When a containerized app on a VPS breaks, the old Linux reflexes only half-apply. The process you're looking for isn't in the host's normal process list where you expect it; the logs aren't in /var/log; the port that's "open" is open in a network namespace one layer in. Container-first troubleshooting is the same discipline — logs, process, network — pointed at the right layer. Here's a path that gets you from "it's broken" to the cause without flailing.
Start with logs — but the container's
Ninety percent of the time the answer is in the logs, and for a container that means docker logs, not the host's syslog:
docker logs --tail 100 -f <container>
Read the last clean startup and the first error after it. A container in a restart loop prints the same fatal line every few seconds — that line is usually the whole answer (a missing env var, an unwritable volume, a failed dependency). This is the same "read the log first" habit that solves most Jellyfin issues; it generalizes to every container.
Then the process and its exit
If logs are thin, look at lifecycle:
docker ps -a— is it running, restarting, or exited? An exit code is a clue: 137 is OOM-killed (raise the memory limit or fix the leak), 1 is a generic app error, 0 with a restart means it thinks it finished.docker exec -it <container> sh— get inside the namespace to check what the app sees: its config, its files, whether the path it wants exists. The bug is often a host-vs-container path or permission mismatch.
Then the network — at the right layer
"The port's open but I can't reach it" is a layered question:
- Is the app listening inside the container?
execin and check it's bound to0.0.0.0, not127.0.0.1(a container bound to localhost is unreachable from outside it). - Is the port published to the host (
docker psport mapping)? - Is the reverse proxy pointed at the right container/port? A stale upstream is the classic intermittent-502 cause.
- Is a host firewall blocking the published port?
Walk it from inside out and you'll find which layer drops the connection.
Health checks turn mysteries into signals
Half of "why is it broken" is "I didn't know it was broken." Good Docker health-check defaults make the container report its own state, so docker ps shows unhealthy instead of you discovering it from a user.
The repeatable path
docker logs— read the last startup and first error.docker ps -a— running/restarting/exited + exit code.docker exec— inside the namespace: config, files, what the app binds to.- Network outward: container listen → published port → proxy → firewall.
- Add a health check so the next failure announces itself.
Takeaway
Containerized troubleshooting isn't harder than classic Linux debugging — it's the same logs-process-network path aimed one layer in. Read the container's logs first, check its exit code and what it sees from inside the namespace, then walk the network from the app's bind outward. Do it in that order and "the container's broken" becomes a specific, fixable line every time.