App in Docker can't reach the database? Localhost isn't the host
Short answer: Inside a Docker container, localhost means the container itself, not your laptop or server. If your app connects to localhost:5432 for its database and the database runs in another container or on the host machine, the connection is refused because nothing is listening inside the app's own container. With Docker Compose, connect to the other service by its service name, such as db:5432. To reach something running on the host, Docker Desktop provides the name host.docker.internal, while on a Linux server you usually add that name yourself or connect through the host's address.
Why localhost stops working
Each container has its own network stack, so localhost or 127.0.0.1 inside it loops back to the same container. Before Docker, your app and database both ran on one machine, and localhost found the database. After moving only the app into a container, the same setting points at an empty port, and you see "connection refused" or a timeout.
The same applies to a cache, a search service, a mail catcher used in development or an internal API.
Containers talking to containers: use service names
Docker's Compose documentation explains that by default Compose sets up a single network for your app. Each service's container joins it and is reachable by other containers, and discoverable by its service name. So with services named web and db, the web app connects to host db.
A typical setup:
services:
web:
build: .
environment:
DATABASE_HOST: db
DATABASE_PORT: "5432"
db:
image: postgres:17
Docker's docs also say containers get a new IP address when recreated but keep the same name, which is why you should always use names rather than container IPs.
Watch the port numbers
A common second mistake is using the published port between containers. Compose's documentation spells out the difference: in ports: "8001:5432", 8001 is the host port and 5432 is the container port. Service-to-service traffic uses the container port, and the host port is only for access from outside the Docker network.
So inside Compose, the app connects to db:5432, while you might connect from your laptop's database tool to localhost:8001. Mixing them up gives a refused connection that looks like the same bug.
Reaching services on the host
Sometimes the database stays on the host machine, for example a managed local install you don't want to containerise yet.
On Docker Desktop (Mac and Windows): Docker's networking guide says to use the special DNS name host.docker.internal, which resolves to the internal IP address of your host. Connect to host.docker.internal:5432.
On a Linux server running Docker Engine: that name isn't always there by default. A common approach is to map it with extra_hosts in Compose, using Docker's special host-gateway value, or to connect to the IP address of the Docker bridge on the host.
Then check the host service itself:
- Is it listening on more than localhost? A database configured to listen only on
127.0.0.1won't accept connections arriving from the Docker bridge. Allow the bridge interface or address, not the whole internet. - Does its access control allow the container's network? Databases often have their own allow-lists of client addresses.
- Is a firewall in the way? Allow traffic from the Docker network to that port only.
Reaching containers from the host
The reverse problem has its own fix. Docker's guide says to publish ports with -p or --publish to access containerised services from your host or local network. In Compose, that's the ports setting. Publish only what you need, and bind development-only ports to 127.0.0.1 so they're not exposed to your whole network.
When the database isn't ready yet
Sometimes the name and port are right but the app starts before the database is ready to accept connections, especially on first start. Add retry logic to the app's database connection, and in Compose, consider a health check on the database with the app depending on it being healthy.
Keep settings per environment
Hard-coding localhost in the app is what makes this break in the first place. Read the database host, port and credentials from environment variables, with different values for a developer's laptop, the Compose setup and production. Document the expected values in the project's README so the next person doesn't rediscover the problem.
Debugging step by step
- Print the actual connection settings the app uses inside the container. Environment variables often differ from what you expect.
- Open a shell in the app container and try to resolve and connect to the target name and port with whatever tools the image has.
- Check both containers are on the same network. Docker's Compose guide has a debugging section on inspecting port mappings and verifying network membership.
- Check the database logs for refused or rejected connections, which show whether traffic arrives at all.
An illustrative example
A booking platform for a group of Dublin physiotherapy clinics is moved into Docker Compose for easier deployment. The app container crashes with "connection refused" to localhost:5432. The developer changes the database host to the db service name, keeps the container port 5432 for the app, publishes the database only as 127.0.0.1:5433 for local tools, and adds a health check so the app waits for the database. The mail catcher used in testing gets the same treatment.
FAQ
Can I use network_mode: host to keep localhost?
On Linux it makes the container share the host's network, so localhost works, but it removes isolation. It's a workaround, not a default.
Why does my database tool connect but my app doesn't?
Your tool runs on the host and uses the published port. The app runs inside the network and needs the service name and container port.
Do I need links between services?
Not with Compose's default network. Service names are enough.
Does this apply in production?
Yes. The same networking rules apply wherever containers run.
If your app broke when it moved into containers and you'd like the setup straightened out, tell us what runs in Docker and what doesn't.