Add Docker dev compose workflow with bind mounts and hot reload docs

Dockerfile.dev

@@ -0,0 +1,26 @@
+FROM webdevops/php-apache:8.4
+
+RUN echo "LimitRequestLine 12000" > /opt/docker/etc/httpd/conf.d/limits.conf \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+        build-essential \
+        git \
+        gphoto2 \
+        libimage-exiftool-perl \
+        rsync \
+        udisks2 \
+        python3 \
+        ca-certificates \
+        curl \
+        gnupg \
+        nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+RUN mkdir -p /app/node_modules /app/vendor \
+    && chown -R application:application /app
+
+USER application

README.md

@@ -99,6 +99,26 @@ before opening a new issue.
 
 For local testing and development, the docker setup can be used with `docker compose up --build`.
 
+### Local dev with Docker Compose (bind mount + hot reload)
+
+Use the development compose override to run Photobooth directly from your local source tree while containers handle PHP/Apache and asset watching.
+Alternatively call `scripts/dev-docker.sh` from the repo root to start the stack with one command.
+
+1. Start development stack:
+    - `docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build`
+2. Open:
+    - `http://localhost:8080`
+3. Edit files locally in this repository.
+    - PHP/template changes are available immediately via bind mount.
+    - JS/SCSS changes are rebuilt automatically by the `watcher` service (`npm run watch:gulp`).
+
+Notes:
+
+- `docker-compose.dev.yml` mounts the project into `/app`.
+- `node_modules` and `vendor` are stored in named Docker volumes so dependency installs stay inside containers.
+- File watching uses polling (`CHOKIDAR_USEPOLLING=1`) for reliable hot reload behavior on Docker bind mounts.
+- Stop the stack with `docker compose -f docker-compose.yml -f docker-compose.dev.yml down`.
+
 ### Local dev with DDEV (alternative to docker compose)
 
 Use DDEV if you want an all-in-one local stack without touching your host PHP/Node toolchain (Docker Desktop/WSL2/macOS/Linux supported).

docker-compose.dev.yml

@@ -0,0 +1,41 @@
+services:
+  photobooth:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    volumes:
+      - ./:/app
+      - photobooth_node_modules:/app/node_modules
+      - photobooth_vendor:/app/vendor
+    environment:
+      - COMPOSER_VERSION=2
+
+  watcher:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    working_dir: /app
+    user: application
+    command: >-
+      sh -lc "
+      git config --global --add safe.directory /app &&
+      [ -x node_modules/.bin/gulp ] || npm install &&
+      [ -f vendor/autoload.php ] || php bin/composer install &&
+      npm run build &&
+      npm run watch:gulp
+      "
+    volumes:
+      - ./:/app
+      - photobooth_node_modules:/app/node_modules
+      - photobooth_vendor:/app/vendor
+    environment:
+      - CHOKIDAR_USEPOLLING=1
+      - CHOKIDAR_INTERVAL=250
+      - WATCHPACK_POLLING=true
+      - COMPOSER_VERSION=2
+    depends_on:
+      - photobooth
+
+volumes:
+  photobooth_node_modules:
+  photobooth_vendor:

docker-compose.yml

@@ -1,10 +1,8 @@
-version: "3.9"
-
 services:
   photobooth:
     build: .
     ports:
-      - "80:80"
-      - "443:443"
+      - "8080:80"
+      - "8443:443"
     environment:
       - COMPOSER_VERSION=2

docs/install/docker-development.md

@@ -0,0 +1,72 @@
+# Docker development workflow
+
+Use this setup to develop Photobooth inside Docker while editing files on your host machine.
+
+It provides:
+
+- Apache + PHP in container
+- Source code bind-mounted from your local checkout
+- Automatic JS/SCSS rebuild via watcher container
+- Named volumes for `node_modules` and `vendor`
+
+## Start development stack
+
+From the repository root run:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+```
+
+Then open:
+
+- http://localhost:8080
+
+Stop with:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml down
+```
+
+## How live updates work
+
+- All project files are mounted to `/app` in both services.
+- The `watcher` service runs:
+  - `npm run watch:gulp`
+- JavaScript and Sass changes are rebuilt into `resources/` automatically.
+- Polling is enabled for reliable file detection on mounted volumes:
+  - `CHOKIDAR_USEPOLLING=1`
+  - `CHOKIDAR_INTERVAL=250`
+
+## Dependency handling
+
+Dependencies stay in Docker-managed named volumes:
+
+- `/app/node_modules`
+- `/app/vendor`
+
+At startup, the watcher bootstraps missing dependencies:
+
+- runs `npm install` if gulp binary is missing
+- runs `php bin/composer install` if `vendor/autoload.php` is missing
+
+## Verify hot reload
+
+1. Start the stack.
+2. Edit a file in `assets/js/` or `assets/sass/`.
+3. Watch logs for rebuild output from `watcher`.
+4. Refresh the browser and verify your change.
+
+## Troubleshooting
+
+- If changes are not detected, check `watcher` logs:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f watcher
+```
+
+- If dependencies look broken, recreate containers and volumes:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+```

docs/install/index.md

@@ -8,5 +8,6 @@ Pick the guide that matches your environment:
 - Linux:
   - [Install on Debian](install-debian.md)
   - [Enable PHP in nginx](install-nginx.md)
+  - [Docker development workflow](docker-development.md)
 - Windows:
   - [Install on Windows](install-windows.md)

mkdocs_remote.yml

@@ -31,6 +31,7 @@ nav:
     - Photobooth Setup Wizard: install/setup_wizard.md
     - Install on Debian: install/install-debian.md
     - Enable PHP in nginx: install/install-nginx.md
+    - Docker development workflow: install/docker-development.md
     - Install on Windows: install/install-windows.md
   - Upgrade & Maintenance:
     - Overview: update/index.md

scripts/dev-docker.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+# Bring up the dev stack (build + watcher) with a bind mount so you can edit locally.
+# Call this from the repo root.
+
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build