Skip to content

Development

Jump to bottom
George Dawoud edited this page Jan 28, 2026 · 27 revisions

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 Links

New Developer? Returning Developer? Ready to Contribute?
Quick Start → Development Cycle → PR Checklist →
First-Time Setup → npm Scripts → Testing Guide →
Tech Stack → Debugging → Contributing →

Development QuickStart Video

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):

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

All available scripts are defined in package.json. Here's a comprehensive reference:

Build & Deploy

Script Description
npm run build Build PHP dependencies + frontend assets
npm run build:frontend Build frontend only (JS/CSS)
npm run build:php Install PHP dependencies via Composer
npm run build:webpack Run webpack bundler only
npm run build:orm Regenerate Propel ORM models
npm run build:signatures Generate file signatures for integrity checks
npm run build:php:validate Validate PHP syntax for all files
npm run deploy Full build + generate signatures (recommended)
npm run deploy:clean Clean install + full deploy
npm run package Create release package (.zip)
npm run clean Remove all generated files and dependencies

Docker - Development

Script Description
npm run docker:dev:start Start dev containers (web, database, mailhog)
npm run docker:dev:stop Stop dev containers
npm run docker:dev:logs View container logs (follow mode)
npm run docker:dev:login:web Shell into web container
npm run docker:dev:login:db Shell into database container

Docker - Testing

Script Description
npm run docker:test Start test containers
npm run docker:test:stop Stop test containers
npm run docker:test:down Stop and remove test containers + volumes
npm run docker:test:rebuild Full rebuild of test containers
npm run docker:test:restart Restart all test containers
npm run docker:test:restart:db Restart database only (refresh schema)
npm run docker:test:logs View test container logs
npm run docker:test:login:web Shell into test web container
npm run docker:test:login:db Shell into test database container
npm run docker:test:subdir Start test with subdirectory config
npm run docker:test:reset Reset CI containers (down + rebuild)

Docker - CI/CD

Script Description
npm run docker:ci:start Start CI containers (GitHub Actions)
npm run docker:ci:down Stop and remove CI containers

Testing (Cypress)

Script Description
npm run test Run all Cypress tests (headless)
npm run test:ui Open Cypress interactive UI
npm run test:fast Run tests with headed Chrome (no exit)
npm run test:api Run API tests only
npm run test:ui-only Run UI tests only (no API tests)

Localization

Script Description
npm run locale:build Extract and build locale files
npm run locale:audit Check translation completeness
npm run locale:download Download translations from POEditor
npm run locale:variants Populate language variants
npm run locale:missing Build missing translation entries
npm run locale:lint Lint locale files for issues

Code Quality

Script Description
npm run format:web Format code with Prettier
npm run audit Fix npm security vulnerabilities

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

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 fix/issue-123-description
  3. Make your changes and test thoroughly
  4. Run tests: npm run test (required before PR)
  5. Submit a pull request with clear description

Code Standards

  • Follow PSR-12 for PHP code
  • Use Propel ORM for all database access (no raw SQL)
  • Use Bootstrap 4.6.2 CSS classes (not Bootstrap 5)
  • Wrap all UI text with gettext() (PHP) or i18next.t() (JS)
  • Add comments for complex logic
  • Update documentation for user-facing changes

📘 Full Standards: See .github/copilot-instructions.md for complete coding standards and patterns.

GitHub Actions & CI/CD

ChurchCRM uses GitHub Actions to automate quality checks. Understanding these helps you submit successful PRs.

What Happens When You Submit a PR

When you open a Pull Request, these automated checks run:

Workflow What It Checks Must Pass?
Build, Test and Package Builds app, runs Cypress tests, creates release package ✅ Yes
CI — Typecheck & Lint TypeScript type checking, ESLint for React code ✅ Yes
Security Analysis (DevSkim) Scans for security vulnerabilities in code ⚠️ Review

Build, Test and Package Workflow

This is the main CI workflow (build-test-package.yml):

  1. Install Dependencies - npm ci and Composer install
  2. Build Application - npm run package (frontend + backend)
  3. Validate PHP Syntax - Checks all PHP files for syntax errors
  4. Start Docker - Spins up test containers (web, database, mailhog)
  5. Run Cypress Tests - Full end-to-end test suite
  6. Create Artifact - Builds ChurchCRM-{version}.zip package

If tests fail:

  • Cypress screenshots/videos are uploaded as artifacts
  • Download cypress-artifacts-{run_id} from the workflow run
  • Check cypress/logs/ for detailed error messages

CI — Typecheck & Lint Workflow

This workflow (ci.yml) ensures TypeScript and React code quality:

  • TypeScript Check: npx tsc --noEmit - Catches type errors
  • ESLint: npx eslint "react/**/*.{js,jsx,ts,tsx}" - Code style

Run locally before pushing:

npx tsc --noEmit --pretty        # TypeScript check
npx eslint "react/**/*.{js,jsx,ts,tsx}"  # Lint check

Security Analysis Workflow

The DevSkim security scanner (security-devskim.yml) runs on:

  • Every push to master and develop
  • Every PR to master
  • Weekly scheduled scans

It checks for common security issues like:

  • SQL injection vulnerabilities
  • XSS (cross-site scripting) risks
  • Hardcoded credentials
  • Insecure cryptographic patterns

Other Automated Workflows

Workflow Purpose When It Runs
Locale Generate App Terms Extracts translatable strings from code Push to master (src/ changes)
Auto-comment on Issues Posts helpful templates on new issues New issue opened
Manage Stale Issues Marks/closes inactive issues and PRs Daily at 1:30 AM UTC

Pull Request Checklist

Before submitting your PR, verify:

Required

  • Branch naming: fix/issue-123-description or feature/description
  • Tests pass locally: Run npm run test
  • TypeScript compiles: Run npx tsc --noEmit
  • Linked to issue: PR description includes Fixes #123

Code Quality

  • Propel ORM used (no raw SQL or RunQuery())
  • Bootstrap 4.6.2 classes (not Bootstrap 5)
  • UI text wrapped with gettext() or i18next.t()
  • No alert() calls - use window.CRM.notify()
  • Asset paths use SystemURLs::getRootPath()

For UI Changes

  • Screenshot or GIF included in PR
  • Responsive design tested
  • Cypress UI test added/updated

For API Changes

  • API test added in cypress/e2e/api/
  • Error responses use SlimUtils::renderErrorJSON()
  • Documentation updated if needed

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

Community Support

Contributing & Improving ChurchCRM

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

Resources

Documentation

External Resources

Community

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

Website | Demo | GitHub Discussions | Report Issues | Twitter @church_crm

🚀 Getting Started

👥 For End Users

Day-to-day usage of ChurchCRM

🔧 For Administrators

Server management & configuration

👨‍💻 For Developers

Contributing to ChurchCRM

📚 Help & Reference

Clone this wiki locally