The goal was straightforward: run a MySQL client inside a Docker container and connect it to the MySQL database running on my local machine (the host). No docker-compose, no fancy setup. Just a container talking to my laptop's database.

What followed was a few hours of connection refused, some googling, and eventually understanding how Docker networking actually works under the hood.

Let me walk you through what I learned.

The Problem — Why 127.0.0.1 Doesn't Work Inside a Container

My first instinct was just to connect to 127.0.0.1. That's localhost, right? MySQL is running there.

mysql -h 127.0.0.1 -u root -p
# ERROR 2003 (HY000): Can't connect to MySQL server on '127.0.0.1'

Nope.

Here's the thing — inside a container, 127.0.0.1 is the container's own loopback. Not your machine. Your host machine doesn't exist at that address from inside the container. The container is living in its own isolated network. Your laptop is somewhere else entirely.

So where is your host machine from the container's perspective? That's where docker0 comes in.

What is docker0?

When you install Docker, it automatically creates a virtual network interface on your machine called docker0.

Run this on your host and you'll see it:

ip addr show docker0
# 3: docker0: inet 172.17.0.1/24

Think of docker0 as a virtual network switch that Docker manages. It has its own IP — usually 172.17.0.1 — and every container you run connects to it.

Your Machine
├── eth0        → your real network card (connects to internet/router)
└── docker0     → virtual bridge (172.17.0.1)
      ├── Container A (172.17.0.2)
      ├── Container B (172.17.0.3)
      └── Container C (172.17.0.4)

Each container gets connected to docker0 through something called a veth pair — a virtual ethernet cable. One end is inside the container (shows up as eth0 inside), the other end is plugged into docker0 on the host.

So from inside a container, your host machine is reachable at 172.17.0.1 — the docker0 IP.

Fix #1 — Change MySQL's Bind Address

Even once I knew the right IP, I still got refused. Because MySQL on my machine was configured to only accept connections from 127.0.0.1.

Check your MySQL config:

# usually at /etc/mysql/mysql.conf.d/mysqld.cnf
grep bind-address /etc/mysql/mysql.conf.d/mysqld.cnf
# bind-address = 127.0.0.1

That 127.0.0.1 means MySQL is only listening on localhost — it completely ignores any connection coming from the container subnet.

Change it to 0.0.0.0 so it listens on all interfaces:

bind-address = 0.0.0.0

Then restart MySQL:

sudo systemctl restart mysql

Fix #2 — Create a MySQL User for Docker

I didn't want to use root for this, so I created a dedicated MySQL user that's allowed to connect from the container subnet (172.17.0.%).

Log into MySQL on your host:

CREATE USER 'dockeruser'@'172.17.0.%' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON yourdb.* TO 'dockeruser'@'172.17.0.%';
FLUSH PRIVILEGES;

The 172.17.0.% means this user can connect from any IP in the container subnet — not just from localhost.

Fix #3 — Allow the Port Through the Firewall

One more thing I missed — my firewall was blocking port 3306 from the container network.

sudo ufw allow from 172.17.0.0/24 to any port 3306

Now from inside the container:

mysql -h 172.17.0.2 -u dockeruser -p
# Welcome to the MySQL monitor. 

Finally. It works.

But Wait — How Does the Internet Work from Inside a Container?

While I was debugging all this, I got curious about something else. If containers have these private IPs like 172.17.0.3 — how does curl google.com even work inside a container? Private IPs aren't routable on the internet. Google can't send a reply back to 172.17.0.3.

Let's trace what actually happens when you run something like:

# inside a container
curl https://google.com

Step 1 — DNS

The container resolves google.com using Docker's embedded DNS resolver (127.0.0.11), which forwards to your host's DNS and returns Google's real IP.

Step 2 — Packet leaves the container

The container sends a packet:

• Source IP: 172.17.0.3 (the container)

• Destination IP: 142.250.x.x (Google)

This travels through the veth pair → hits docker0.

Step 3 — Linux kernel routing

The host kernel looks at its routing table:

ip route
# default via 192.168.1.1 dev eth0    → internet goes here
# 172.17.0.0/24 dev docker0           → containers live here

Google's IP isn't in the container subnet, so the kernel forwards it out through eth0.

Step 4 — SNAT / Masquerade

Here's the key part. Before the packet leaves your machine, Linux rewrites the source IP. It replaces 172.17.0.3 with your machine's actual IP (192.168.1.x).

This is called SNAT (Source NAT) or Masquerade. Docker sets this up automatically using iptables:

sudo iptables -t nat -L POSTROUTING -n
# MASQUERADE all -- 172.17.0.0/24 !172.17.0.0/24

So the packet that hits Google's servers has your real machine IP as the source. Google replies to your machine. Then Linux uses conntrack (connection tracking) to remember which container made the request, and forwards the reply back to 172.17.0.3.

Container sends:          After Masquerade:        Google sees:
SRC: 172.17.0.3    →      SRC: 192.168.1.10   →   your machine's IP
DST: 142.250.x.x          DST: 142.250.x.x

The container gets its response and has no idea any of this happened. It's completely transparent.

This is the same reason your home router works — your router does the same NAT trick so multiple devices can share one public IP.

The Full Picture

Your Machine
┌───────────────────────────────────────────────────────┐
│                                                       │
│  Container (172.17.0.3)                               │
│    └── veth ──► docker0 (172.17.0.1)                  │
│                    └── iptables (MASQUERADE/SNAT)     │
│                           └── eth0 ──► Router ──► Internet
│                                                       │
│  Host MySQL listening on 0.0.0.0:3306                 │
│    └── reachable from container at 172.17.0.1:3306    │
│                                                       │
└───────────────────────────────────────────────────────┘

Quick Reference

What I Took Away From This

Before this I thought Docker networking was just magic. Now I understand there's actual Linux networking underneath — bridges, routing, NAT, connection tracking. Docker just sets it all up for you automatically.

The concepts here — veth pairs, bridge networking, SNAT — are also the foundation of how Kubernetes networking works. So if you're planning to get into K8s eventually, understanding this stuff first really helps.

If you're just getting started with Docker, try this exercise yourself. Deliberately break things, read the error messages, and trace what's actually happening. You learn way more than just following a tutorial.

If anything here was confusing or wrong, drop a comment — I'm still learning this stuff too.