Docker Compose environment variable files per environment

<p>Managing different configurations for development, staging, and production in Docker Compose. Hardcoding environment variables in compose files leads to secrets in version control and different configs for each environment.</p>

<p>Use <code>.env</code> files with Docker Compose's <code>env_file</code> directive and environment-specific override files:</p> <div class="highlight"><pre><span></span><code># .env.development (committed) DATABASE_URL=postgresql+asyncpg://dev:dev@postgres:5432/devdb DEBUG=true LOG_LEVEL=debug # .env.production (NOT committed — use secrets manager) DATABASE_URL=postgresql+asyncpg://user:secret@prod-host:5432/proddb DEBUG=false LOG_LEVEL=info </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># docker-compose.yml (base)</span> <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">build</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">./api</span> <span class="w"> </span><span class="nt">env_file</span><span class="p">:</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.env.${ENV:-development}</span> <span class="w"> </span><span class="nt">environment</span><span class="p">:</span> <span class="w"> </span><span class="c1"># Override specific vars (takes precedence over env_file)</span> <span class="w"> </span><span class="nt">APP_NAME</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CommonTrace</span> <span class="w"> </span><span class="c1"># docker-compose.production.yml (extends base)</span> <span class="w"> </span><span class="nt">api</span><span class="p">:</span> <span class="w"> </span><span class="nt">deploy</span><span class="p">:</span> <span class="w"> </span><span class="nt">replicas</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">resources</span><span class="p">:</span> <span class="w"> </span><span class="nt">limits</span><span class="p">:</span> <span class="w"> </span><span class="nt">memory</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">512M</span> </code></pre></div> <div class="highlight"><pre><span></span><code><span class="c1"># Run with specific environment</span> <span class="nv">ENV</span><span class="o">=</span>production<span class="w"> </span>docker-compose<span class="w"> </span>-f<span class="w"> </span>docker-compose.yml<span class="w"> </span>-f<span class="w"> </span>docker-compose.production.yml<span class="w"> </span>up<span class="w"> </span>-d <span class="c1"># Or set in .env file at project root (auto-loaded by Compose)</span> <span class="nb">echo</span><span class="w"> </span><span class="s1">'ENV=production'</span><span class="w"> </span>&gt;<span class="w"> </span>.env docker-compose<span class="w"> </span>up<span class="w"> </span>-d </code></pre></div> <div class="highlight"><pre><span></span><code># .gitignore .env .env.production .env.staging .env.*.local # Commit only: # .env.development # .env.example </code></pre></div> <p>Precedence order (highest to lowest): <code>environment:</code> block in compose file &gt; <code>env_file:</code> &gt; shell environment variables when running compose. Always provide a <code>.env.example</code> with all keys but no values.</p>