Development

ChurchCRM Development Guide

Welcome to ChurchCRM development! This guide will help you set up a complete development environment and start contributing to the project.

Quick Start - GitHub Codespaces (Easiest!)

GitHub Codespaces is the recommended way to develop ChurchCRM. Everything is automatically set up for you:

Using GitHub Codespaces

1. Go to ChurchCRM GitHub Repository
2. Click "Code" → "Codespaces" → "Create codespace on master"
3. Wait 2-3 minutes for automatic setup
4. Code is ready immediately! You can edit files and run builds
5. When ready to test the application: Run npm run docker:dev:start
6. Access the app at http://localhost (login: admin/changeme)

What's automatically installed:

• ✅ PHP 8.2+
• ✅ Node.js 22 with all dependencies
• ✅ Git & Git LFS
• ✅ Docker support
• ✅ VS Code extensions (PHP IntelliSense, Copilot, Xdebug, etc.)
• ✅ Frontend & backend dependencies already built

Your devcontainer includes:

• All required PHP extensions (bcmath, curl, gd, gettext, intl, json, mbstring, mysqli, opcache, soap, sodium, xml, zip)
• Pre-configured VS Code settings and extensions
• Docker port forwarding (80, 3306, 8025, 8088)
• Automatic initialization script

For detailed devcontainer information, see Development Container Setup.

Alternative: VS Code Dev Containers (Local)

If you prefer to develop locally with VS Code:

1. Install VS Code from code.visualstudio.com
2. Install "Dev Containers" extension in VS Code (search in Extensions)
3. Clone the repository: git clone https://github.com/ChurchCRM/CRM.git
4. Open the folder in VS Code
5. Click the "Reopen in Container" button that appears
6. Wait for setup to complete (~2-3 minutes)
7. Run npm run docker:dev:start when ready to test

Same automatic setup as Codespaces - everything is pre-configured!

Manual Development Setup (Not Recommended)

If you need to develop outside containers, follow these steps:

Prerequisites (Manual Setup Only)

1. Git: Installation guide
2. PHP 8.2+: See System Requirements
3. Node.js 22+: nodejs.org
4. Composer: getcomposer.org
5. Docker (optional, needed for testing):
   • Docker for Windows
   • Docker for macOS
   • Docker for Linux

Manual Setup Steps

# 1. Clone repository
git clone https://github.com/ChurchCRM/CRM.git
cd CRM

# 2. Install npm dependencies
npm ci

# 3. Install PHP dependencies
cd src
composer install
cd ..

# 4. Build frontend assets
npm run build:frontend

# 5. When ready to test, start Docker
npm run docker:dev:start

# 6. Access application at http://localhost/

⚠️ Note: Manual setup is more complex. Codespaces/Dev Containers handle all of this automatically and are strongly recommended.

Development Workflow

With Codespaces / Dev Containers (Recommended)

Everything is automatically ready after setup!

# 1. Immediately available (no Docker needed for builds):
npm run build              # Full build (PHP + frontend)
npm run build:frontend     # Rebuild JS/CSS only
npm run build:php          # Update PHP dependencies

# 2. When ready to test the application:
npm run docker:dev:start   # Start MariaDB, Apache, MailHog
npm run docker:dev:stop    # Stop services
npm run docker:dev:logs    # View service logs

# 3. Application is then available at:
# - Main app: http://localhost/
# - Email testing: http://localhost:8025/
# - Database admin: http://localhost:8088/
# - Login: admin / changeme

Typical Development Cycle

1. Code Changes: Edit files in VS Code
2. Frontend Changes: Run npm run build:frontend (rebuilds CSS/JS)
3. Refresh Browser: See changes immediately
4. Database Access: Use Adminer at http://localhost:8088/
5. Email Testing: Check MailHog at http://localhost:8025/

Making Changes

1. Code Changes: Edit files in your local repository
2. Build Assets: Run npm run build:frontend to rebuild CSS/JS assets
3. View Changes: Refresh http://localhost/ to see your changes
4. Database Access: Use http://localhost:8088/ (adminer) for database management

Key npm Scripts

# Build and deployment
npm run deploy              # Main build command (CSS, JS, PHP dependencies)
npm run composer-install    # Install PHP dependencies only
npm run orm-gen             # Generate ORM models from database schema

# Docker development
npm run docker:dev:start    # Start development containers
npm run docker:dev:stop     # Stop development containers  
npm run docker:dev:logs     # View container logs
npm run docker:dev:login-web # SSH into web container

# Testing
npm run test               # Run Cypress end-to-end tests
npm run docker:test:start  # Start testing environment
npm run docker-test-stop   # Stop testing environment

# Localization
npm run locale:audit       # Check translation completeness
npm run locale:download    # Download latest translations
npm run locale:term-extract # Extract terms for translation

After Development Setup

Once your development environment is running, you'll need to complete initial setup:

Default Credentials

• Username: admin
• Password: changeme

Important: Change this password immediately after first login for security.

First-Time Setup

1. Access ChurchCRM

   • If using Codespaces: Open the forwarded port link (port 80)
   • If using Dev Containers: Visit http://localhost/

2. Login with admin / changeme

3. Change Password

   • You'll be prompted to change your password on first login
   • Set a strong password for your development account

4. Configure Church Information (Optional for development)

   • Go to System Settings to configure your church details
   • This helps personalize the interface but is optional for development work

5. Test Email Integration (Optional)

   • MailHog is running on port 8025 for testing email functionality
   • Outgoing emails are captured and can be viewed at http://localhost:8025

Next Development Steps

