Troubleshooting

Most self-hosting problems surface at startup. Start by looking at the service state and logs:

cd ~/sdp
docker compose ps
docker compose logs -f sdp-api

Docker is not ready

The install script checks for Docker up front. If you see that Docker is not installed, that Compose v2 is unavailable, or that the daemon is unreachable, install or start Docker and retry — see the Docker Engine and Compose docs.

A required variable is missing

compose.yml fails fast when a required variable is unset, with a message such as set POSTGRES_PASSWORD in .env. Make sure a .env exists next to compose.yml and fills in every required variable. The configurator produces a complete file; the environment reference lists what is required.

Images won't pull

If docker compose pull reports access denied or a missing manifest:

• Confirm SDP_IMAGE_REGISTRY and SDP_VERSION point at a registry and tag you can reach.
• Pull a single image directly to see the underlying error, e.g. docker pull ghcr.io/solana-foundation/sdp/sdp-api:latest.
• If the registry is private, run docker login for it first.

Port already in use

The API, web, and docs default to ports 8787, 3000, and 3001. If another process holds one of them, the service won't bind. Override the host port in .env with SDP_API_PORT, SDP_WEB_PORT, or SDP_DOCS_PORT and run docker compose up -d again.

Migrations failed

sdp-migrate runs once before the API starts; if it fails, the API stays down. Inspect it with:

docker compose logs sdp-migrate

A failure here is usually a database connection problem — check POSTGRES_* (or DATABASE_URL) and that the postgres service is healthy in docker compose ps.

Database connection refused

The API and migration services wait for Postgres to report healthy before starting. If they still can't connect, verify the credentials in .env, and for an external database (DATABASE_URL set) that it is reachable from inside the Docker network.

Authentication errors in the dashboard

Sign-in problems point at the Clerk configuration. Re-check NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, and CLERK_ISSUER against your Clerk application, and confirm the keys match the environment (development vs production) you intend to run.

Still stuck?

Capture the failing service's logs and your (secret-redacted) .env settings, then open an issue on the project repository.