Skip to content

Development

Jump to bottom
George Dawoud edited this page Nov 18, 2025 · 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.

Development QuickStart Video

Quick Start

Prerequisites

  1. Install Git: Follow the Git installation guide

  2. Install Node.js 20+: Download from nodejs.org

  3. Install Docker: Download from the official website:

Development Setup

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

# 2. Install dependencies  
npm ci
npm run deploy

# 3. Start Docker development environment
docker compose -f "docker/docker-compose.test-php8-apache.yaml" up -d --build

# 4. Access the application
# Open http://localhost/ in your browser
# Login: admin / changeme

Development Workflow

Making Changes

  1. Code Changes: Edit files in your local repository
  2. Build Assets: Run npm run deploy 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

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

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