Installation troubleshooting

The SummitPSA installer (install.sh) is a thin orchestrator: it checks prerequisites, authenticates to the license-gated registry with your key, pulls the pinned image, writes .env.docker and docker-compose.yml into the install directory (default /opt/summitpsa), and runs docker compose up -d. Failures almost always fall into one of the buckets below.

Prerequisite checks fail

The installer checks but never installs prerequisites. It exits early if any of these are missing: root (run with sudo), Docker Engine, the Docker Compose v2 plugin (docker compose version), a reachable Docker daemon, and openssl (used to generate secrets). Install the named tool and re-run.

"License key not accepted"

Your license key is the registry credential. The installer runs docker login license.summitpsa.com -u x with the key on stdin; a 401 means the key is wrong, expired, or suspended. Re-check the key (format SUMMIT-XXXXX-XXXXX-XXXXX-XXXXX) and confirm it is active.

"Image pull failed"

The key authenticated but the pull failed — usually a bad version tag or loss of connectivity to license.summitpsa.com. Confirm the server can reach that host over HTTPS.

App not responding after install

First boot runs database migrations and can take up to ~3 minutes; the installer polls http://127.0.0.1:8001/ for up to 3 minutes. If it warns that the app isn't responding, inspect logs:

cd /opt/summitpsa && docker compose logs app

The most common cause is the database still initialising — the app container waits up to 120s for the DB, then runs alembic upgrade head before starting.

Can't reach the setup wizard

The app binds to 127.0.0.1:8001 only and is deliberately not exposed publicly. Reach the wizard either through your reverse proxy (terminating TLS and pointing at http://127.0.0.1:8001) or an SSH tunnel: ssh -L 8001:127.0.0.1:8001 user@server, then open http://localhost:8001.