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

Prerequisites

1. Install Git: Follow the Git installation guide

   • Alternative: Use GitHub Desktop for a graphical interface

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

3. Install Docker: Download from the official website:

   • Docker for Windows
   • Docker for macOS
   • Docker for Linux

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 8.1+
• Framework: Slim Framework v4 (MVC architecture)
• Database ORM: Propel (with auto-generated models)
• Database: MariaDB/MySQL 5.5+

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

• 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

• 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