docs(docker): add nginx + PHP-FPM reference configuration to fix login redirect loop (#8207)

Copilot · DawoudIO · web-flow · commit 6e46512e357f · 2026-03-07T08:20:33.000-08:00
ChurchCRM users deploying with nginx + PHP-FPM hit an infinite redirect loop (`/session/begin → /session/begin`) because nginx routes everything to the root `index.php`, which redirects unauthenticated users to `/session/begin` — which also hits `index.php` — and so on. The loop happens because ChurchCRM has **9 independent Slim 4 entry points** (one per subdirectory). Apache resolves this automatically via per-directory `.htaccess` mod_rewrite rules; nginx requires explicit `location` blocks per sub-app. ## Changes - **`docker/nginx/default.conf`** — nginx server block with `location ^~` blocks routing each sub-application prefix to its own `index.php`. Regex locations for static assets and PHP, security denies for `/logs`, `/tmp_attach`, and dotfiles. Commented subdirectory-install variant at the bottom. ```nginx # Each Slim sub-app gets its own routing block location ^~ /session { try_files $uri /session/index.php$is_args$args; location ~ \.php$ { fastcgi_pass php-fpm:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } } # ... repeated for /api, /v2, /admin, /finance, /kiosk, /plugins, /external, /setup ``` - **`docker/Dockerfile.churchcrm-fpm-php8`** — PHP-FPM multi-stage image (`prod` / `dev`) with all required extensions (`bcmath`, `gd`, `intl`, `mysqli`, `pdo_mysql`, `sodium`, `zip`, …). Mirrors the existing `Dockerfile.churchcrm-apache-php8`. - **`docker/docker-compose.nginx.yaml`** — Self-contained Compose reference (MariaDB + PHP-FPM + nginx). Not wired into CI; intended as a starting point for self-hosted deployments. - **`docker/README.md`** — Added intro table distinguishing dev/CI (Apache) from self-hosted (nginx), plus a new section explaining the routing architecture, the loop pitfall, quick-start, and customisation notes.  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>Question: Docker Installation Challenges</issue_title> > <issue_description>## How can we help? > > Please share briefly: > - **What you're trying to do**: I'm trying to install ChurchCRM into an environment that is otherwise manged through docker-compose. Since ChurchCRM doesn't have a dedicated set of docker containers, I've been attempting to install it using a combination of nginx, mariadb, and a custom PHP dockerfile with all the needed PHP extensions. I've made good progress (and I'm looking to share my procedures once I'm successful), but I'm running into an issue just a few feet from the finish line. > > Specifically, I'm getting a login loop after finishing the initial setup wizard, 'too many redirects'. > > From Claude: > This is the key finding! Look at what's happening: > > ✅ Cookie IS being set — CRM-xxxxx=yyy — so session saving is working now > ✅ Only one redirect with curl+cookies — not an infinite loop > ❌ It's redirecting /session/begin → /session/begin — redirecting to itself! > > > - **What you've tried**: Steps or settings you've attempted > This occurs after attempting to go to http://churchcrm.example.com, once the setup wizard has been completed. > > - **Expected behavior**: What you expected to happen > Getting a login prompt =) > > Add environment details only if relevant (version, hosting type, etc.). > > My Docker Compose: > > ```version: "3.9" > > services: > > churchcrm-mariadb: > image: mariadb:11 > container_name: churchcrm-mariadb > restart: unless-stopped > environment: > MYSQL_ROOT_PASSWORD: 12345 > MYSQL_DATABASE: churchcrm > MYSQL_USER: churchcrm > MYSQL_PASSWORD: 12345 > volumes: > - churchcrm-mariadb:/var/lib/mysql > > churchcrm-php: > image: php84-custom1 > container_name: churchcrm-php > restart: unless-stopped > volumes: > - churchcrm-php:/usr/local/etc/php/conf.d > - churchcrm-www:/var/www/html > depends_on: > - churchcrm-mariadb > > churchcrm-nginx: > image: nginx:stable-alpine > container_name: churchcrm-nginx > restart: unless-stopped > ports: > - "80:80" > volumes: > - churchcrm-www:/var/www/html > - churchcrm-nginx:/etc/nginx/ > depends_on: > - churchcrm-php > > # ========================= > # PHPMYADMIN > # ========================= > > phpmyadmin: > image: phpmyadmin/phpmyadmin:latest > container_name: churchcrm-phpmyadmin > ports: > - "7381:80" > environment: > - PMA_HOST=churchcrm-mariadb > - PMA_PORT=3306 > - TZ=America/New_York > restart: ${RESTART_POLICY} > > volumes: > churchcrm-php: > churchcrm-nginx: > churchcrm-www: > churchcrm-mariadb: > ``` > > My Dockerfile for my php container: > > ```FROM php:8.4-fpm > > RUN apt-get update && apt-get install -y \ > libzip-dev \ > libicu-dev \ > libpng-dev \ > libjpeg-dev \ > libfreetype6-dev \ > libxml2-dev \ > libonig-dev \ > unzip \ > git \ > curl \ > && docker-php-ext-configure gd --with-freetype --with-jpeg \ > && docker-php-ext-install \ > pdo_mysql \ > mysqli \ > intl \ > gd \ > zip \ > mbstring \ > xml \ > opcache \ > gettext \ > && apt-get clean > ``` > > My php override file: > > ``` > session.save_path = /tmp > upload_max_filesize = 20M > post_max_size = 25M > memory_limit = 256M > ``` > > My nginx config: > > ``` > server { > listen 80; > server_name crm.example.org; > root /var/www/html; > index index.php index.html; > client_max_body_size 100M; > > location ^~ /setup { > try_files $uri $uri/ /setup/index.php$is_args$args; > > location ~ \.php$ { > include fastcgi_params; > fastcgi_pass churchcrm-php:9000; > fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; > fastcgi_index index.php; > } > } > > location / { > try_files $uri $uri/ /index.php?$query_string; > } > > location ~ \.php$ { > include fastcgi_params; > fastcgi_pass churchcrm-php:9000; > fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; > fastcgi_index index.php; > } > > location ~ /\.ht { > deny all; > } > } > ``` > > ...I think that's everything =)</issue_description> > > <agent_instructions>review the docker setup used for dev/ci/test and recommend a path forward </agent_instructions> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details>  - Fixes #8200  --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey). --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: DawoudIO <554959+DawoudIO@users.noreply.github.com> Co-authored-by: George Dawoud <george@dawouds.com>
diff --git a/docker/Dockerfile.churchcrm-fpm-php8 b/docker/Dockerfile.churchcrm-fpm-php8
@@ -0,0 +1,94 @@
+# PHP-FPM Dockerfile for ChurchCRM (nginx deployments)
+#
+# Use this image with the nginx configuration in docker/nginx/default.conf.
+# For the Apache-based development/CI setup, see Dockerfile.churchcrm-apache-php8.
+#
+# Build:
+#   docker build -f Dockerfile.churchcrm-fpm-php8 -t churchcrm/crm:php8-fpm .
+#
+# Required PHP extensions for ChurchCRM:
+#   bcmath, curl, exif, gd, gettext, iconv, intl, mbstring, mysqli,
+#   opcache, pdo_mysql, sodium, xml, zip
+
+FROM php:8-fpm AS base
+LABEL maintainer="ChurchCRM"
+
+EXPOSE 9000
+
+# Install system dependencies required by PHP extensions
+RUN apt-get update && \
+    apt-get install -y \
+        libcurl4-openssl-dev \
+        libfreetype6-dev \
+        libicu-dev \
+        libjpeg-dev \
+        libonig-dev \
+        libpng-dev \
+        libxml2-dev \
+        libzip-dev \
+        gettext \
+        locales \
+        locales-all \
+        unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install and configure PHP extensions
+RUN docker-php-ext-configure gd --with-freetype --with-jpeg && \
+    docker-php-ext-install -j$(nproc) \
+        bcmath \
+        curl \
+        exif \
+        gd \
+        gettext \
+        iconv \
+        intl \
+        mbstring \
+        mysqli \
+        opcache \
+        pdo_mysql \
+        xml \
+        zip
+
+# Sodium is bundled with PHP 7.2+ but needs to be enabled
+RUN docker-php-ext-enable sodium
+
+# Configure PHP settings
+RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" && \
+    sed -i 's/^upload_max_filesize.*$/upload_max_filesize = 2G/g' $PHP_INI_DIR/php.ini && \
+    sed -i 's/^post_max_size.*$/post_max_size = 2G/g' $PHP_INI_DIR/php.ini && \
+    sed -i 's/^memory_limit.*$/memory_limit = 256M/g' $PHP_INI_DIR/php.ini && \
+    sed -i 's/^max_execution_time.*$/max_execution_time = 120/g' $PHP_INI_DIR/php.ini
+
+
+# Production stage - minimal runtime
+FROM base AS prod
+
+
+# Dev stage - includes build tools for local development inside the container
+FROM base AS dev
+
+# Install development tools
+RUN apt-get update && \
+    apt-get install -y \
+        git \
+        make \
+        python3 \
+        unzip \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Xdebug for step-debugging
+RUN pecl install xdebug && docker-php-ext-enable xdebug
+
+# Install Composer
+RUN php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && \
+    php composer-setup.php --install-dir=/usr/local/bin --filename=composer && \
+    rm composer-setup.php
+
+# Install NVM + Node.js (needed to run npm run deploy inside the container)
+RUN curl https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh -o /opt/node-install.sh && \
+    chmod a+x /opt/node-install.sh && \
+    /opt/node-install.sh && \
+    rm /opt/node-install.sh
+
+RUN /bin/bash -c "source /root/.nvm/nvm.sh && nvm install 24 && npm install -g node-gyp"
diff --git a/docker/README.md b/docker/README.md
@@ -1,6 +1,18 @@
-Getting Started with Docker for Development
+Getting Started with Docker for ChurchCRM
 ===========================
 
+This directory contains two types of Docker configurations:
+
+| Configuration | Use Case |
+|---------------|----------|
+| `docker-compose.yaml` | Development and testing (Apache + PHP). Used by the automated test suite and local development. |
+| `docker-compose.nginx.yaml` | Self-hosted or production reference (nginx + PHP-FPM). Starting point for your own deployment. |
+
+---
+
+Development & Testing (Apache)
+---
+
 ** THIS DOCKER CONFIGURATION IS INTENDED FOR DEVELOPMENT & TESTING PURPOSES ONLY**
 
 ChurchCRM uses a single `docker-compose.yaml` with profiles to support different environments:
@@ -117,4 +129,74 @@ WEBSERVER_PORT=80
 ADMINER_PORT=8088
 MAILSERVER_PORT=1025
 MAILSERVER_GUI_PORT=8025
-```
+```
+
+---
+
+Self-Hosted / Production (nginx + PHP-FPM)
+---
+
+The `docker-compose.nginx.yaml` and `nginx/default.conf` files provide a reference
+configuration for deploying ChurchCRM with **nginx + PHP-FPM** instead of Apache.
+This is the setup most commonly used in self-hosted environments (reverse-proxy
+stacks, Kubernetes, etc.).
+
+### Why nginx needs explicit routing
+
+ChurchCRM is structured as multiple independent **Slim 4 PHP applications**, each
+in its own subdirectory with its own `index.php` entry point:
+
+| URL prefix | Entry point |
+|------------|-------------|
+| `/session/` | `session/index.php` — login, logout, 2FA |
+| `/api/` | `api/index.php` — REST API |
+| `/v2/` | `v2/index.php` — modern MVC pages |
+| `/admin/` | `admin/index.php` — admin panel |
+| `/finance/` | `finance/index.php` — finance module |
+| `/kiosk/` | `kiosk/index.php` — check-in kiosk |
+| `/plugins/` | `plugins/index.php` — plugin system |
+| `/external/` | `external/index.php` — public integrations |
+| `/setup/` | `setup/index.php` — first-run wizard |
+| `/` | `index.php` — legacy PHP pages |
+
+With **Apache**, each subdirectory's `.htaccess` file automatically routes
+requests to the correct entry point.
+
+With **nginx**, you must explicitly map each URL prefix to its entry point.
+**Routing all requests to the root `index.php`** (a common mistake) causes an
+infinite redirect loop because unauthenticated users are redirected to
+`/session/begin`, but that path also goes to `index.php`, which redirects again.
+
+### Quick start
+
+```bash
+# From the docker/ directory:
+docker compose -f docker-compose.nginx.yaml up -d
+```
+
+Visit `http://localhost/` — you will see the setup wizard on first run.
+
+### Files
+
+| File | Description |
+|------|-------------|
+| `docker-compose.nginx.yaml` | Example Compose file (nginx + PHP-FPM + MariaDB) |
+| `nginx/default.conf` | nginx server block with correct per-subdirectory routing |
+| `Dockerfile.churchcrm-fpm-php8` | PHP-FPM image with all required extensions |
+
+### Customising the nginx config
+
+1. Copy `nginx/default.conf` to your deployment.
+2. Replace `php-fpm:9000` with your PHP-FPM container hostname/port.
+3. Set `root` to the path where ChurchCRM's `src/` contents are served from.
+4. For a **subdirectory install** (e.g. `http://example.com/churchcrm/`):
+   - Set `$sRootPath = '/churchcrm'` in `Include/Config.php`.
+   - Prefix all `location` paths in the nginx config with `/churchcrm`.
+   - See the commented example at the bottom of `nginx/default.conf`.
+
+### Required PHP extensions
+
+`bcmath`, `curl`, `exif`, `gd`, `gettext`, `iconv`, `intl`, `mbstring`, `mysqli`,
+`opcache`, `pdo_mysql`, `sodium`, `xml`, `zip`
+
+The `Dockerfile.churchcrm-fpm-php8` installs all of these.
diff --git a/docker/docker-compose.nginx.yaml b/docker/docker-compose.nginx.yaml
@@ -0,0 +1,75 @@
+# docker-compose.nginx.yaml — Example nginx + PHP-FPM deployment for ChurchCRM
+#
+# This is a REFERENCE CONFIGURATION for self-hosted deployments using nginx +
+# PHP-FPM instead of Apache. It is NOT used by the automated test suite (which
+# uses docker-compose.yaml with Apache). Use this as a starting point for your
+# own production or staging environment.
+#
+# QUICK START
+# -----------
+#   1. Copy this file and docker/nginx/default.conf to your deployment directory.
+#   2. Copy docker/Config.php to Include/Config.php in your ChurchCRM source tree
+#      and set the database connection details to match the values below.
+#   3. Set MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD to strong secrets.
+#   4. Run: docker compose -f docker-compose.nginx.yaml up -d
+#   5. Visit http://localhost/ - you will be redirected to the setup wizard on
+#      first run (no Config.php) or to the login page after installation.
+#
+# IMPORTANT: Change all passwords before exposing this to the internet.
+
+services:
+
+  database:
+    image: mariadb:11
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-changeme_root}
+      MYSQL_DATABASE: churchcrm
+      MYSQL_USER: churchcrm
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-changeme}
+    volumes:
+      - churchcrm-db:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      timeout: 20s
+      retries: 10
+    hostname: database
+
+  php-fpm:
+    build:
+      context: .
+      dockerfile: Dockerfile.churchcrm-fpm-php8
+      target: prod
+    image: churchcrm/crm:php8-fpm
+    restart: unless-stopped
+    volumes:
+      # Mount ChurchCRM source (the contents of src/) here.
+      # Options:
+      #   a) Replace with a bind mount to a local directory:
+      #        - /path/to/churchcrm/src:/var/www/html
+      #   b) Copy files into this named volume after the first `docker compose up`:
+      #        docker cp /path/to/churchcrm/src/. churchcrm-php-fpm-1:/var/www/html/
+      #   c) Build a custom image with COPY instructions in your own Dockerfile.
+      - churchcrm-www:/var/www/html
+    depends_on:
+      database:
+        condition: service_healthy
+    hostname: php-fpm
+
+  webserver:
+    image: nginx:stable-alpine
+    restart: unless-stopped
+    ports:
+      - "${WEBSERVER_PORT:-80}:80"
+    volumes:
+      # Same source volume as php-fpm so nginx can serve static files directly
+      - churchcrm-www:/var/www/html:ro
+      # Mount the nginx configuration
+      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
+    depends_on:
+      - php-fpm
+    hostname: webserver
+
+volumes:
+  churchcrm-db:
+  churchcrm-www:
diff --git a/docker/nginx/default.conf b/docker/nginx/default.conf
