History

Brian Pooe 110d17f59f fix(gramps-web): correct container paths in config template and gate OIDC The official grampsweb image works under /app, not /opt/gramps-web — media/index/cache paths pointed at unmounted directories. OIDC is now opt-in via GRAMPS_OIDC_ENABLED and all optional placeholders have defaults so rendering works without an OIDC/email config.		2026-07-03 19:02:17 +02:00
..
config	fix(gramps-web): correct container paths in config template and gate OIDC	2026-07-03 19:02:17 +02:00
.env.sample	fix(gramps-web): correct container paths in config template and gate OIDC	2026-07-03 19:02:17 +02:00
README.md	Harden strict substitution workflow	2026-06-17 22:15:54 +02:00
template.yaml	refactor: restructure docs, sync stacks with Caddyfile, harden compose templates	2026-07-03 17:45:16 +02:00

README.md

Gramps Web

Docker deployment for Gramps Web with Celery and Redis. Run all commands from the repository root.

Persistent Data

Gramps Web application state is stored in Docker-managed gramps_* named volumes. The generated gramps_config/config.cfg remains a read-only host mount, and media remains an intentional host mount from /mnt/gramps_media.

Existing deployments that use project-root gramps_* state directories must copy their contents into the matching named volumes before recreating the stack.

Installation

Create .env if it does not exist:
```
cp -n .env.sample .env
```
Set the Gramps, OIDC, and email values in .env. At minimum configure TREE, BASE_URL, SECRET_KEY, and USER_DB_URI.

Deploy with make:

make deploy-gramps

This creates gramps_config/config.cfg, renders docker-compose.gramps.yml, and starts the stack.

Manual equivalent:

mkdir -p gramps_config
./substitute_env.sh docker-compose-files/gramps-web/config/config_template.cfg gramps_config/config.cfg .env
chmod 644 gramps_config/config.cfg
./substitute_env.sh docker-compose-files/gramps-web/template.yaml docker-compose.gramps.yml .env

Validate and start Gramps Web:

docker compose -f docker-compose.gramps.yml config --quiet
docker compose -f docker-compose.gramps.yml up -d

Verify the containers and open http://<HOST_IP>:

docker compose -f docker-compose.gramps.yml ps
docker compose -f docker-compose.gramps.yml logs --tail=100

Apply Configuration Changes

./substitute_env.sh docker-compose-files/gramps-web/config/config_template.cfg gramps_config/config.cfg .env
chmod 644 gramps_config/config.cfg
./substitute_env.sh docker-compose-files/gramps-web/template.yaml docker-compose.gramps.yml .env
docker compose -f docker-compose.gramps.yml up -d

Initial Setup

Open Gramps Web, create the first user, and configure the family tree. Confirm OIDC and email settings if enabled.

Network Requirements

Allow trusted clients or Caddy to reach port 80.
Ensure /mnt/gramps_media exists and is accessible to Docker.

Troubleshooting

Check that gramps_config/config.cfg is readable and /mnt/gramps_media is writable by the container before starting the stack.

Useful Commands

docker compose -f docker-compose.gramps.yml restart grampsweb

Backup

Back up the gramps_* named volumes, gramps_config/config.cfg, and /mnt/gramps_media.