Docker healthcheck with curl vs wget and retry logic

<p>Docker Compose healthchecks fail because the container doesn't have curl or wget installed in a slim image. Need a working healthcheck that works in minimal Alpine and Debian-slim images, and handles startup time correctly.</p>

<p>Use Python's built-in HTTP or <code>nc</code> for healthchecks in minimal images:</p> <div class="highlight"><pre><span></span><code><span class="nt">services</span><span class="p">:</span> <span class="w"> </span><span class="nt">api</span><span class="p">:</span> <span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">myapp:latest</span> <span class="w"> </span><span class="nt">healthcheck</span><span class="p">:</span> <span class="w"> </span><span class="c1"># Works if Python is installed (guaranteed in Python images)</span> <span class="w"> </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"CMD"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"python3"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"-c"</span><span class="p p-Indicator">,</span> <span class="w"> </span><span class="s">"import</span><span class="nv"> </span><span class="s">urllib.request;</span><span class="nv"> </span><span class="s">urllib.request.urlopen('http://localhost:8000/health',</span><span class="nv"> </span><span class="s">timeout=2)"</span><span class="p p-Indicator">]</span> <span class="w"> </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10s</span> <span class="w"> </span><span class="nt">timeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5s</span> <span class="w"> </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span> <span class="w"> </span><span class="nt">start_period</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30s</span><span class="w"> </span><span class="c1"># Grace period before health failures count</span> <span class="w"> </span><span class="c1"># For Alpine-based images (has wget, not curl)</span> <span class="w"> </span><span class="nt">nginx</span><span class="p">:</span> <span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">nginx:alpine</span> <span class="w"> </span><span class="nt">healthcheck</span><span class="p">:</span> <span class="w"> </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"CMD"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"wget"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"--no-verbose"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"--tries=1"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"--spider"</span><span class="p p-Indicator">,</span> <span class="w"> </span><span class="s">"http://localhost:80/health"</span><span class="p p-Indicator">]</span> <span class="w"> </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30s</span> <span class="w"> </span><span class="nt">timeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10s</span> <span class="w"> </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span> <span class="w"> </span><span class="nt">start_period</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10s</span> <span class="w"> </span><span class="c1"># For postgres — use pg_isready (built-in)</span> <span class="w"> </span><span class="nt">postgres</span><span class="p">:</span> <span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pgvector/pgvector:pg17</span> <span class="w"> </span><span class="nt">healthcheck</span><span class="p">:</span> <span class="w"> </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"CMD-SHELL"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"pg_isready</span><span class="nv"> </span><span class="s">-U</span><span class="nv"> </span><span class="s">${POSTGRES_USER}</span><span class="nv"> </span><span class="s">-d</span><span class="nv"> </span><span class="s">${POSTGRES_DB}"</span><span class="p p-Indicator">]</span> <span class="w"> </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5s</span> <span class="w"> </span><span class="nt">timeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3s</span> <span class="w"> </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span> <span class="w"> </span><span class="nt">start_period</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">15s</span> <span class="w"> </span><span class="c1"># Redis — use redis-cli</span> <span class="w"> </span><span class="nt">redis</span><span class="p">:</span> <span class="w"> </span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis:7-alpine</span> <span class="w"> </span><span class="nt">healthcheck</span><span class="p">:</span> <span class="w"> </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">"CMD"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"redis-cli"</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">"ping"</span><span class="p p-Indicator">]</span> <span class="w"> </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5s</span> <span class="w"> </span><span class="nt">timeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2s</span> <span class="w"> </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span> </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># FastAPI health endpoint</span> <span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'/health'</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">health</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">:</span> <span class="k">return</span> <span class="p">{</span><span class="s1">'status'</span><span class="p">:</span> <span class="s1">'ok'</span><span class="p">,</span> <span class="s1">'version'</span><span class="p">:</span> <span class="n">settings</span><span class="o">.</span><span class="n">app_version</span><span class="p">}</span> </code></pre></div> <p><code>start_period</code> gives the container time to initialize — failures during this period don't count toward <code>retries</code>. Use <code>CMD-SHELL</code> when you need shell features (environment variable expansion). <code>CMD</code> (array form) is preferred — no shell injection risk.</p>