Dockerfile ARG and ENV for build-time configuration

<p>Docker images need different configuration for different environments (staging vs production). Hardcoding config in the Dockerfile or passing everything at runtime isn't sufficient — some values must be baked in at build time (like the app version).</p>

<p>Use <code>ARG</code> for build-time variables and <code>ENV</code> for runtime variables:</p> <div class="highlight"><pre><span></span><code><span class="c"># Dockerfile</span> <span class="k">FROM</span><span class="w"> </span><span class="s">python:3.12-slim</span> <span class="c"># ARG: only available during build, not at runtime</span> <span class="k">ARG</span><span class="w"> </span><span class="nv">BUILD_VERSION</span><span class="o">=</span>dev <span class="k">ARG</span><span class="w"> </span><span class="nv">COMMIT_SHA</span><span class="o">=</span>unknown <span class="k">ARG</span><span class="w"> </span>BUILD_DATE <span class="c"># Convert build-time ARG to runtime ENV where needed</span> <span class="k">ENV</span><span class="w"> </span><span class="nv">APP_VERSION</span><span class="o">=</span><span class="si">${</span><span class="nv">BUILD_VERSION</span><span class="si">}</span> <span class="k">ENV</span><span class="w"> </span><span class="nv">COMMIT_SHA</span><span class="o">=</span><span class="si">${</span><span class="nv">COMMIT_SHA</span><span class="si">}</span> <span class="c"># ENV: available at runtime</span> <span class="k">ENV</span><span class="w"> </span><span class="nv">PYTHONUNBUFFERED</span><span class="o">=</span><span class="m">1</span> <span class="k">ENV</span><span class="w"> </span><span class="nv">PYTHONDONTWRITEBYTECODE</span><span class="o">=</span><span class="m">1</span> <span class="k">ENV</span><span class="w"> </span><span class="nv">PORT</span><span class="o">=</span><span class="m">8000</span> <span class="c"># Embed build metadata</span> <span class="k">LABEL</span><span class="w"> </span>org.opencontainers.image.version<span class="o">=</span><span class="si">${</span><span class="nv">BUILD_VERSION</span><span class="si">}</span> <span class="k">LABEL</span><span class="w"> </span>org.opencontainers.image.revision<span class="o">=</span><span class="si">${</span><span class="nv">COMMIT_SHA</span><span class="si">}</span> <span class="k">LABEL</span><span class="w"> </span>org.opencontainers.image.created<span class="o">=</span><span class="si">${</span><span class="nv">BUILD_DATE</span><span class="si">}</span> <span class="k">WORKDIR</span><span class="w"> </span><span class="s">/app</span> <span class="k">COPY</span><span class="w"> </span>.<span class="w"> </span>. <span class="k">RUN</span><span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>. <span class="k">CMD</span><span class="w"> </span><span class="p">[</span><span class="s2">"uvicorn"</span><span class="p">,</span><span class="w"> </span><span class="s2">"app.main:app"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--host"</span><span class="p">,</span><span class="w"> </span><span class="s2">"0.0.0.0"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--port"</span><span class="p">,</span><span class="w"> </span><span class="s2">"8000"</span><span class="p">]</span> </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># Pass ARGs at build time</span> docker<span class="w"> </span>build<span class="w"> </span><span class="se">\</span> <span class="w"> </span>--build-arg<span class="w"> </span><span class="nv">BUILD_VERSION</span><span class="o">=</span><span class="k">$(</span>git<span class="w"> </span>describe<span class="w"> </span>--tags<span class="k">)</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--build-arg<span class="w"> </span><span class="nv">COMMIT_SHA</span><span class="o">=</span><span class="k">$(</span>git<span class="w"> </span>rev-parse<span class="w"> </span>--short<span class="w"> </span>HEAD<span class="k">)</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>--build-arg<span class="w"> </span><span class="nv">BUILD_DATE</span><span class="o">=</span><span class="k">$(</span>date<span class="w"> </span>-u<span class="w"> </span>+%Y-%m-%dT%H:%M:%SZ<span class="k">)</span><span class="w"> </span><span class="se">\</span> <span class="w"> </span>-t<span class="w"> </span>myapp:<span class="k">$(</span>git<span class="w"> </span>describe<span class="w"> </span>--tags<span class="k">)</span><span class="w"> </span>. <span class="c1"># Override ENV at runtime</span> docker<span class="w"> </span>run<span class="w"> </span><span class="se">\</span> <span class="w"> </span>-e<span class="w"> </span><span class="nv">DATABASE_URL</span><span class="o">=</span>postgresql://...<span class="w"> </span><span class="se">\</span> <span class="w"> </span>-e<span class="w"> </span><span class="nv">REDIS_URL</span><span class="o">=</span>redis://...<span class="w"> </span><span class="se">\</span> <span class="w"> </span>myapp:latest </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># GitHub Actions integration</span> <span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Build</span> <span class="w"> </span><span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">docker/build-push-action@v5</span> <span class="w"> </span><span class="nt">with</span><span class="p">:</span> <span class="w"> </span><span class="nt">build-args</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span> <span class="w"> </span><span class="no">BUILD_VERSION=${{ github.ref_name }}</span> <span class="w"> </span><span class="no">COMMIT_SHA=${{ github.sha }}</span> <span class="w"> </span><span class="no">BUILD_DATE=${{ steps.date.outputs.date }}</span> </code></pre></div> <p>Key: <code>ARG</code> values don't persist past the build stage they're defined in (use them before <code>FROM</code> for global or after <code>FROM</code> for stage-specific). Never put secrets in <code>ARG</code> — they appear in <code>docker history</code>. Use runtime <code>ENV</code> or Docker secrets for sensitive values.</p>