Troubleshoot a deployment

Diagnose Docker, Compose, container health, reverse proxying, and business requests layer by layer.

Operations troubleshooting guideUpdated Oct 26, 2026

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.

Check the Docker toolchain
docker info
docker compose version
docker buildx version
docker context show

Inspect 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.

Inspect Compose status and logs
./deploy/stack.sh status
./deploy/stack.sh logs

Run 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

SymptomCheck firstBoundary
Image build failsRegistry, Go module, npm connectivity, disk, and memoryDoes not yet indicate an application configuration problem
Container is unhealthyContainer logs, MySQL, Redis, private configuration, and mountsDo not delete data volumes as a repair attempt
Domain is unreachableDNS, certificate, ports 80/443, firewall, and reverse-proxy upstreamHealthy containers do not prove public routing works
Model request failsBase URL, key, model access, channel, and upstream responseHealth 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.

Check on the deployment host first
./deploy/stack.sh status
curl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://127.0.0.1:18080/login
Then check directly from the visitor’s workstation
curl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://SERVER_IP:18080/login

Replace 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

BOS API · TYPEX

Sales consultation is unavailable

Sales reception could not be initialized. Please try again later. Documentation and free self-hosting remain available.

Read the docsSelf-host for free