MySQL in Docker, with the socket shared so host apps think it's local

This setup came out of a PHP app's web installer telling me No such file or directory when I pointed it at the database. We'd moved MySQL into a container because upgrades and rollbacks are much easier than with the distro package, but the app itself ran on the host under nginx and PHP-FPM. Apps like that usually expect MySQL on the local Unix socket at /var/run/mysqld/mysqld.sock, the same as a native install. So this is how we do it now, with TCP on loopback only and the socket shared to the host.

You'll need Docker Engine with the Compose plugin, and root or sudo. Make sure no MySQL or MariaDB server package is installed on the host, because it will fight over port 3306 and /run/mysqld. Client packages are fine.

Project directory and root password

mkdir -p /opt/mysql/data
cd /opt/mysql

Put the root password in /opt/mysql/.env and lock it down:

MYSQL_ROOT_PASSWORD=change-me-to-a-long-random-string

chmod 600 /opt/mysql/.env

A socket directory that survives reboots

/var/run is a symlink to /run, which is a tmpfs, so anything you create there is gone after a reboot. A tmpfiles.d entry recreates it at boot with the right owner, before Docker starts the container. Without it, Docker creates the missing bind-mount source itself as a root-owned directory, and depending on the image and timing, mysqld may not be able to create its socket there. I'd rather not leave that to luck.

First check the UID of the mysql user inside the image:

docker run --rm mysql:8.4 id mysql

In the official image that's UID and GID 999. Create /etc/tmpfiles.d/mysqld-docker.conf:

d /run/mysqld 0755 999 999 -

The 0755 matters. The socket file itself is world-writable, but the host user (www-data, for example) has to be able to enter the directory, or the app gets "Permission denied" on the socket. Apply it now without rebooting:

systemd-tmpfiles --create /etc/tmpfiles.d/mysqld-docker.conf
ls -ld /run/mysqld

The compose file

/opt/mysql/compose.yaml:

services:
  mysql:
    image: mysql:8.4
    container_name: mysql
    restart: unless-stopped
    env_file: .env
    ports:
      - "127.0.0.1:3306:3306"
    volumes:
      - ./data:/var/lib/mysql
      - /var/run/mysqld:/var/run/mysqld

127.0.0.1:3306:3306 publishes the port on loopback only. Leave the IP prefix off and Docker publishes on all interfaces, and Docker's own firewall rules are applied ahead of most host firewall setups, so a ufw "deny 3306" won't save you.

Bind-mounting /var/run/mysqld puts the container's socket directory on the host. When mysqld creates mysqld.sock inside the container, it shows up on the host at the same path.

Start it and check the socket

docker compose up -d
docker compose logs -f mysql      # wait for "ready for connections", then Ctrl+C
ls -l /var/run/mysqld/

You should see mysqld.sock. Confirm the server agrees on the path:

docker exec -it mysql mysql -uroot -p -e "SHOW VARIABLES LIKE 'socket';"

If your image version reports the socket somewhere else, change the bind mount to match that directory, or set the socket path explicitly in a config file mounted into /etc/mysql/conf.d/.

The app's database and user

docker exec -it mysql mysql -uroot -p

CREATE DATABASE appdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'appuser'@'localhost' IDENTIFIED BY 'another-long-random-string';
GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'localhost';

apt install -y default-mysql-client
mysql -u appuser -p appdb -e "SELECT CURRENT_USER(), @@hostname;"
mysql -h 127.0.0.1 -u root -p -e "SELECT 1;"
ss -ltnp | grep 3306