# Traefik Deployment Notes

This note applies to the reverse-proxy deployment variant in `docs/docker-compose-traefik.yml`.

## Start The Stack

From the repository root:

```bash
cp docs/docker-compose-traefik.env.example docs/docker-compose-traefik.env
# edit docs/docker-compose-traefik.env
docker compose \
  --env-file docs/docker-compose-traefik.env \
  -f docs/docker-compose-traefik.yml \
  up -d
```

## Common Failure Modes

### Traefik cannot reach the web container

Check:

- the external Docker network named by `TRAEFIK_NETWORK` exists
- the Traefik instance is attached to that same Docker network
- the hostname in `ECOSPECIES_HOSTNAME` matches the Traefik router rule you expect
- the path in `ECOSPECIES_BASE_PATH` matches the published application prefix, for example `/apps/ecospecies`

### The site opens but the API fails

Check:

- the `api` service is healthy and running
- the `web` service is using the repo's `apps/web/nginx.conf`
- the `api` service finished waiting for `importer`
- the request path is under `ECOSPECIES_BASE_PATH` if you are publishing the app below a domain root

### Importer fails on startup

Check:

- `ECOSPECIES_LEGACY_DATA_DIR` points to a real host path
- that path contains `InputFiles - TXT`
- the mount is readable by Docker on the target host

### Database does not initialize

Check:

- `ECOSPECIES_DB_PASSWORD` is set
- the PostgreSQL volume is writable
- an old incompatible volume is not being reused unintentionally

### Editor login works but no editor state is available

Check:

- `ECOSPECIES_AUTH_TOKENS` is set on the `api` service
- the token you entered matches the configured value exactly

## Operational Notes

- This deployment variant intentionally exposes only the `web` container to Traefik.
- The `api`, `db`, and `importer` services stay on the internal Compose network.
- The `importer` runs before the API starts and seeds or synchronizes the dataset.
- The web container serves both the domain root and `/apps/ecospecies/`, but the Traefik router should target the intended public path.

## Apache Front Door

If Apache is the public front door for the hostname in `ECOSPECIES_HOSTNAME`, it must proxy the configured `ECOSPECIES_BASE_PATH` onward. Otherwise Apache can return its own `Not Found` page before the EcoSpecies stack sees the request.

Example Apache directives:

```apache
ProxyPass        /apps/ecospecies http://127.0.0.1:80/apps/ecospecies
ProxyPassReverse /apps/ecospecies http://127.0.0.1:80/apps/ecospecies
```

Point the backend address at the actual Traefik listener on the host if it is not `127.0.0.1:80`, and adjust the published path if `ECOSPECIES_BASE_PATH` is different.