mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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.
828 lines
30 KiB
HTML
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: '3.8'
|
|
|
|
services:
|
|
web:
|
|
image: nginx:alpine
|
|
ports:
|
|
- "8080:80"
|
|
volumes:
|
|
- ./html:/usr/share/nginx/html
|
|
networks:
|
|
- frontend
|
|
|
|
api:
|
|
build: ./api
|
|
ports:
|
|
- "3000:3000"
|
|
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
|
|
- "8080:80"
|
|
volumes: # Mounts
|
|
- ./data:/data
|
|
environment: # Environment variables
|
|
- DEBUG=true
|
|
depends_on: # Service dependencies
|
|
- db
|
|
networks: # Networks to join
|
|
- frontend
|
|
command: ["npm", "start"] # 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 'latest'
|
|
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:
|
|
- "8080:80" # Host 8080 → Container 80
|
|
- "443:443"
|
|
- "127.0.0.1:3000:3000" # Bind to localhost only</code></pre>
|
|
<p><strong>Expose (internal only)</strong>:</p>
|
|
<pre><code class="lang-yaml">services:
|
|
api:
|
|
expose:
|
|
- "3000" # Accessible to other services, not host</code></pre>
|
|
<p><strong>Dynamic ports</strong>:</p>
|
|
<pre><code class="lang-yaml">services:
|
|
web:
|
|
ports:
|
|
- "8080" # 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: ":/export/data"</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 'default' network
|
|
api:
|
|
# Can reach 'web' via hostname 'web'</code></pre>
|
|
<p><strong>Services communicate via service name</strong>:</p>
|
|
<pre><code class="lang-bash"># Inside 'api' 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 'web'
|
|
|
|
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'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: ["CMD-SHELL", "pg_isready -U postgres"]
|
|
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: ["CMD-SHELL", "pg_isready -U postgres"]
|
|
|
|
# MySQL
|
|
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
|
|
|
|
# Redis
|
|
test: ["CMD", "redis-cli", "ping"]
|
|
|
|
# HTTP endpoint
|
|
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
|
|
|
|
# Custom script
|
|
test: ["CMD", "/app/healthcheck.sh"]</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 < 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: '3.8'
|
|
|
|
services:
|
|
web:
|
|
build: .
|
|
ports:
|
|
- "8000:8000"
|
|
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: ["CMD-SHELL", "pg_isready -U user"]
|
|
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: '3.8'
|
|
|
|
services:
|
|
frontend:
|
|
build: ./frontend
|
|
ports:
|
|
- "3000:3000"
|
|
volumes:
|
|
- ./frontend:/app
|
|
- /app/node_modules
|
|
environment:
|
|
- REACT_APP_API_URL=http://localhost:8000
|
|
networks:
|
|
- frontend
|
|
|
|
backend:
|
|
build: ./backend
|
|
ports:
|
|
- "8000:8000"
|
|
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: '3.8'
|
|
|
|
services:
|
|
app:
|
|
build:
|
|
context: .
|
|
target: development # Multi-stage build
|
|
ports:
|
|
- "3000:3000"
|
|
volumes:
|
|
- ./src:/app/src:delegated # Sync source code
|
|
- /app/node_modules # Don'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: '3.8'
|
|
services:
|
|
app:
|
|
image: myapp:latest
|
|
ports:
|
|
- "8000:8000"</code></pre>
|
|
<p><strong>docker-compose.override.yml</strong> (development, auto-loaded):</p>
|
|
<pre><code class="lang-yaml">version: '3.8'
|
|
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: '3.8'
|
|
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: ["CMD", "curl", "-f", "http://localhost:8000/health"]
|
|
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: '1.0'
|
|
memory: 512M
|
|
reservations:
|
|
cpus: '0.5'
|
|
memory: 256M</code></pre>
|
|
<hr>
|
|
<h2>Troubleshooting</h2>
|
|
<h3>Issue 1: Services Can'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: '/data/file.txt'</code></p>
|
|
<p><strong>Solution</strong>: Match user IDs</p>
|
|
<pre><code class="lang-yaml">services:
|
|
app:
|
|
user: "${UID}:${GID}"
|
|
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 <PID>
|
|
|
|
# Or use different port
|
|
# ports: - "8081:8080"</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> |