Skip to content

Commit d763edd

Browse files
DawoudIODawoudIO
authored
Add DDEV local development environment support (#8089)
Adds a fully automated DDEV-based local development path so contributors can get a running ChurchCRM instance in two commands, without managing Docker Compose directly. ## New files - **`.ddev/config.yaml`** — PHP 8.4, MariaDB 10.11, Node 24, Apache-FPM. Post-start hooks auto-configure `Config.php`, chmod `src/logs/`, run `composer install` (idempotent), and import the demo database on first start. - **`.ddev/Config.ddev.php`** — ChurchCRM config template using DDEV's default `db`/`db`/`db` credentials and `https://churchcrm.ddev.site/` as the app URL. - **`.ddev/php/churchcrm.ini`** — PHP limits (512M memory, 64M upload, 120s execution). - **`.ddev/commands/web/setup-churchcrm`** — Custom `ddev setup-churchcrm` command; runs `npm ci` + `npm run build:frontend` inside the container. Kept separate from post-start to avoid slowing every `ddev start`. - **`.ddev/.gitignore`** — Excludes DDEV user-specific files (`.env`, `auth.json`, DB snapshots). ## Updated - **`CONTRIBUTING.md`** — DDEV added as a third Quick Start option alongside Codespaces and Dev Containers; full DDEV Setup section with service URLs, daily workflow, and troubleshooting table. ## Developer workflow ```bash git clone https://github.com/ChurchCRM/CRM.git churchcrm && cd churchcrm ddev start # pulls images, configures Config.php, imports demo DB (~2 min) ddev setup-churchcrm # npm ci + webpack build (~2 min) ddev launch # opens https://churchcrm.ddev.site → admin / changeme ``` Mailpit (email testing) is available at `https://churchcrm.ddev.site:8025` with no additional setup. <!-- START COPILOT CODING AGENT TIPS --> --- ✨ Let Copilot coding agent [set things up for you](https://github.com/ChurchCRM/CRM/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.
2 parents 620d4d6 + d3c2700 commit d763edd

File tree

6 files changed

+212
-0
lines changed

6 files changed

+212
-0
lines changed

‎.ddev/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# DDEV auto-generated gitignore — do not delete
2+
# User-specific settings that should not be shared
3+
.env
4+
.env.*
5+
auth.json
6+
import-db
7+
db_snapshots/
8+
sequelpro.spf
9+
.DS_Store

‎.ddev/Config.ddev.php‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<?php
2+
/*******************************************************************************
3+
*
4+
* filename : .ddev/Config.ddev.php
5+
* website : https://churchcrm.io
6+
* description : ChurchCRM configuration for DDEV local development
7+
*
8+
* This file is copied to src/Include/Config.php automatically by the
9+
* DDEV post-start hook defined in .ddev/config.yaml.
10+
*
11+
******************************************************************************/
12+
13+
// DDEV database connection — default DDEV MariaDB credentials
14+
$sSERVERNAME = 'db';
15+
$dbPort = '3306';
16+
$sUSER = 'db';
17+
$sPASSWORD = 'db';
18+
$sDATABASE = 'db';
19+
20+
// Root path — top-level installation (no subdirectory)
21+
$sRootPath = '';
22+
23+
// Lock URL enforcement disabled for local development
24+
$bLockURL = false;
25+
26+
// Primary URL — matches the DDEV project name 'churchcrm'
27+
// Access both http:// and https:// via DDEV's built-in router
28+
$URL[0] = 'https://churchcrm.ddev.site/';
29+
$URL[1] = 'http://churchcrm.ddev.site/';
30+
31+
// PHP error reporting for development
32+
error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED);
33+
34+
//
35+
// SETTINGS END HERE. DO NOT MODIFY BELOW THIS LINE
36+
//
37+
// Absolute path must be specified since this file is called
38+
// from scripts located in other directories
39+
require_once dirname(__FILE__).DIRECTORY_SEPARATOR.'LoadConfigs.php';

