CAcompose

Docker Compose setup for CollectiveAccess — runs Providence (cataloguing backend) and Pawtucket2 (public catalog) together with MySQL 8, Redis 7, and Nginx, all on a single host.

Services

Container	Role	URL
nginx	Reverse proxy, TLS termination	—
providence	Admin / cataloguing backend (PHP + Apache)	https://host/backend/
pawtucket2	Public catalog frontend (PHP + Apache)	https://host/
db	MySQL 8	internal
redis	Cache	internal

Both apps share the same database and a single media directory mounted from the host.

Quick start

# 1. Edit credentials (file already exists with defaults)
$EDITOR .env

# 2. Generate a self-signed TLS certificate for local HTTPS
./generate-dev-certs.sh

# 3. Create required host directories
mkdir -p ./media ./import \
         data/providence/log data/providence/tmp \
         data/pawtucket2/log data/pawtucket2/tmp

# 4. Build and start  (~20-40 min first time — Composer installs for both apps)
docker compose up --build -d

# 5. Run the web installers
open https://127.0.0.1/backend/install/   # Providence first

Key features

• Single .env file — all credentials and settings in one place; setup.php for both apps reads them via getenv() at runtime, no rebuild needed for config changes.
• File override system — replace any app file (config, plugin, template) by placing it under overrides/providence/ or overrides/pawtucket2/, mirroring the app directory structure. Applied on every container start, no rebuild.
• Custom themes — drop a theme folder into overrides/pawtucket2/themes/ and set CA_PAWTUCKET2_THEME=<name> in .env.
• External media directory — both containers mount the same host path (MEDIA_PATH in .env) so uploaded files are shared. Supports local directories, NFS, or S3 via s3fs.
• Persistent logs and tmp — app/log/ and app/tmp/ for both apps are bind-mounted under data/ on the host, surviving container rebuilds.
• Batch media import — drop files into ./import/ (configurable via IMPORT_PATH) and they appear in Providence's media importer.
• Umami analytics — opt-in self-hosted analytics via docker compose --profile analytics up -d.
• Development HTTPS — ./generate-dev-certs.sh creates a self-signed cert with correct SAN for 127.0.0.1/localhost. HTTP on :80 auto-redirects to HTTPS on :443.
• Production-ready routing — Nginx uses Docker's internal DNS resolver with variable-based proxy_pass to avoid startup race conditions.

File layout

.
├── .env                          # credentials and runtime config
├── generate-dev-certs.sh         # one-shot dev certificate generator
├── docker-compose.yml
├── nginx/
│   ├── conf.d/default.conf       # reverse proxy config (HTTPS)
│   └── certs/                    # dev.crt + dev.key (gitignored)
├── providence/
│   ├── Dockerfile
│   ├── apache.conf               # Alias /backend → /var/www/providence
│   └── setup.php                 # reads CA_* env vars via getenv()
├── pawtucket2/
│   ├── Dockerfile
│   ├── apache.conf
│   └── setup.php
├── overrides/
│   ├── providence/               # place overrides here
│   └── pawtucket2/
│       ├── app/conf/             # e.g. app.conf
│       └── themes/               # custom themes
├── data/
│   ├── providence/
│   │   ├── log/                  # CA application logs (bind-mounted)
│   │   └── tmp/                  # sessions, upload staging, file cache
│   └── pawtucket2/
│       ├── log/
│       └── tmp/
├── import/                       # batch media import staging (IMPORT_PATH)
└── media/                        # shared media directory (MEDIA_PATH)

Custom installation profile

The CA installer lets you choose a profile (an XML file defining the initial data model, lists, and UI) when setting up Providence for the first time. To use a custom profile, place it in:

overrides/providence/install/profiles/xml/your-profile.xml

The entrypoint copies it into the container on every start, so it will appear in the installer's profile dropdown without a rebuild. Run the installer at https://host/backend/install/, select your profile, and proceed normally.

Profiles only affect the initial install — once the database is set up the file has no further effect.

Documentation

See Documentation.md for the full reference:

• Configuration variable reference
• How the file override system works
• Adding a custom InformationService plugin
• Runtime data directories (logs, tmp, import)
• Batch media import staging
• Umami analytics opt-in
• Production deployment (external nginx + Let's Encrypt, or Certbot in Docker)
• Database backup / restore
• caUtils CLI examples
• Troubleshooting

Requirements

• Docker 24+ and Docker Compose v2
• openssl on the host (for generate-dev-certs.sh) — comes with macOS and any Linux distro
• ~4 GB disk space for the built images

Notes

• First build clones both CA repos from GitHub and runs composer install — expect some time to build.
• Pin CA_PROVIDENCE_VERSION and CA_PAWTUCKET2_VERSION in .env to a release tag (e.g. 2.0.2) for reproducible builds.