Files
skills/public/containers-docker-compose-development.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

828 lines
30 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>containers-docker-compose-development</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/containers-docker-compose-development">
<link rel="alternate" type="text/markdown" href="/containers-docker-compose-development.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/containers-docker-compose-development.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>containers-docker-compose-development</h1><p class="lede">Setting up local development environments</p><h1>Docker Compose Development</h1>
<p><strong>Scope</strong>: Compose files, networking, volumes, service dependencies, healthchecks <strong>Lines</strong>: ~280 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Setting up local development environments</li><li>Orchestrating multi-container applications</li><li>Defining service dependencies and startup order</li><li>Configuring container networking</li><li>Managing persistent data with volumes</li><li>Implementing health checks</li><li>Creating reproducible development environments</li><li>Debugging container connectivity issues</li></ul>
<h2>Core Concepts</h2>
<h3>What is Docker Compose?</h3>
<p><strong>Docker Compose</strong>: Tool for defining and running multi-container Docker applications.</p>
<p><strong>Key properties</strong>:</p>
<ul><li><strong>Declarative</strong>: Define services in YAML (<code>docker-compose.yml</code>)</li><li><strong>Reproducible</strong>: Same environment across machines</li><li><strong>Isolated</strong>: Separate network per project</li><li><strong>Convenient</strong>: Single command to start/stop all services</li><li><strong>Development-focused</strong>: Not for production (use Kubernetes/Swarm)</li></ul>
<p><strong>Basic workflow</strong>:</p>
<pre><code class="lang-bash">docker compose up # Start all services
docker compose down # Stop and remove containers
docker compose logs # View logs
docker compose ps # List running containers</code></pre>
<hr>
<h2>Docker Compose File Structure</h2>
<h3>Basic Compose File (v3.8+)</h3>
<pre><code class="lang-yaml">version: &#x27;3.8&#x27;
services:
web:
image: nginx:alpine
ports:
- &quot;8080:80&quot;
volumes:
- ./html:/usr/share/nginx/html
networks:
- frontend
api:
build: ./api
ports:
- &quot;3000:3000&quot;
environment:
- DATABASE_URL=postgres://user:pass@db:5432/mydb
depends_on:
- db
networks:
- frontend
- backend
db:
image: postgres:16
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: mydb
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- backend
networks:
frontend:
backend:
volumes:
postgres_data:</code></pre>
<h3>Service Definition Keys</h3>
<p><strong>Essential keys</strong>:</p>
<pre><code class="lang-yaml">services:
app:
image: myapp:latest # Pre-built image
build: ./app # Build from Dockerfile
container_name: my_app # Custom container name
ports: # Port mapping
- &quot;8080:80&quot;
volumes: # Mounts
- ./data:/data
environment: # Environment variables
- DEBUG=true
depends_on: # Service dependencies
- db
networks: # Networks to join
- frontend
command: [&quot;npm&quot;, &quot;start&quot;] # Override default command
restart: unless-stopped # Restart policy</code></pre>
<hr>
<h2>Service Configuration</h2>
<h3>Building Images</h3>
<p><strong>Simple build</strong>:</p>
<pre><code class="lang-yaml">services:
app:
build: ./app # Dockerfile in ./app directory</code></pre>
<p><strong>Advanced build</strong>:</p>
<pre><code class="lang-yaml">services:
app:
build:
context: ./app # Build context
dockerfile: Dockerfile.dev # Custom Dockerfile name
args: # Build arguments
- NODE_ENV=development
target: development # Multi-stage build target
cache_from: # Cache sources
- myapp:latest</code></pre>
<h3>Environment Variables</h3>
<p><strong>Inline</strong>:</p>
<pre><code class="lang-yaml">services:
app:
environment:
- DEBUG=true
- API_KEY=secret123</code></pre>
<p><strong>From .env file</strong>:</p>
<pre><code class="lang-yaml">services:
app:
env_file:
- .env
- .env.local</code></pre>
<p><strong>.env file</strong>:</p>
<pre><code class="lang-bash">DEBUG=true
DATABASE_URL=postgres://localhost/mydb
API_KEY=secret123</code></pre>
<p><strong>Using environment in compose</strong>:</p>
<pre><code class="lang-yaml">services:
app:
image: myapp:${TAG:-latest} # Default to &#x27;latest&#x27;
environment:
- DATABASE_URL=${DATABASE_URL}</code></pre>
<h3>Port Mapping</h3>
<p><strong>Host:Container mapping</strong>:</p>
<pre><code class="lang-yaml">services:
web:
ports:
- &quot;8080:80&quot; # Host 8080 → Container 80
- &quot;443:443&quot;
- &quot;127.0.0.1:3000:3000&quot; # Bind to localhost only</code></pre>
<p><strong>Expose (internal only)</strong>:</p>
<pre><code class="lang-yaml">services:
api:
expose:
- &quot;3000&quot; # Accessible to other services, not host</code></pre>
<p><strong>Dynamic ports</strong>:</p>
<pre><code class="lang-yaml">services:
web:
ports:
- &quot;8080&quot; # Docker assigns random host port</code></pre>
<hr>
<h2>Volumes and Data Persistence</h2>
<h3>Volume Types</h3>
<p><strong>Named volumes</strong> (managed by Docker):</p>
<pre><code class="lang-yaml">services:
db:
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data: # Docker manages storage</code></pre>
<p><strong>Bind mounts</strong> (host directory):</p>
<pre><code class="lang-yaml">services:
app:
volumes:
- ./app:/app # Sync local code
- ./config:/etc/config:ro # Read-only</code></pre>
<p><strong>tmpfs</strong> (in-memory):</p>
<pre><code class="lang-yaml">services:
app:
tmpfs:
- /tmp
- /run</code></pre>
<h3>Volume Configuration</h3>
<p><strong>Advanced volume options</strong>:</p>
<pre><code class="lang-yaml">volumes:
postgres_data:
driver: local
driver_opts:
type: none
o: bind
device: /path/on/host
nfs_data:
driver: local
driver_opts:
type: nfs
o: addr=192.168.1.100,rw
device: &quot;:/export/data&quot;</code></pre>
<h3>Bind Mount Performance (Mac/Windows)</h3>
<p><strong>Problem</strong>: Bind mounts are slow on Mac/Windows.</p>
<p><strong>Solution</strong>: Use delegated/cached modes:</p>
<pre><code class="lang-yaml">services:
app:
volumes:
- ./app:/app:delegated # Performance over consistency
- ./logs:/logs:cached # Container writes prioritized</code></pre>
<p><strong>Modes</strong>:</p>
<ul><li><code>consistent</code> - Default, slowest, most consistent</li><li><code>delegated</code> - Host writes delayed to container (faster)</li><li><code>cached</code> - Container writes delayed to host (faster)</li></ul>
<hr>
<h2>Networking</h2>
<h3>Default Bridge Network</h3>
<p><strong>Automatic</strong>:</p>
<pre><code class="lang-yaml">services:
web:
# Automatically joins &#x27;default&#x27; network
api:
# Can reach &#x27;web&#x27; via hostname &#x27;web&#x27;</code></pre>
<p><strong>Services communicate via service name</strong>:</p>
<pre><code class="lang-bash"># Inside &#x27;api&#x27; container
curl http://web:80</code></pre>
<h3>Custom Networks</h3>
<pre><code class="lang-yaml">services:
web:
networks:
- frontend
api:
networks:
- frontend
- backend
db:
networks:
- backend # Isolated from &#x27;web&#x27;
networks:
frontend:
backend:</code></pre>
<p><strong>Result</strong>: <code>web</code> and <code>api</code> can communicate, <code>web</code> and <code>db</code> cannot.</p>
<h3>Network Aliases</h3>
<pre><code class="lang-yaml">services:
api:
networks:
frontend:
aliases:
- api-server
- backend-api</code></pre>
<p><strong>Access via</strong>:</p>
<pre><code class="lang-bash">curl http://api:3000
curl http://api-server:3000
curl http://backend-api:3000</code></pre>
<h3>External Networks</h3>
<pre><code class="lang-yaml">networks:
existing-network:
external: true # Use existing network
services:
app:
networks:
- existing-network</code></pre>
<h3>Network Drivers</h3>
<pre><code class="lang-yaml">networks:
frontend:
driver: bridge # Default (single host)
overlay:
driver: overlay # Multi-host (Swarm)
host:
driver: host # Use host network (no isolation)</code></pre>
<hr>
<h2>Service Dependencies</h2>
<h3>depends_on (Basic)</h3>
<pre><code class="lang-yaml">services:
api:
depends_on:
- db
- redis
db:
image: postgres:16
redis:
image: redis:7</code></pre>
<p><strong>Behavior</strong>: Starts <code>db</code> and <code>redis</code> before <code>api</code>.</p>
<p><strong>Limitation</strong>: Doesn&#x27;t wait for services to be <strong>ready</strong>, only <strong>started</strong>.</p>
<h3>Health Checks (Wait for Ready)</h3>
<pre><code class="lang-yaml">services:
db:
image: postgres:16
healthcheck:
test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U postgres&quot;]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
api:
depends_on:
db:
condition: service_healthy # Wait for healthy</code></pre>
<p><strong>Health check commands</strong>:</p>
<pre><code class="lang-yaml"># Postgres
test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U postgres&quot;]
# MySQL
test: [&quot;CMD&quot;, &quot;mysqladmin&quot;, &quot;ping&quot;, &quot;-h&quot;, &quot;localhost&quot;]
# Redis
test: [&quot;CMD&quot;, &quot;redis-cli&quot;, &quot;ping&quot;]
# HTTP endpoint
test: [&quot;CMD&quot;, &quot;curl&quot;, &quot;-f&quot;, &quot;http://localhost:8080/health&quot;]
# Custom script
test: [&quot;CMD&quot;, &quot;/app/healthcheck.sh&quot;]</code></pre>
<h3>Long Dependencies (Retry Logic)</h3>
<p><strong>Problem</strong>: Some services take time to initialize.</p>
<p><strong>Solution</strong>: Use <code>restart</code> + application-level retries:</p>
<pre><code class="lang-yaml">services:
api:
depends_on:
- db
restart: on-failure
environment:
- DB_RETRY_ATTEMPTS=10
- DB_RETRY_DELAY=5</code></pre>
<p><strong>Application code</strong> (example in Python):</p>
<pre><code class="lang-python">import time
import psycopg2
def connect_with_retry(max_attempts=10, delay=5):
for attempt in range(max_attempts):
try:
conn = psycopg2.connect(DATABASE_URL)
return conn
except psycopg2.OperationalError:
if attempt &lt; max_attempts - 1:
time.sleep(delay)
else:
raise</code></pre>
<hr>
<h2>Common Service Patterns</h2>
<h3>Pattern 1: Web App + Database + Redis</h3>
<pre><code class="lang-yaml">version: &#x27;3.8&#x27;
services:
web:
build: .
ports:
- &quot;8000:8000&quot;
environment:
- DATABASE_URL=postgres://user:pass@db:5432/mydb
- REDIS_URL=redis://redis:6379
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
volumes:
- ./app:/app
networks:
- app-network
db:
image: postgres:16
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: mydb
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U user&quot;]
interval: 10s
timeout: 5s
retries: 5
networks:
- app-network
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
networks:
- app-network
networks:
app-network:
volumes:
postgres_data:
redis_data:</code></pre>
<h3>Pattern 2: Frontend + Backend + Database</h3>
<pre><code class="lang-yaml">version: &#x27;3.8&#x27;
services:
frontend:
build: ./frontend
ports:
- &quot;3000:3000&quot;
volumes:
- ./frontend:/app
- /app/node_modules
environment:
- REACT_APP_API_URL=http://localhost:8000
networks:
- frontend
backend:
build: ./backend
ports:
- &quot;8000:8000&quot;
environment:
- DATABASE_URL=postgres://user:pass@db:5432/mydb
depends_on:
- db
volumes:
- ./backend:/app
networks:
- frontend
- backend
db:
image: postgres:16
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: mydb
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- backend
networks:
frontend:
backend:
volumes:
postgres_data:</code></pre>
<h3>Pattern 3: Development with Live Reload</h3>
<pre><code class="lang-yaml">version: &#x27;3.8&#x27;
services:
app:
build:
context: .
target: development # Multi-stage build
ports:
- &quot;3000:3000&quot;
volumes:
- ./src:/app/src:delegated # Sync source code
- /app/node_modules # Don&#x27;t sync node_modules
environment:
- NODE_ENV=development
- CHOKIDAR_USEPOLLING=true # File watching (Windows/Mac)
command: npm run dev # Override with dev command</code></pre>
<hr>
<h2>Docker Compose Commands</h2>
<h3>Starting and Stopping</h3>
<pre><code class="lang-bash"># Start all services (attached)
docker compose up
# Start in background (detached)
docker compose up -d
# Start specific services
docker compose up web db
# Rebuild images
docker compose up --build
# Stop services
docker compose stop
# Stop and remove containers
docker compose down
# Remove containers, volumes, networks
docker compose down -v</code></pre>
<h3>Viewing Logs</h3>
<pre><code class="lang-bash"># All services
docker compose logs
# Follow logs
docker compose logs -f
# Specific service
docker compose logs web
# Last N lines
docker compose logs --tail=100 web
# Timestamps
docker compose logs -t</code></pre>
<h3>Running Commands</h3>
<pre><code class="lang-bash"># Execute command in running container
docker compose exec web sh
# Run one-off command (new container)
docker compose run web npm test
# Run without starting dependencies
docker compose run --no-deps web npm test</code></pre>
<h3>Inspecting Services</h3>
<pre><code class="lang-bash"># List running containers
docker compose ps
# List all containers (including stopped)
docker compose ps -a
# Show service configuration
docker compose config
# Validate compose file
docker compose config --quiet</code></pre>
<hr>
<h2>Development Workflow Best Practices</h2>
<h3>Practice 1: Environment-Specific Overrides</h3>
<p><strong>docker-compose.yml</strong> (base):</p>
<pre><code class="lang-yaml">version: &#x27;3.8&#x27;
services:
app:
image: myapp:latest
ports:
- &quot;8000:8000&quot;</code></pre>
<p><strong>docker-compose.override.yml</strong> (development, auto-loaded):</p>
<pre><code class="lang-yaml">version: &#x27;3.8&#x27;
services:
app:
build: .
volumes:
- ./src:/app/src
environment:
- DEBUG=true</code></pre>
<p><strong>docker-compose.prod.yml</strong> (production):</p>
<pre><code class="lang-yaml">version: &#x27;3.8&#x27;
services:
app:
image: myapp:v1.2.3
restart: always</code></pre>
<p><strong>Use</strong>:</p>
<pre><code class="lang-bash"># Development (auto-loads override)
docker compose up
# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up</code></pre>
<h3>Practice 2: Health Checks for All Services</h3>
<pre><code class="lang-yaml">services:
web:
healthcheck:
test: [&quot;CMD&quot;, &quot;curl&quot;, &quot;-f&quot;, &quot;http://localhost:8000/health&quot;]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s</code></pre>
<h3>Practice 3: Resource Limits</h3>
<pre><code class="lang-yaml">services:
app:
deploy:
resources:
limits:
cpus: &#x27;1.0&#x27;
memory: 512M
reservations:
cpus: &#x27;0.5&#x27;
memory: 256M</code></pre>
<hr>
<h2>Troubleshooting</h2>
<h3>Issue 1: Services Can&#x27;t Communicate</h3>
<p><strong>Symptom</strong>: <code>curl: (6) Could not resolve host: api</code></p>
<p><strong>Solution</strong>: Check networks</p>
<pre><code class="lang-bash"># Ensure services on same network
docker compose config | grep networks
# Verify DNS
docker compose exec web ping api</code></pre>
<h3>Issue 2: Permission Denied (Volumes)</h3>
<p><strong>Symptom</strong>: <code>Permission denied: &#x27;/data/file.txt&#x27;</code></p>
<p><strong>Solution</strong>: Match user IDs</p>
<pre><code class="lang-yaml">services:
app:
user: &quot;${UID}:${GID}&quot;
volumes:
- ./data:/data</code></pre>
<pre><code class="lang-bash"># Set in .env
UID=1000
GID=1000</code></pre>
<h3>Issue 3: Port Already in Use</h3>
<p><strong>Symptom</strong>: <code>Bind for 0.0.0.0:8080 failed: port is already allocated</code></p>
<p><strong>Solution</strong>: Change host port or stop conflicting service</p>
<pre><code class="lang-bash"># Find process
lsof -i :8080
# Kill process
kill -9 &lt;PID&gt;
# Or use different port
# ports: - &quot;8081:8080&quot;</code></pre>
<hr>
<h2>Docker Compose Checklist</h2>
<pre><code>Configuration:
[ ] Use version 3.8+
[ ] Define named volumes for persistence
[ ] Configure custom networks for isolation
[ ] Use .env files for secrets (not committed to git)
[ ] Pin image versions (not :latest)
Development:
[ ] Use bind mounts for live code reload
[ ] Configure health checks
[ ] Set depends_on with conditions
[ ] Use docker-compose.override.yml for local config
[ ] Enable file watching (CHOKIDAR_USEPOLLING)
Production:
[ ] Use built images (not build context)
[ ] Set restart policies (restart: always)
[ ] Configure resource limits
[ ] Use production compose file override
[ ] Remove debug/dev tools
Networking:
[ ] Isolate services with custom networks
[ ] Expose only necessary ports
[ ] Use service names for DNS
[ ] Configure network aliases if needed</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><code>dockerfile-optimization.md</code> - Building efficient images</li><li><code>container-security.md</code> - Securing containers</li><li><code>container-networking.md</code> - Advanced networking</li><li><code>kubernetes-basics.md</code> - Production orchestration</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-18 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/containers-docker-compose-development.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>