‎.ddev/commands/web/setup-churchcrm‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/usr/bin/env bash
2+
3+
## Description: Install Node packages and build ChurchCRM frontend assets
4+
## Usage: setup-churchcrm
5+
## Example: "ddev setup-churchcrm"
6+
## ExecRaw: false
7+
## Flags: []
8+
## AutocompleteTerminators: []
9+
## CanRunGlobally: false
10+
## OSTypes: []
11+
12+
set -e
13+
14+
echo ""
15+
echo "========================================================"
16+
echo " ChurchCRM DDEV Setup"
17+
echo "========================================================"
18+
echo ""
19+
echo "Installing Node.js dependencies..."
20+
cd /var/www/html
21+
npm ci
22+
echo "✓ Node.js dependencies installed"
23+
echo ""
24+
echo "Building frontend assets (JS/CSS)..."
25+
npm run build:frontend
26+
echo "✓ Frontend assets built"
27+
echo ""
28+
echo "========================================================"
29+
echo " Setup Complete!"
30+
echo "========================================================"
31+
echo ""
32+
echo "ChurchCRM is ready at: https://churchcrm.ddev.site"
33+
echo " Login: admin / changeme"
34+
echo " Mailpit: https://churchcrm.ddev.site:8025"
35+
echo ""
36+
echo "Useful commands:"
37+
echo " ddev describe — show service URLs and status"
38+
echo " ddev logs — view web server logs"
39+
echo " ddev ssh — open a shell in the web container"
40+
echo " ddev mysql — open a MySQL prompt"
41+
echo " ddev import-db --file=demo/ChurchCRM-Database.sql — re-import demo DB"
42+
echo ""

‎.ddev/config.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: churchcrm
2+
type: php
3+
docroot: src
4+
php_version: "8.4"
5+
webserver_type: apache-fpm
6+
database:
7+
type: mariadb
8+
version: "10.11"
9+
nodejs_version: "24"
10+
11+
# DDEV router settings
12+
router_http_port: "80"
13+
router_https_port: "443"
14+
use_dns_when_possible: true
15+
16+
# Environment variables available in the web container
17+
web_environment:
18+
- COMPOSER_ALLOW_SUPERUSER=1
19+
- NODE_ENV=development
20+
21+
# Mailpit (email testing) is built into DDEV
22+
# Access at: https://churchcrm.ddev.site:8025 OR run: ddev mailpit
23+
24+
# Hooks run automatically after `ddev start`
25+
hooks:
26+
post-start:
27+
# Copy DDEV-specific Config.php if the source exists and the destination doesn't
28+
- exec: "[ -f /var/www/html/.ddev/Config.ddev.php ] && [ ! -f /var/www/html/src/Include/Config.php ] && cp /var/www/html/.ddev/Config.ddev.php /var/www/html/src/Include/Config.php || true"
29+
# Ensure logs directory exists and is writable
30+
- exec: "mkdir -p /var/www/html/src/logs && chmod -R 777 /var/www/html/src/logs"
31+
# Install PHP (Composer) dependencies if not already present
32+
- exec: "[ -f /var/www/html/src/vendor/autoload.php ] || (cd /var/www/html/src && composer install --no-dev --no-interaction)"
33+
# Import demo database on first start (when the database has no tables yet)
34+
- exec: "mysql -udb -pdb -hdb db -e 'SHOW TABLES' | grep -q . && echo 'Database already populated.' || (echo 'Importing ChurchCRM demo database...' && mysql -udb -pdb -hdb db < /var/www/html/demo/ChurchCRM-Database.sql && echo 'Demo database imported.')"

‎.ddev/php/churchcrm.ini‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[PHP]
2+
; ChurchCRM PHP settings for DDEV development environment
3+
memory_limit = 512M
4+
upload_max_filesize = 64M
5+
post_max_size = 64M
6+
max_execution_time = 120

‎CONTRIBUTING.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,19 @@ The project welcomes, and depends on, contributions from developers and users in
2929
3. Click "Reopen in Container" when prompted
3030
4. Wait for setup to complete
3131