• Read First-Run Configuration Items for production setup
• Review Features Overview to understand ChurchCRM capabilities
• Check Database Structure to understand the data model
• Explore Code Functional Reference for API information

Technology Stack

Frontend

• Framework: AdminLTE (Bootstrap-based admin theme)
• CSS: SASS compilation to churchcrm.min.css
• JavaScript: jQuery, plus React/TypeScript for newer components
• Build Tools: Grunt (task runner) + Webpack (React components)

Backend

• Language: PHP (see System Requirements for details)
• Framework: Slim Framework v4 (MVC architecture)
• Database ORM: Propel (with auto-generated models)
• Database: MySQL or MariaDB (see System Requirements for details)

Testing

• End-to-End: Cypress (browser automation)
• Integration: PHP-based tests
• Environment: Docker containers for consistent testing

Architecture Guidelines

For New APIs and Pages

Use Slim MVC architecture:

• Models: Propel ORM entities in src/ChurchCRM/model/
• Views: PHP templates in src/templates/ or React components in react/
• Controllers: Slim route handlers in src/api/routes/ or src/v2/routes/

For UI Components

Follow AdminLTE design principles:

• Use existing AdminLTE components when possible
• Create modular, responsive designs
• Add custom styling in SASS files under src/skin/scss/

For JavaScript

• Legacy code: jQuery-based, located in src/skin/js/
• New components: React/TypeScript, located in react/
• Internationalization: Use i18next for user-facing text

Database Development

Schema Changes

1. Edit schema in src/mysql/upgrade.json
2. Run npm run orm-gen to regenerate Propel models
3. Test changes with Docker database container

Sample Data

• Development database includes sample families, people, and events
• Reset database: Use adminer or API endpoint /api/database/reset

Contributing Guidelines

Before Starting

1. Read the Contributing Guide
2. Join the developer chat at Matrix
3. Look for good first issue labels

Development Process

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Submit a pull request with clear description

Code Standards

• Follow PSR-12 for PHP code
• Use consistent indentation and naming conventions
• Add comments for complex logic
• Update documentation for user-facing changes

Debugging & Getting Support

Troubleshooting Development Issues

Container or Setup Problems

• Container won't start: Check npm run docker:dev:logs for error messages
• Port conflicts: Ensure ports 80, 3306, 8025, 8088 are available
• Git LFS errors: Run git lfs install && git lfs pull to download large files
• npm/Composer errors: Delete node_modules/ and vendor/ folders, then run npm ci && composer install

Application Errors

• White page or 500 errors: Check src/logs/error.log for PHP errors
• Database connection issues: Verify credentials, check npm run docker:dev:logs for database errors
• Email not sending: MailHog captures emails at http://localhost:8025/
• Assets not loading: Run npm run build:frontend to rebuild frontend assets

Debugging Tools

• Database: Access via Adminer at http://localhost:8088/ (MySQL/MariaDB)
• PHP Logs: Located in src/logs/ - check error.log and access.log
• Container Logs: npm run docker:dev:logs shows all container output
• Xdebug: Pre-configured in dev container for step debugging via VS Code

Getting Help

Developer Resources

• FAQs - Frequently asked questions about ChurchCRM
• Troubleshooting Guide - Common problems and solutions
• 500 Error Solutions - Server error troubleshooting

Community Support

• Matrix Chat - Real-time developer discussions and questions
• GitHub Issues - Report bugs, request features, or ask technical questions
• GitHub Discussions - General questions and community support

Contributing & Improving ChurchCRM

• Contributing Guide - How to contribute code and documentation
• Issue Labels - Find help wanted or good first issue to start contributing

Advanced Development

Container Development

For development inside containers:

# SSH into web container
npm run docker-dev-login-web

# Inside container
cd /home/ChurchCRM
npm run deploy
chmod a+rwx src/logs  # Fix log permissions

Building for Production

# Generate production assets
npm run deploy

# Create release package
grunt compress

Debugging

• PHP Errors: Check src/logs/ for application logs
• Container Logs: Use npm run docker:dev:logs
• Database: Use adminer at http://localhost:8088/
• Email Testing: Check http://localhost:8025/ for sent emails

Resources

Documentation

• Automated Testing - Cypress end-to-end testing guide
• Code Functional Reference
• Database Structure
• Localization System

External Resources

• AdminLTE Documentation
• Slim Framework Docs
• Propel ORM Guide
• Cypress Testing

Community

• Matrix Chat - Developer discussions
• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - General questions

In the ChurchCRM source directory run:

npm install

Note: if you are running Apple Silicon (M1/M2 processor) you will get errors with node-sass.

For example:

npm ERR! Binary has a problem: Error: dlopen(/path/to/ChurchCRM/node_modules/node-sass/vendor/darwin-arm64-120/binding.node, 0x0001):
         tried:
         '/path/to/ChurchCRM/node_modules/node-sass/vendor/darwin-arm64-120/binding.node' (not a mach-o file),
         '/System/Volumes/Preboot/Cryptexes/OS/path/to/ChurchCRM/node_modules/node-sass/vendor/darwin-arm64-120/binding.node' (no such file),
         '/path/to/ChurchCRM/node_modules/node-sass/vendor/darwin-arm64-120/binding.node' (not a mach-o file)'

If this happens, simply execute the following (fix courtesy of "m_kos" at Stack Overflow):

npm install node-sass@npm:sass{.sh} (requires npm >6.9)

Start the application and test it locally:

1. npm run deploy{.sh}
2. npm run docker:test:start{.sh}
3. Open your browser and visit http://localhost/ and log in with admin/changeme

Make Code Change

Download an IDE

• PHP Storm is a great but paid
• Visual Studio Code is a free IDE