Debugging

Debugging

Troubleshooting and debugging procedures for strut VPS deployments.

Quick Diagnostics

strut my-stack health --env prod                          # Health check all services
strut my-stack status --env prod                          # Container status
strut my-stack logs my-service --tail 100 --env prod      # Recent logs

strut status-all --env prod                               # Dashboard across every stack
strut status-all --env prod --json                        # Same, JSON for scripts
strut doctor                                              # Environment-level checks (Docker, SSH keys, tools)
strut doctor --check-vps                                  # + SSH reachability for each env file

status-all (since v0.11.0) is the fastest way to see which stacks are running — it reads container state, newest rollback snapshot, newest backup, and cached drift metrics without running full health probes. Exit 1 if any stack is down or degraded.

Common Issues

502 Bad Gateway

nginx can't reach the backend — usually after a container restart assigns new Docker IPs.

strut my-stack exec "docker compose exec nginx nginx -s reload" --env prod

Port Already Allocated

strut my-stack stop --env prod        # Stop everything cleanly
strut my-stack deploy --env prod      # Redeploy

Service Won't Start

strut my-stack logs my-service --tail 100 --env prod
strut my-stack exec "docker compose exec my-service env" --env prod

Common causes: missing env vars, DB connection issues, port conflicts, disk full.

Database Connection Issues

strut my-stack exec "docker compose exec postgres pg_isready -U postgres" --env prod
strut my-stack exec "docker compose exec redis redis-cli ping" --env prod

Disk Space

strut my-stack exec "df -h /" --env prod
strut my-stack exec "docker system df" --env prod
strut my-stack exec "docker image prune -f" --env prod

Debug Commands

# Execute command in container
strut my-stack debug exec my-service "ls -la /app"

# Open interactive shell
strut my-stack debug shell my-service

# Forward port from container
strut my-stack debug port-forward my-service 3000:3000

# Copy files to/from container
strut my-stack debug copy my-service /app/logs ./local-logs

# Create container snapshot
strut my-stack debug snapshot my-service

# Show environment variables
strut my-stack debug inspect-env my-service

# Show real-time resource usage
strut my-stack debug stats my-service

Advanced Diagnostics

strut my-stack shell --env prod                                    # Interactive SSH
strut my-stack exec "docker stats --no-stream" --env prod          # Resource usage
strut my-stack exec "docker inspect <container>" --env prod        # Full inspection

exec vs shell

Tool	Use For
exec	Single commands, automation, quick checks
shell	Interactive debugging, multiple commands

Environment-Specific Debugging

strut my-stack local debug shell my-service       # Local containers
strut my-stack prod debug shell my-service        # Production containers
strut my-stack staging debug shell my-service     # Staging containers