32+
**🔧 DDEV (Local Docker-based):**
33+
1. Install [DDEV](https://ddev.readthedocs.io/en/stable/users/install/ddev-installation/) and [Docker](https://docs.docker.com/desktop/)
34+
2. Clone the repo and run:
35+
```bash
36+
git clone https://github.com/ChurchCRM/CRM.git churchcrm
37+
cd churchcrm
38+
ddev start
39+
ddev setup-churchcrm
40+
```
41+
3. Open [https://churchcrm.ddev.site](https://churchcrm.ddev.site) and log in with `admin`/`changeme`
42+
43+
See [DDEV Setup](#ddev-setup) below for full details and troubleshooting.
44+
3245
### Manual Setup
3346

3447
If you prefer manual setup or the automatic options don't work:
@@ -73,6 +86,75 @@ npm run docker:test:restart # Restart test containers
7386
npm run docker:test:rebuild # Full rebuild (remove volumes, rebuild images)
7487
```
7588

89+
### DDEV Setup
90+
91+
[DDEV](https://ddev.readthedocs.io/en/stable/) is a Docker-based local development environment that gives you PHP, MariaDB, Node.js, HTTPS, and email testing with a single command — no manual port management or Docker Compose knowledge required.
92+
93+
#### Prerequisites
94+
95+
- [Docker Desktop](https://docs.docker.com/desktop/) (or Docker Engine + Compose v2 on Linux)
96+
- [DDEV](https://ddev.readthedocs.io/en/stable/users/install/ddev-installation/) v1.22+
97+
98+
#### Quick Start
99+
100+
```bash
101+
# 1. Clone the repository (use your fork URL for contributions)
102+
git clone https://github.com/ChurchCRM/CRM.git churchcrm
103+
cd churchcrm
104+
105+
# 2. Start DDEV (first run takes ~2 min to pull images)
106+
# This automatically:
107+
# - Configures Config.php with DDEV database credentials
108+
# - Installs Composer (PHP) dependencies
109+
# - Imports the demo database
110+
ddev start
111+
112+
# 3. Install Node packages and build frontend assets (~2 min)
113+
ddev setup-churchcrm
114+
115+
# 4. Open the app
116+
ddev launch
117+
```
118+
119+
Login credentials: **admin** / **changeme**
120+
121+
#### Service URLs
122+
123+
| Service | URL | Notes |
124+
|---------|-----|-------|
125+
| ChurchCRM | https://churchcrm.ddev.site | Main application |
126+
| Mailpit | https://churchcrm.ddev.site:8025 | Catch-all email testing |
127+
| MySQL | `ddev mysql` | Interactive prompt |
128+
129+
#### Daily Development Workflow
130+
131+
```bash
132+
ddev start # Start all services
133+
ddev stop # Stop all services (preserves database)
134+
ddev ssh # Shell into the web container
135+
ddev mysql # MySQL prompt (database: db, user: db, password: db)
136+
ddev logs # Tail web server logs
137+
ddev exec npm run build:frontend # Rebuild JS/CSS inside the container
138+
ddev exec npm run build:php # Update Composer dependencies
139+
ddev import-db --file=demo/ChurchCRM-Database.sql # Reset demo database
140+
```
141+
142+
#### DDEV Troubleshooting
143+
144+
| Problem | Solution |
145+
|---------|----------|
146+
| `ddev start` fails | Ensure Docker is running: `docker info` |
147+
| Port 80/443 in use | DDEV uses its own router; conflicts are rare. Run `ddev poweroff && ddev start` |
148+
| Config.php not created | Run `ddev exec cp /var/www/html/.ddev/Config.ddev.php /var/www/html/src/Include/Config.php` |
149+
| Blank page / 500 error | Check logs: `ddev logs` or `ddev exec cat /var/www/html/src/logs/$(date +%Y-%m-%d)-php.log` |
150+
| Database empty | Re-import: `ddev import-db --file=demo/ChurchCRM-Database.sql` |
151+
| Node packages missing | Run `ddev setup-churchcrm` |
152+
| Composer packages missing | Run `ddev exec 'cd /var/www/html/src && composer install --no-dev'` |
153+
154+
Full DDEV documentation: https://ddev.readthedocs.io
155+
156+
---
157+
76158
### User Interface using AdminLTE
77159

78160
ChurchCRM utilizes the AdminLTE framework for its user interface. Follow these guidelines when working on the UI:

0 commit comments

Comments
 (0)