EcoSpecies-Atlas/docs/traefik-deploy.md

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:

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:

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.