Troubleshoot a deployment
Diagnose Docker, Compose, container health, reverse proxying, and business requests layer by layer.
Confirm Docker and the local context first
Installation and builds require an available Docker daemon, Compose v2, and Buildx, with the active Docker context pointing to the local host. Do not use a remote context without explicitly confirming the target.
docker info
docker compose version
docker buildx version
docker context showInspect status and relevant logs
Identify the first failed or unhealthy service. Do not delete containers, data volumes, and configuration together. Preserve the original error before addressing dependencies, disk, network, or configuration.
./deploy/stack.sh status
./deploy/stack.sh logsRun from the actual deployment directory: the application checkout for --local, or /opt/bosapi for the default root archive workflow. Add sudo on Linux if Docker access requires it, never on macOS.
Locate the failing layer by symptom
| Symptom | Check first | Boundary |
|---|---|---|
| Image build fails | Registry, Go module, npm connectivity, disk, and memory | Does not yet indicate an application configuration problem |
| Container is unhealthy | Container logs, MySQL, Redis, private configuration, and mounts | Do not delete data volumes as a repair attempt |
| Domain is unreachable | DNS, certificate, ports 80/443, firewall, and reverse-proxy upstream | Healthy containers do not prove public routing works |
| Model request fails | Base URL, key, model access, channel, and upstream response | Health checks do not validate real inference |
Public HTTP without Nginx and browser troubleshooting
With ./install.sh --local --public --port 18080, Go serves the frontend and API directly. BOSAPI_BIND_IP=0.0.0.0 in deploy/stack.env controls public binding; no Nginx upstream configuration is involved. Run host commands from the actual application deployment directory. Add sudo for a root installation if needed, never on macOS.
./deploy/stack.sh status
curl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://127.0.0.1:18080/logincurl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://SERVER_IP:18080/loginReplace SERVER_IP and any custom port, then visit the same address in the actual browser. CLI success alone does not establish browser recovery.
- For external timeouts, check the application’s public binding, inbound TCP 18080 in the attached security group, the allowed source IP, and the host firewall. Changing the port number alone does not enable public binding.
- If server-local and external direct checks return 200 but the browser shows 502, inspect browser proxy extensions and PAC rules. Disabling the system proxy may leave extension proxying active, including in incognito mode.
Retry from the original directory
Preserve the original deploy/stack.env, encryption key, and data mounts, then rerun the appropriate command from the original installation directory. Archive reruns do not upgrade source; --local rebuilds the current checkout without fetching Git updates or automatically repairing damaged data.
Match capabilities and procedures to your deployment version. Read the documentation scope