Troubleshooting

Which containers should run?

Every service except migrate should be running; proxy only on standalone deployments. migrate must exit with code 0, or the application does not start. Containers lists each healthcheck.

From the installation directory:

docker compose ps -a
docker compose logs --tail=100 migrate web worker-1 worker-2
docker compose logs --tail=100 postgres redis clickhouse

On cloud VMs, run these as root from /opt/grovs. In Coolify and Dokploy, use the service logs. For a local trial, add -f docker-compose.yml -f docker-compose.local.yml after docker compose.

Images cannot be pulled

• Check GROVS_VERSION against the latest completed release, or use latest in an existing Compose installation.
• The images are ghcr.io/grovs-io/backend and ghcr.io/grovs-io/dashboard. Both GHCR packages must contain the selected tag and allow anonymous pulls.
• On Railway templates and Render, check the service image sources directly.
• A public source repository does not make its packages public automatically.
• An image built only locally is not available to new servers until the release workflow pushes it.

See Images and releases.

Dashboard works, project links fail

Check all three:

1. Wildcard DNS points to the correct server, including *.test.<links-domain>.
2. The reverse proxy routes the project hostname to web:3000.
3. The certificate covers that hostname. *.<links-domain> does not cover <project>.test.<links-domain>; the test domain needs its own wildcard.

In the platform template, the dashboard's router has higher priority than the API and link router. Keep GROVS_ROUTER_PREFIX unique on a shared proxy. The GROVS_*_DOMAIN_PATTERN values are generated from your link domains; update them too if you change domains.

Coolify or Dokploy reports a proxy or certificate error

• The external Docker network exists and the Traefik proxy is connected to it.
• The entrypoint and certificate resolver names match the platform environment file.
• The resolver uses DNS-01. The template uses Traefik v3 HostRegexp rules, and wildcard certificates need DNS-01.
• The standalone Caddy profile is off.

Login fails after a successful migration

The API and dashboard must share the same OAUTH_CLIENT_UID and OAUTH_CLIENT_SECRET. Import the complete generated environment; do not generate credentials separately per service. Confirm the dashboard container can reach API_HOST.

Analytics is temporarily unavailable

Wait for the first scheduled rollup, then check the worker-1 and ClickHouse logs. Confirm all three databases are healthy. Do not disable the shipped ClickHouse flags to hide an error; ClickHouse is the analytics and event store.

Uploaded images do not show

S3_ASSET_PREFIX must be https://<API_HOST>, and that host must be publicly reachable over HTTPS. See Configuration.

Reset everything

For a local trial, see Stop and resume. For a public installation, back up your data and secrets first. Restarting containers keeps volumes; docker compose down --volumes deletes them.