homelab-blueprint/docker-compose-files/gramps-web

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

1. Create .env if it does not exist:

   cp -n .env.sample .env
   

2. Set the Gramps, OIDC, and email values in .env. At minimum configure TREE, BASE_URL, SECRET_KEY, and USER_DB_URI.

3. Create the config directory and render both templates:

   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-web.yml .env
   

4. Validate and start Gramps Web:

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

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

   docker compose -f docker-compose.gramps-web.yml ps
   docker compose -f docker-compose.gramps-web.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-web.yml .env
docker compose -f docker-compose.gramps-web.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-web.yml restart grampsweb

Backup

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