Docker Compose networking and service discovery

<p>My Docker Compose setup has FastAPI, PostgreSQL, Redis, and a background worker. The services need to talk to each other. I am confused about when to use service names vs localhost, and how ports work inside vs outside the compose network.</p>

<p>Docker Compose creates a default network where services communicate by service name:</p> <div class="highlight"><pre><span></span><code><span class="nt">services</span><span class="p">:</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="c1"># No ports: -- not exposed to host in production</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">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">ports</span><span class="p">:</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">"8000:8000"</span><span class="w"> </span><span class="c1"># Exposes to host machine</span> <span class="w"> </span><span class="nt">environment</span><span class="p">:</span> <span class="w"> </span><span class="c1"># Use SERVICE NAME, not localhost:</span> <span class="w"> </span><span class="nt">DATABASE_URL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">postgresql+asyncpg://user:pass@postgres:5432/db</span> <span class="w"> </span><span class="nt">REDIS_URL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">redis://redis:6379</span> <span class="w"> </span><span class="nt">depends_on</span><span class="p">:</span> <span class="w"> </span><span class="nt">postgres</span><span class="p">:</span> <span class="w"> </span><span class="nt">condition</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">service_healthy</span> </code></pre></div> <p>Key points: - Inside Compose network: postgres:5432 not localhost:5432 - ports: opens port to the HOST machine (laptop or internet) - Services without ports are only reachable within the Compose network - localhost inside a container refers to THAT container, not the host</p>