Skip to content
Supermetry

Troubleshoot self-hosting

Resolve common Docker, PostgreSQL, configuration and port errors.

Match the startup error to a verified fix, then check readiness again.

  1. If Compose reports compose build requires buildx 0.17 or later, upgrade buildx or disable Bake for this run.

    Terminal window
    COMPOSE_BAKE=false docker compose -f deploy/docker-compose.yml up -d --build

  2. If an older checkout left deploy-* containers or deploy_* volumes, inspect them before removing anything.

    Terminal window
    docker ps -a --filter name=deploy-
    docker volume ls --filter name=deploy_

    Back up any needed data before deleting an old container or volume. Current Compose resources use the supermetry project name.

  3. If PostgreSQL 18 starts with an empty database after an upgrade, check the volume mount. PostgreSQL 18 stores its cluster below /var/lib/postgresql/18/docker, and the current Compose file mounts the volume at /var/lib/postgresql.

    An old volume mounted at /var/lib/postgresql/data must be backed up with its old configuration and restored into a fresh PostgreSQL 18 volume. Do not remount it at the new path.

  4. For installer database failures, correct the field named by the message:

    • connection refused by PostgreSQL host: start PostgreSQL and check its host and port.
    • DNS name not found: correct the database hostname.
    • password authentication failed for user ...: correct the user or password.
    • database ... does not exist: create the database or correct its name.
    • PostgreSQL TLS certificate could not be verified: correct the certificate trust or sslmode.

    Interactive installation keeps the entered values and asks again. An unattended --yes install exits without writing files.

  5. If plain supermetry prints Supermetry is not configured, run the installer or create .env with SUPERMETRY_DATABASE_URL, SUPERMETRY_SECRET_KEY, and SUPERMETRY_BASE_URL.

  6. If startup reports listen on ... address already in use, identify the process using the configured port.

    Terminal window
    sudo ss -ltnp 'sport = :8787'

    Stop the unintended process or change SUPERMETRY_LISTEN, then restart Supermetry.

  7. Check the service and readiness.

    Terminal window
    sudo systemctl status supermetry --no-pager
    sudo journalctl -u supermetry -n 50 --no-pager
    curl -fsS http://127.0.0.1:8787/readyz

What you should see: the service is active and /readyz returns {"status":"ok"}.

Section titled “Related”