DEV Community: Peon Sh

Docker Container Keeps Restarting? Here’s How to Debug It

Peon Sh — Thu, 27 Aug 2026 05:33:02 +0000

A container stuck in a restart loop usually fails in the first second. Find the real error with logs, exit codes and these five common causes.

What a restart loop actually is
A container "stuck restarting" is not mysterious: the main process exits (usually within the first second or two), and the restart policy dutifully relaunches it, forever. The container is doing exactly what it was told; your job is to find out why the process dies. The answer is almost always sitting in the logs of the failed run, and the debugging discipline is to read the evidence before changing anything.

docker ps -a # see the status and restart count
docker logs --tail 100 # the error from the last run
docker inspect \
--format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'

Decode the exit code
The exit code narrows the cause before you read a single stack trace:

1 (or app-specific nonzero): the application errored, read the stack trace; usually config or a missing dependency
137: the process was SIGKILLed, either the kernel OOM killer (check OOMKilled in inspect) or a stop timeout; if OOMKilled is true, raise the memory limit or fix the leak
126: the entrypoint exists but is not executable, typically a missing chmod +x or a Windows line-ending problem in a shell script
127: command not found, a CMD typo, or the binary does not exist in your slim base image (bash on alpine is the classic)
139: segmentation fault, very often a native module compiled for the wrong architecture (x86 module in an ARM container or vice versa)

The five usual suspects
Across thousands of restart loops, the same five causes dominate:

Missing environment variable: the app’s config validation throws on boot; compare docker exec env expectations against what the service actually defines
Database not ready: the app connects once at startup, Postgres is still initializing, the connection fails and the process exits, add retry-with-backoff in the app or a health-gated depends_on
Wrong bind address: the app listens on 127.0.0.1 inside the container, so nothing can reach it and a healthcheck kills it; always bind 0.0.0.0 in containers
Memory limit below reality: a Node app that needs 600 MB in a 512 MB container will OOM on schedule; watch docker stats during startup
Bad healthcheck: the check curls the wrong port or path, marks a healthy app unhealthy, and the platform restarts it, verify the check command by running it manually with docker exec
Reproduce it interactively
When the logs are too thin (some apps crash before configuring their logger), bypass the loop entirely: start a shell in the same image with the same environment, then launch the process by hand and watch it fail in slow motion:

docker run -it --rm --entrypoint sh \
--env-file <(docker inspect --format \
'{{range .Config.Env}}{{println .}}{{end}}') \

# inside: run the original CMD manually

Prevent the next one
Three habits eliminate most restart loops before they ship: validate configuration at boot and fail with a clear message naming the missing variable; add startup dependency retries so ordering never matters; and test the image locally with docker run using production-shaped environment variables before deploying. Platforms help too, Peon streams the failing container’s logs in the dashboard, so the stack trace is one click away rather than an SSH session.

Fix “Port Is Already in Use” Errors on Linux and Docker

Peon Sh — Thu, 27 Aug 2026 05:31:29 +0000

EADDRINUSE and Docker port binding failures: find what holds the port, free it safely, and design so it never happens again.

The error and what it means
Whether it appears as EADDRINUSE in Node, "address already in use" from Docker, or "bind: address already in use" from nginx, the meaning is identical: exactly one process may listen on a given IP:port pair, and something already holds the one you want. The fix is never to reboot and hope; it is to identify the holder, decide whether it should be there, and act accordingly.

Find the holder
Modern Linux gives you the owning process in one command:

sudo ss -tlnp | grep :3000
# LISTEN 0 511 *:3000 users:(("node",pid=1234,fd=20))
# or the older equivalent
sudo lsof -i :3000
# if it's a container publishing the port
docker ps --format '{{.Names}}\t{{.Ports}}' | grep 3000

Common culprits, in order of frequency

