Troubleshooting

Troubleshooting

Containers Won't Start

docker compose config
docker compose logs -f server
docker compose logs -f web

Common causes:

• Missing required env vars
• Invalid image tag
• Port conflicts on host

Auth Issues

Verify these are aligned:

BETTER_AUTH_URL
NEXT_PUBLIC_SERVER_URL
NEXT_PUBLIC_APP_URL
CORS_ORIGINS
BETTER_AUTH_COOKIE_DOMAIN (optional; set it if you want root-domain cookies)

Database Connection Errors

• Check DATABASE_URL credentials and host
• Confirm postgres service is healthy if you are using the bundled database
• In Docker, localhost points to the container itself
  • Use postgres for bundled Compose Postgres
  • Use host.docker.internal for host-machine Postgres
• If tables are missing in a fresh database:
  • bundled database:
    • docker compose run --rm migrate
  • external database:
    • docker compose -f docker-compose.external-db.yml run --rm migrate

Uploads Not Accessible

• Verify STORAGE_BUCKET, STORAGE_ACCESS_KEY_ID, and STORAGE_SECRET_ACCESS_KEY
• Verify STORAGE_REGION/STORAGE_ENDPOINT for your provider
• If you use a custom S3-compatible provider, try STORAGE_ADDRESSING_STYLE=path or virtual if the default auto mode does not match your provider
• Verify bucket CORS if uploads fail before the server responds
• If uploads are restricted to known sites, keep bucket CORS origins aligned with the capture public key allowedOrigins
• If using STORAGE_PUBLIC_URL, confirm it points to accessible objects

See: Storage Setup

Redis or Turnstile Not Configured

Testiment does not require Redis or Turnstile to run.

• Missing Redis disables capture rate limiting and one-time submit token replay protection.
• Missing Turnstile disables the anti-bot challenge for capture submissions.
• CAPTURE_SUBMIT_TOKEN_SECRET can still be set without Redis or Turnstile.