When 'localhost' Broke My Entire Docker Setup

When “localhost” Broke My Entire Docker Setup

I had a Spring Boot application that worked flawlessly on my local machine. Then I moved it to Docker… and everything broke. The app couldn’t connect to PostgreSQL

What made it worse?

Everything looked correct:

• Database container was running
• Credentials were correct
• Docker containers were up and healthy

Still, the connection kept failing.

The Mistake My configuration looked completely normal:

spring.datasource.url=jdbc:postgresql://localhost:5432/<database>.db

And that’s exactly why I missed the problem.

This works perfectly on a local setup. But inside Docker, it fails — silently.

The Reality of Containers

Inside a container, localhost doesn’t mean your machine. It points to the container itself. So my Spring Boot container was trying to connect to PostgreSQL inside its own container, where no database existed.

The Fix

The fix was simple, but not obvious:

spring.datasource.url=jdbc:postgresql://db:5432/<database_name>.db

Here,db is the service name defined in Docker Compose. Docker automatically provides internal DNS, allowing containers to talk to each other using service names.

No IPs. No localhost. Just names.

What This Taught Me

This wasn’t a coding bug. It was a misunderstanding of how the environment works. I was thinking in terms of:

• Local machine networking

Instead of:

• Container-to-container communication

That small difference cost hours.

✅ Key Takeaways

• Containers are isolated environments
• localhost is relative to each container
• Use Docker Compose service names for communication
• Most DevOps issues are mental model problems, not code problems
• Sometimes the hardest bugs aren’t in your code — they’re in your assumptions.