Use this page as a quick index; deep debugging belongs in your environment logs and Swagger responses.
In this page
API won’t start
| Symptom | Checks |
|---|
| Prisma errors on boot | DATABASE_URL reachable; run pnpm --filter @deploydock/api exec prisma migrate deploy. |
| Port in use | Change PANEL_API_PORT or stop other process on 4000. |
Deploy stuck or instant success
| Symptom | Likely cause | Action |
|---|
| Queue never drains | Worker not running or Redis down | Start apps/worker; verify REDIS_HOST / REDIS_PORT. |
| Deploy “succeeds” instantly with no artifacts | PANEL_DISABLE_QUEUE=1 | API skips BullMQ and calls finishDeployLocal (updates DB only). Set to 0 and run worker for real adapter work. |
| Adapter errors | Noop adapter for runtime | Only node and php adapters have real logic today; see Runtime matrix. |
CORS / login from browser
| Symptom | Checks |
|---|
| Browser blocks API | PANEL_WEB_ORIGIN must include the UI origin (e.g. http://127.0.0.1:5173 or http://localhost:8080). |
Worker / Redis
| Symptom | Checks |
|---|
| Connection refused | Redis listening on expected host; in Docker use service name redis. |
| Auth errors | Set REDIS_PASSWORD in worker env if Redis requires a password. |
Docker prod UI blank or 404 on refresh
| Symptom | Checks |
|---|
| Blank page | Run pnpm --filter @deploydock/web build before docker compose -f deploy/docker/docker-compose.prod.yml up; nginx mounts apps/web/dist. |
| 404 on deep link | nginx.panel.conf uses try_files → /index.html for SPA routing—verify volume mount paths. |
Health: GET /api/v1/health
Swagger: /api/docs on the API port.