A previous instance of your own app: a dev server you forgot, or an orphaned process after a crashed deploy, kill the specific PID, not everything matching a name
Another container publishing the same host port: two services both trying to own 8080:..., only one can win
System services on well-known ports: a distro-installed Apache or nginx squatting on 80/443, blocking your reverse proxy container (disable with systemctl disable --now)
systemd-resolved on port 53, relevant when running Pi-hole or other DNS containers
TIME_WAIT ghosts: right after a restart the port looks busy for up to a minute; SO_REUSEADDR in the app makes rebinding immediate, and ss shows no LISTEN holder in this case

The structural fix: stop publishing ports
On a server with a reverse proxy, host port conflicts are a symptom of an anti-pattern: app containers should not publish host ports at all. Each app listens on its internal port on the Docker network; the proxy is the only process binding 80 and 443, and it routes by hostname. Under this design, two apps can both use "port 3000" internally forever without conflict, because no one is competing for host ports.

This is how Peon deploys services by default: no published ports on app containers, proxy-only ingress. If you are hand-writing compose files, deleting the ports: section from app services (keeping it only on the proxy) is the single change that retires this whole error class.

Quick decision table

Holder is your old process: kill , then fix whatever leaves orphans (usually a missing SIGTERM handler)
Holder is another container: change one side’s published port, or better, unpublish both and route via the proxy
Holder is a system service you need: move your service to another port
Holder is a system service you do not need: disable it permanently
No holder visible: TIME_WAIT, wait 60 seconds or fix the app’s socket options

Docker Ate Your Disk? Reclaim Space Safely

Peon Sh — Thu, 27 Aug 2026 05:29:55 +0000

“No space left on device” on a Docker host: find what’s consuming the disk (images, logs, volumes, build cache) and clean each safely.

Why Docker hosts fill up
Full disks are the most common cause of outages on single-server Docker hosts, more common than crashes or traffic spikes. The mechanics are mundane: every deploy leaves image layers behind, every build adds cache, and every log line a container prints is appended to an unbounded JSON file. None of it cleans itself up, and "no space left on device" takes down everything at once: new deploys fail, databases cannot write, and even the commands to fix it can fail.

Diagnose before deleting anything
Two commands show exactly where the space went, always run them first:

