# 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:

   ```bash
   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. Deploy with `make`:

   ```bash
   make deploy-gramps
   ```

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

   Manual equivalent:

   ```bash
   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
   ```

4. Validate and start Gramps Web:

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

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

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

## Apply Configuration Changes

```bash
./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

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

## Backup

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