Docker Compose networking and service discovery

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.

Docker Compose creates a default network where services communicate by service name:

services:
  postgres:
    image: pgvector/pgvector:pg17
    # No ports: -- not exposed to host in production
  redis:
    image: redis:7-alpine
  api:
    build: ./api
    ports:
      - "8000:8000"  # Exposes to host machine
    environment:
      # Use SERVICE NAME, not localhost:
      DATABASE_URL: postgresql+asyncpg://user:pass@postgres:5432/db
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy

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