docker system df -v # images, containers, volumes, build cache
df -h / # overall disk picture
du -sh /var/lib/docker/containers/*/ 2>/dev/null | sort -h | tail
# ^ per-container log sizes: the silent killer

Clean each consumer, in safety order
From completely safe to requires-thought:

Dangling and unused images: docker image prune -af, safe, worst case the next deploy pulls layers again
Build cache: docker builder prune -af, safe, the next build is slower, nothing is lost
Stopped containers: docker container prune -f, safe if you do not intentionally keep stopped containers around
Container logs: truncate oversized ones (truncate -s 0 /var/lib/docker/containers//-json.log), then fix rotation permanently (next section)
Volumes: docker volume prune is DANGEROUS, "unused" only means no running container references it right now; a stopped database’s data volume qualifies. List them, identify each one, and remove only what you can name

Cap log growth permanently
The default json-file log driver has no size limit; a single chatty container can write gigabytes a week. Set global limits in the daemon config and this problem never returns:

/etc/docker/daemon.json

{
"log-driver": "json-file",
"log-opts": { "max-size": "20m", "max-file": "3" }
}
# then: systemctl restart docker
# note: applies to newly created containers; recreate old ones to adopt it

Automate the hygiene
One-off cleanups buy weeks; automation buys forever. Schedule a weekly prune of images, stopped containers and build cache, and alert on disk crossing 80% so you act before 100%. Peon exposes exactly this as a server cleanup action (on demand or scheduled) and shows per-server disk meters in the dashboard, deploy-heavy hosts stay healthy without anyone remembering to SSH in and prune.

SSH Connection Refused or Timing Out: A Debugging Checklist

Peon Sh — Thu, 27 Aug 2026 05:28:25 +0000

Locked out of your VPS? Work through connection refused vs timeout, firewall rules, sshd state and key problems methodically.

The error message is the map
SSH failures announce their category if you read them precisely. "Connection refused" means a machine answered and actively rejected you: the network path works, but nothing (or the wrong thing) listens on that port. "Connection timed out" means packets vanished: a firewall silently drops them or you are aiming at the wrong address. "Permission denied (publickey)" means SSH itself works fine and authentication is the problem. Each category has a completely different checklist, so classifying first halves the work.

Timeouts: walk the firewalls, outside in
Verify the IP: ping it, and check the provider dashboard, VPS IPs change after rebuilds, and stale SSH configs point at ghosts
Provider/cloud firewall: does a rule allow TCP 22 from your current IP? Office and home IPs change; allowlists silently go stale
Host firewall: ufw or iptables on the server itself, easy to lock yourself out by enabling ufw without ufw allow ssh first
Your side: corporate and hotel networks sometimes block outbound 22, test via phone hotspot to rule it out in one minute
fail2ban or provider intrusion protection may have banned your IP after repeated failed attempts, check from a different IP
Refused: get on the box out-of-band
Every serious VPS provider offers a web console (VNC/serial) that works even when SSH does not, this is your lifeline. Log in through it and inspect the daemon:

Common causes: a bad sshd_config edit (always run sshd -t before restarting), the daemon disabled after an update, or sshd moved to a non-standard port you forgot
Disk 100% full can also prevent sshd from accepting sessions, check df -h while you are there
systemctl status sshd # running? crashed? failed config?
journalctl -u sshd -n 50 # recent errors, bad config lines
ss -tlnp | grep sshd # which port is it actually on?
sshd -t # validate config syntax before restarting
Permission denied (publickey)
Authentication failures are almost always one of four things:

Wrong key offered: ssh -v shows which keys the client tries; specify explicitly with -i ~/.ssh/the_right_key
Wrong user: images differ, ubuntu on Ubuntu cloud images, root on many VPS defaults, debian, admin... check the provider docs
Server-side permissions: ~/.ssh must be 700 and authorized_keys 600, owned by the user; sshd silently ignores world-readable key files (visible in journalctl -u sshd)
PasswordAuthentication no with your key missing from authorized_keys entirely, fix via the web console
Lock-out-proofing for the future
Three cheap habits make lockouts a non-event: keep a second SSH key from a different machine in authorized_keys; when changing sshd config, keep your current session open and test a new connection before closing it; and know where your provider’s web console lives before you need it. Deployment platforms reduce day-to-day exposure too, with Peon managing servers over its own configured SSH access, your personal SSH sessions become rare, so there is less config churn to get wrong.

DNS Propagation: Why Your Domain Change Takes Time (and Why It Doesn’t)

Peon Sh — Thu, 27 Aug 2026 05:26:20 +0000

What actually happens when you change an A record, why “48 hours” is a myth, and how to verify DNS changes in real time.

There is no “propagation”, only caches expiring
DNS changes do not push out to the world; nothing is propagating anywhere. When you update an A record, the authoritative nameserver answers with the new value immediately. Everyone else, ISP resolvers, public resolvers like 1.1.1.1, your OS, your browser, keeps serving their cached copy until its TTL (time to live) expires, then re-asks and gets the new answer.

"Propagation delay" is simply the world’s caches expiring at different moments. With a 300-second TTL, effectively everyone converges within five minutes. The mythical "24 to 48 hours" dates from an era of default day-long TTLs and survives because it makes a safe thing to tell customers.

Verify at the source, skip the guesswork
The definitive check queries your zone’s authoritative nameserver directly, bypassing every cache on Earth:

Correct at the authoritative server: your change is live; the world converges within one TTL, done
Wrong there: the change did not save, or you edited the wrong zone, if nameservers point at Cloudflare, records at your registrar are decorative
dig +short NS example.com # find the authoritative servers
dig +short app.example.com @ns1.dns-host.com # ask one directly
Why YOUR machine still shows the old value
The most common "DNS is broken" report is local caching. Your OS resolver, systemd-resolved, and your browser each cache independently, sometimes beyond the TTL. Test against a public resolver to see what the world sees, and flush local caches only if you personally need the new value right now:

dig +short app.example.com @1.1.1.1 # Cloudflare's resolver
dig +short app.example.com @8.8.8.8 # Google's
# flush local (macOS)
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# flush local (Linux with systemd-resolved)
sudo resolvectl flush-caches
Negative caching: the sneaky one
If you query a name before creating its record, resolvers cache the "does not exist" answer (NXDOMAIN) for the zone’s negative TTL, often longer than your record TTL. Practical rule: create the record first, test second. If you tested too early, the fix is patience or querying a resolver you have not poisoned yet.

Practical playbook for changes
Before a planned migration: lower the TTL to 300 a day in advance (the old TTL governs how long the lowering itself takes to be seen)
Make the change, verify against the authoritative server, then against 1.1.1.1
Keep the old server running for at least the old TTL window to catch stragglers
After stabilizing, raise TTL back to 3600 or more for resilience and fewer resolver queries

Let’s Encrypt Certificate Not Issuing? Diagnose It in Order

Peon Sh — Thu, 27 Aug 2026 05:22:16 +0000

ACME challenge failed, connection refused, or rate limited, a systematic checklist for when automatic HTTPS doesn’t come up.

How issuance fails, structurally
Automatic HTTPS has three prerequisites: the domain resolves to your server, the ACME challenge can reach it (port 80 for HTTP-01), and you are not rate limited from earlier failed attempts. Every "certificate not issued" case is one of those three, and the fastest path is to check them in that order rather than re-deploying and hoping. Crucially: your proxy logs contain the exact ACME error naming the failing check, read them first.

docker logs 2>&1 | grep -i -E "acme|certificate|challenge" | tail -20

Check 1: DNS (it’s DNS 80% of the time)
The domain must resolve to this server’s public IP before issuance can succeed:

No answer: the record does not exist, or you edited a zone that is not authoritative (registrar DNS vs Cloudflare is the classic mix-up)
Wrong IP: an old record, or the record points at a load balancer/other box
Also check AAAA: if an IPv6 record exists but the server does not actually serve on that address, validation can fail even though IPv4 looks perfect
dig +short app.example.com # what the world sees
curl -4 -s ifconfig.me # this server's public IPv4
# these two must match

Check 2: reachability on port 80
HTTP-01 validation arrives as a plain HTTP request on port 80. Both the cloud firewall (security group) and any host firewall (ufw, iptables) must allow 80 and 443, and the proxy container must actually be running and bound to them. A stray host-level nginx or Apache holding port 80 silently absorbs every challenge, check with ss -tlnp | grep -E ":80|:443" that the listener is your proxy.

Check 3: the Cloudflare orange cloud
If the domain is proxied through Cloudflare (orange cloud), challenge requests hit Cloudflare’s edge, not your origin, and HTTP-01 can fail confusingly. Two clean resolutions: set the Cloudflare SSL mode to Full (strict) and let Cloudflare terminate for visitors while your origin still gets its own certificate; or temporarily grey-cloud the DNS record, let issuance complete, then re-enable the proxy. Never run Flexible mode; it causes redirect loops with origin HTTPS.

Check 4: rate limits, and how not to hit them
Let’s Encrypt limits failed validations to 5 per account, per hostname, per hour, and duplicate certificates to 5 per week. Retrying in a loop while DNS is broken burns through both. The discipline: diagnose with the checks above, fix the root cause, retry once. For experiments, point the proxy at the staging endpoint, generous limits and untrusted certificates, perfect for verifying plumbing before touching production limits.

When everything is fixed, issuance is fast: certificates typically arrive within seconds of the first valid request, and platforms like Peon retry automatically, so a previously failing domain heals on its own once DNS and firewall are right.

Docker Logging Best Practices for Production Apps

Peon Sh — Thu, 27 Aug 2026 05:21:03 +0000

Log to stdout, structure as JSON, cap file sizes and know your retention: pragmatic logging for containerized apps without an ELK stack.

The one rule: stdout, unbuffered
The twelve-factor principle remains the foundation of container logging: applications write events to stdout/stderr and treat log routing as the runtime’s job. Never write log files inside a container, they die with it, they hide from docker logs, and inside volumes they grow until the disk fills. Every serious runtime, platform and collector builds on the stdout convention; fighting it buys you nothing.

Unbuffered matters too: Python needs PYTHONUNBUFFERED=1, and any language buffering stdout will show logs minutes late or lose the crucial lines before a crash.

Structure beats prose
The difference between grep-able text and queryable JSON shows up the first time you debug a real incident. JSON lines with a level, timestamp, message and request context turn "search the haystack" into "filter where user_id=X and status=500". Every mainstream logger does this well: pino (Node), zerolog/slog (Go), structlog (Python), Serilog (.NET).

Include a request ID on every line of a request’s lifecycle, correlation is the whole game
Log at boundaries (request in/out, job start/end, external calls) rather than narrating every function
Never log secrets, tokens or full card numbers; add a redaction layer where user data flows

{"level":"error","time":"2026-04-07T10:31:04Z","req_id":"abc123",
"user_id":8841,"route":"/api/checkout","status":500,
"err":"payment provider timeout after 3000ms","duration_ms":3012}

Cap and rotate at the daemon
Docker’s default json-file driver has no size cap, making unbounded logs the number-one cause of mysteriously full Docker hosts. Fix it once, globally:

/etc/docker/daemon.json

{ "log-opts": { "max-size": "20m", "max-file": "3" } }
# 60 MB ceiling per container; restart docker, recreate containers to adopt

Levels and volume discipline
Run production at info level: debug in production drowns signals and inflates costs everywhere downstream. A useful volume heuristic: a healthy request logs 1 to 3 lines, not 30. If a single user action produces a screen of logs, you are narrating rather than reporting, and the noise will hide the one line that matters during an incident.

Do you actually need a log stack?
For single-host and few-host deployments, platform log access, Peon streams live and recent container logs per service in the dashboard, plus daemon-level rotation covers the daily debugging loop: see the error, correlate by request ID, fix. Graduate to Loki or an ELK stack when a concrete need arrives: searching across many servers at once, retention measured in months for compliance, or alerting on log patterns. Adopting that infrastructure before the need is a classic complexity trap; the migration later is easy precisely because everything already logs structured JSON to stdout.

Postgres “Connection Refused” in Docker: The Complete Fix List

Peon Sh — Thu, 27 Aug 2026 05:06:34 +0000

App can’t reach Postgres in Docker? Hostname resolution, networks, startup ordering and auth, the four failure classes and their fixes.

Four failure classes, four different fixes
Every "app cannot reach Postgres in Docker" report is one of four distinct problems: wrong hostname, separate networks, startup ordering, or authentication. The error text tells you which: ECONNREFUSED or "connection refused" is network-level (classes 1 to 3); "password authentication failed" or "no pg_hba.conf entry" means the network is fine and auth is wrong (class 4). Diagnose top-down and you fix it in minutes.

Class 1: localhost is not your database
Inside a container, localhost means that same container, not the machine, not the database next door. An app configured with postgres://user:pass@localhost:5432/db will get ECONNREFUSED forever, because nothing listens on 5432 inside the app’s own container. Use the database’s service or container name as the hostname; Docker’s embedded DNS resolves it on shared user-defined networks:

wrong (inside a container)

DATABASE_URL=postgres://app:secret@localhost:5432/appdb
# right
DATABASE_URL=postgres://app:secret@postgres:5432/appdb
#                                    ^ the service/container name

Class 2: different networks
Containers resolve each other only when they share a user-defined Docker network. Two compose stacks, or a hand-run container and a platform-managed one, land on different networks by default and are mutually invisible. Verify and fix:

Platforms avoid this by attaching all services to a shared network, in Peon, services on the same server reach each other by name out of the box
docker inspect app --format '{{json .NetworkSettings.Networks}}' | jq keys
docker inspect postgres --format '{{json .NetworkSettings.Networks}}' | jq keys
# no common network? connect one:
docker network connect app

Class 3: the startup race
Postgres takes several seconds to initialize, longer on first boot with a fresh volume. An app that connects exactly once at startup loses the race, gets ECONNREFUSED, and crashes into a restart loop that eventually stabilizes (masking the real issue). Fix it properly in both places:

And in the app: retry initial connections with backoff for 30 to 60 seconds, ordering then never matters anywhere (CI, restarts, reboots)

compose: gate on real readiness, not just "started"

depends_on:
postgres:
condition: service_healthy
# postgres service:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app"]
interval: 5s
retries: 10

Class 4: auth and the first-boot trap
The official image’s POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB variables apply only when initializing an empty data volume. Change them later and nothing happens, the credentials in the existing volume win, a trap that produces "password authentication failed" after an innocent-looking config edit. Fix credentials in the running database (ALTER USER app WITH PASSWORD ‘...’;) or, for throwaway dev data, remove the volume and re-initialize. "No pg_hba.conf entry" appearing with network connections usually means a custom config restricted host access, the stock image already allows network connections from the Docker network with password auth.

Next.js Standalone Mode: Small Docker Images That Boot Fast

Peon Sh — Thu, 27 Aug 2026 05:02:13 +0000

output: "standalone" cuts Next.js images from 1 GB+ to ~150 MB. How it works, the static-files gotcha, and a copy-paste Dockerfile.

The problem standalone solves
A naive Next.js Dockerfile copies the entire project, node_modules included, into the final image: 1 GB or more, most of it build tooling and dev dependencies the production server never touches. Every deploy moves that gigabyte, every host stores copies of it, and cold starts pay for loading it.

With output: "standalone" in next.config, next build performs file tracing: it walks the actual require/import graph of the production server and emits .next/standalone, a self-contained folder with server.js and only the node_modules files genuinely reached at runtime. Typical result: 120 to 180 MB final images, an 85 to 90% reduction.

// next.config.js
module.exports = { output: 'standalone' };

The gotcha everyone hits once
Standalone output deliberately excludes two directories: .next/static (hashed JS/CSS assets) and public/ (your static files). The assumption is you might serve them from a CDN. Self-hosting them means copying both into the image yourself, forget this, and the app boots fine but every page loads without styles or scripts, assets 404ing:

FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static # <- required
COPY --from=build /app/public ./public # <- required
EXPOSE 3000
CMD ["node", "server.js"]

Environment variable timing
The other classic standalone-mode bug is env timing. NEXT_PUBLIC_* variables are inlined into the client JavaScript at build time; setting them at runtime does nothing, they must exist during npm run build (build args or platform build-time variables). Server-only secrets are the reverse: read at runtime from process.env, so they belong in runtime environment variables and never need rebuilds. The symptom of mixing these up is always "works locally, undefined in production".

What still works (everything)

ISR: revalidation runs in the server process; cache lives on the container filesystem (fine for one instance; use a custom cache handler when scaling out)
next/image: on-demand optimization works out of the box, sharp is bundled by tracing
Middleware, API routes, server actions: all present, this is the full Next.js server, not an adaptation
The only external assumption gone: no CDN implied; add Cloudflare in front if you want edge asset caching

Payoff in production
Concrete numbers from typical apps: image 1.1 GB to 150 MB, build-and-deploy cycle minutes to under one, container start under a second, and far less disk churn on deploy-heavy hosts (relevant when your platform builds on the server, as Peon does, layer cache stays warm and rebuilds move only your app layer). Standalone mode is the single highest-leverage line of configuration in self-hosted Next.js.

Docker Networking Explained: Bridges, DNS and Why localhost Breaks

Peon Sh — Thu, 27 Aug 2026 05:00:21 +0000

A mental model for Docker networks: how containers find each other, when to publish ports, and the difference between expose and ports.

The mental model: networks are virtual switches
Almost every Docker networking confusion dissolves with one picture: a user-defined bridge network is a virtual switch. Containers attached to it get a private IP and, crucially, a DNS name equal to their container or service name, resolved by Docker’s embedded DNS server. Containers on the same switch reach each other by name on any port; containers on different switches cannot see each other at all; and the host only reaches containers through explicitly published ports.

The "user-defined" qualifier matters: the legacy default bridge (what you get with a bare docker run) does not provide DNS between containers. Always create and use named networks, compose does this automatically per project.

ports vs expose, settled
ports: "8080:3000" binds host port 8080 to the container’s 3000, this is the doorway from the outside world (and the internet, if the firewall allows). Each host port can be bound once
expose: 3000 is documentation only; it changes no behaviour. Containers on a shared network can already reach any port the other container listens on
The production rule: only the reverse proxy publishes ports (80/443); every app and database stays network-internal, this eliminates port conflicts and accidental public databases in one stroke

Why localhost breaks, and what to use instead
Inside a container, localhost is that container’s own loopback interface, not the host, not sibling containers. The two fixes cover 95% of cases: to reach a sibling service, use its network name (postgres, redis, api); to reach something on the host machine, use host.docker.internal (add the extra_hosts mapping on Linux).

The mirror-image bug: an app inside a container binding to 127.0.0.1 is unreachable even with published ports, because the publish forwards to the container’s external interface. Containerized servers must listen on 0.0.0.0.

Linux: make host.docker.internal work

extra_hosts:
- "host.docker.internal:host-gateway"

A platform-shaped example
A typical Peon-managed server runs one shared network (peon) where the proxy, your apps and your databases all live. The proxy publishes 80/443 and routes by hostname; your app reaches its database at postgres-abc:5432 by name; nothing else touches host ports. Two different apps can each listen on "port 3000" internally without any conflict, because host ports are simply not part of the design.

Inspection toolkit
When connectivity confuses you, these four commands answer it empirically:
docker network ls # what switches exist
docker network inspect peon | jq '.[0].Containers' # who is attached
docker exec app getent hosts postgres # does DNS resolve?
docker exec app wget -qO- http://api:3000/health # can I actually reach it?

Environment Variables in Docker Compose: env_file, environment and Interpolation

Peon Sh — Thu, 27 Aug 2026 04:57:44 +0000

The three ways Compose handles env vars, which one wins on conflicts, and how to keep secrets out of Git while staying reproducible.

Three mechanisms that look alike and are not
Compose gives you three distinct ways to get values into containers, and most env-related confusion comes from blurring them:

environment: entries in the compose file, set directly on the container; highest precedence; visible to anyone reading the file
env_file: loads KEY=value lines from a named file into the container at start
${VAR} interpolation: substitutes values into the compose file itself at parse time, from your shell or from a .env file sitting next to docker-compose.yml

The classic confusion: .env does not enter containers
The .env file next to your compose file feeds interpolation of the YAML, it is not automatically injected into any container. DB_PASSWORD=secret in .env does nothing for your app unless the compose file passes it through explicitly. The symptom is maddening: the variable exists on the host, echo shows it, and the container sees nothing.

.env (next to docker-compose.yml)

DB_PASSWORD=s3cret
# docker-compose.yml: must reference it to pass it through
services:
app:
environment:
DB_PASSWORD: ${DB_PASSWORD}   # now it reaches the container

Precedence, definitively
When the same key appears in multiple places, the order is: values from your shell override the .env file (for interpolation); and on the container, environment: entries override env_file: entries. One subtle trap: an interpolation with no value becomes an empty string silently, use ${VAR:?err} syntax to make missing required values fail the deploy loudly instead.

environment:
DATABASE_URL: ${DATABASE_URL:?DATABASE_URL must be set} # fail fast
LOG_LEVEL: ${LOG_LEVEL:-info} # default value

eeping secrets out of Git
The pattern that scales: commit the compose file with ${PLACEHOLDERS} and defaults for non-secrets; never commit real values; inject them at deploy time from a secrets store. A deployment platform formalizes this, Peon stores variables encrypted at rest, renders them when deploying the stack, and offers workspace-level shared variables so one API key serves ten services without ten copies. Rotating a credential becomes: change it in one place, redeploy consumers.

Debugging what a container actually received
Stop guessing; look:

Remember the lifecycle: env changes apply on container recreation, restart alone does not re-read env_file or compose changes
And the classic Next.js/CRA trap: build-time variables (NEXT_PUBLIC_*) must exist during the image build, not just in the runtime environment

docker exec env | sort # runtime truth
docker compose config # fully interpolated YAML
docker inspect --format '{{json .Config.Env}}' | jq

How to Reduce Docker Image Size: From Gigabytes to Megabytes

Peon Sh — Thu, 27 Aug 2026 04:49:34 +0000

Multi-stage builds, slim bases, layer ordering and .dockerignore, the techniques that cut image size by 90% and speed up every deploy.

Why size matters more than it seems
Image size is not aesthetic. Every gigabyte is pulled on deploy, stored per host, kept per release for rollbacks, and pruned eventually by someone at 2 a.m. when the disk fills. Big images slow every deploy, stretch rollback windows, and inflate the attack surface (more packages, more CVEs in every scan). The good news: 90% reductions are routine with four techniques, none of which change your application code.

Technique 1: multi-stage builds
The heavy hitter. Build with the full toolchain image; copy only the artifacts into a minimal runtime stage. Compilers, dev dependencies and source never reach production:

FROM node:22 AS build # fat: toolchain, dev deps
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-slim # thin: runtime only
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/index.js"]

Technique 2: pick the right base

node:22 (full Debian): ~1 GB, never for production
node:22-slim: ~200 MB, the safe default; glibc, so native modules just work
node:22-alpine: ~130 MB, smallest mainstream option; musl libc occasionally breaks native modules (sharp, canvas), test before committing
distroless: ~20 MB base with no shell or package manager, excellent security posture, harder to debug in
scratch/distroless-static: for compiled languages, Go and Rust binaries yield single-digit-MB images

Technique 3: layer ordering and .dockerignore
Docker caches layers top-down and invalidates everything below the first change. Order instructions least-to-most volatile: dependency manifests and installs before source code, so editing code never re-downloads dependencies. And always ship a .dockerignore, it shrinks the build context (faster uploads), keeps junk out of layers, and prevents secrets from leaking into image history:

.dockerignore

node_modules
.git
.next
dist
*.log
.env*

Technique 4: measure, don’t guess
docker history shows the size each instruction added, the offender is usually obvious. The dive tool goes deeper, showing files per layer and wasted space from files added then deleted in later layers (which does not reclaim size unless done in the same RUN). Combine cleanup with installation in one instruction: apt-get install with rm -rf /var/lib/apt/lists/* in the same RUN, or use --no-cache flags on alpine’s apk.

Expected results
Node/Next.js app: 1.1 GB naive to 130-180 MB (multi-stage + slim + standalone output)
Python/Django: 950 MB to ~180 MB (multi-stage + python:slim)
Go service: any size to 8-15 MB (static binary + distroless)
Operationally: deploys move seconds of data instead of minutes, rollbacks are instant, disks stop filling, and platform build caches (like Peon’s on-server layer cache) stay effective because only your app layer changes per push