Blog
SavedSearch
Visit Hostlelo

WordPress on Docker Compose With MariaDB LTS, Step by Step

The official WordPress Docker example still uses MySQL 8.0. Build a compose.yaml with MariaDB LTS, a healthcheck, secrets, named volumes and HTTPS instead.

The short answer

The compose example on the official WordPress Docker image page pairs WordPress with mysql:8.0, which endoflife.date lists as past extended support since 30 April 2026. A safer local stack uses a MariaDB LTS image such as mariadb:11.8, passes database passwords through Compose secrets and the images' _FILE variables, waits for the database with healthcheck.sh and depends_on condition service_healthy, and puts a reverse proxy such as Caddy in front, which sets X-Forwarded-Proto so the WordPress image treats requests as HTTPS.

Reading options

On this page

You can run WordPress on Docker Compose with a supported database in one small file. Swap the database image in the usual example for a MariaDB LTS tag such as mariadb:11.8, keep the passwords in Compose secrets instead of plain environment variables, add a healthcheck so WordPress waits for the database, and put a reverse proxy in front for HTTPS.

Here is the catch that started this post. The compose example on the official WordPress image page still pairs the site with mysql:8.0, and endoflife.date lists MySQL 8.0 as past both premier support (ended 30 April 2025) and extended support (ended 30 April 2026). Copy that file today and your brand new stack starts life on a database that no longer gets fixes.

By the end you will have a compose.yaml with WordPress, MariaDB LTS, a healthcheck, file-based secrets, named volumes and Caddy in front for HTTPS, running on your own machine.

What this stack actually is

Docker Compose is a tool that reads one YAML file and starts several containers that talk to each other. A container is a packaged program with everything it needs to run, isolated from the rest of your computer.

Think of it like a small office building. Compose is the building manager, each container is a room, the named volumes are the filing cabinets that stay when a tenant moves out, and the reverse proxy is the front desk that checks visitors in and sends them to the right room.

Our building has three rooms. The db service runs MariaDB, wordpress runs WordPress with Apache and PHP, and caddy is the reverse proxy. A reverse proxy is a server that takes requests from the browser and passes them to another server behind it. Caddy handles HTTPS at the front and talks plain HTTP to WordPress on the private Docker network.

Why this matters: WordPress itself now asks for a modern database. At the time of writing (21 November 2026), the WordPress requirements page recommends MariaDB 10.11 or greater, or MySQL 8.4 or greater, plus PHP 8.3 or greater and HTTPS support. MySQL 8.0 does not meet that recommendation.

Heads up: treat this setup as a lab, a staging copy or a playground for an experienced owner. It is not a hardened production platform. Production needs backups, monitoring, updates and a real certificate on a real domain, and those are jobs on their own.

Before you start

Check these before you type anything:

  • Docker Engine with the Compose plugin, or Docker Desktop. Install it from Docker's own page at https://docs.docker.com/engine/install/ and follow the steps for your platform. Docker Desktop covers Windows and macOS.
  • A terminal where docker compose version prints a version number.
  • Free ports 80 and 443 on your machine, because Caddy will listen on them.
  • About 30 minutes, plus time to pull the images.
  • openssl for generating passwords. Most Linux and macOS systems have it already.
  • Risk level: low on a fresh test machine. If you already run other containers, read each command before you run it, because one of the cleanup commands below deletes volumes.

Quick tip: if you plan to copy a live site into this stack later, take a full backup of that site first and keep it outside the project folder. Nothing in this guide touches a live server, and it should stay that way until you have tested.

Build the stack step by step

Step 1: Create the project folder

This creates a folder for the project with subfolders for secrets and the Caddy config, then moves into it.

mkdir -p ~/wp-stack/secrets ~/wp-stack/conf
cd ~/wp-stack

You should now be inside ~/wp-stack with two empty folders, secrets and conf.

Step 2: Create the password files

Compose secrets read their value from a file on your machine and mount it inside the container at /run/secrets/<secret_name>. Docker's Compose documentation warns that injecting passwords as environment variables risks unintentional information exposure, because environment variables are often available to all processes and access is hard to track. A file is easier to keep private.

This generates two random passwords and writes each one to a file without a trailing newline.

printf '%s' "$(openssl rand -base64 32)" > secrets/db_password.txt
printf '%s' "$(openssl rand -base64 32)" > secrets/db_root_password.txt

This restricts the folder itself to your own user.

chmod 700 secrets

One thing to confirm later: the secret is your file mounted into the container, so the user that runs WordPress inside the container must be able to read it. The check in the "How to check it worked" section tests exactly that, so do not skip it. If it fails, adjust the file permissions until it passes.

Heads up: add secrets/ to your .gitignore before you ever run git add. A password file in a public repository is the same as no password.

Step 3: Write the compose.yaml file

This is the whole stack. Create a file called compose.yaml in ~/wp-stack with this content.

services:
  db:
    image: mariadb:11.8
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD_FILE: /run/secrets/db_password
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
    secrets:
      - db_password
      - db_root_password
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3

  wordpress:
    image: wordpress:7.1.5-php8.3-apache
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password
      WORDPRESS_DB_NAME: wordpress
    secrets:
      - db_password
    volumes:
      - wp_data:/var/www/html

  caddy:
    image: caddy:2.11
    restart: unless-stopped
    depends_on:
      - wordpress
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf:/etc/caddy
      - caddy_data:/data
      - caddy_config:/config

secrets:
  db_password:
    file: ./secrets/db_password.txt
  db_root_password:
    file: ./secrets/db_root_password.txt

volumes:
  db_data:
  wp_data:
  caddy_data:
  caddy_config:

The mariadb:11.8 tag is a long-term support line. MariaDB's own maintenance table lists community support for 11.8 until 4 June 2028. At the time of writing, the lts tag on the MariaDB image points at 12.3.3 and latest points at 13.0.2, which is not an LTS release. I picked a fixed version line on purpose, so a routine pull never moves you to a new major release by surprise.

The MARIADB_DATABASE line matters more than it looks. The WordPress image page says WORDPRESS_DB_NAME must already exist on the database server, and the WordPress container will not create it for you. MariaDB creates that database and the wordpress user on its first start, so the two halves meet in the middle.

The _FILE suffix is the secret trick. Both official images let you add _FILE to their variables so the value is read from a file instead. The WordPress image reads WORDPRESS_DB_PASSWORD_FILE and MariaDB reads MARIADB_PASSWORD_FILE, and both point at the same mounted secret, so the two sides always agree on the password.

The healthcheck uses healthcheck.sh, a script that ships inside the official MariaDB image. The --connect test checks that a client can reach the server over TCP, and --innodb_initialized passes only once InnoDB, the storage engine WordPress tables use, has finished starting, including any crash recovery. The image has no default healthcheck, so without this block Docker has no idea when the database is ready.

The condition: service_healthy line is what uses that healthcheck. Docker's startup order page explains that plain depends_on only waits until a container is running, not until it is ready. With service_healthy, WordPress starts only after MariaDB reports healthy.

The named volumes db_data, wp_data and the two Caddy volumes are the filing cabinets. Compose creates them on the first up and reuses them afterwards, so your database, uploads and certificates survive a container rebuild. The Caddy image docs say /data holds certificates and private keys and must not be treated as a cache.

Notice that WordPress has no ports section. Only Caddy is reachable from your browser. WordPress sits on the private network that Compose creates for the project.

Step 4: Write the Caddyfile

Caddy reads its configuration from /etc/caddy/Caddyfile inside the container. The image docs recommend mounting the folder rather than the single file, which is why ./conf is mounted.

This creates conf/Caddyfile with a single site that sends every request for localhost to the WordPress container on port 80.

cat > conf/Caddyfile <<'EOF'
localhost {
	reverse_proxy wordpress:80
}
EOF

For localhost, Caddy signs its own certificate from a local certificate authority it creates for itself. On a real server with a public domain name you would put that domain here instead, and Caddy's automatic HTTPS would handle a public certificate, subject to the prerequisites in its documentation. One of them is a data directory that is writeable and persistent, which the caddy_data volume gives you.

Step 5: Validate the file before starting

This checks the Compose file for mistakes without starting anything. The --quiet flag only validates and prints nothing when the file is fine.

docker compose config --quiet

No output means the YAML parsed. An error here usually points at a line number with bad indentation.

Step 6: Start the stack

This pulls the images and starts all three services in the background. The --wait flag makes the command wait until services are running or healthy.

docker compose up --wait

The first run takes a minute or two while images download and MariaDB initialises an empty data directory. When the prompt returns, the stack is up.

Step 7: Finish the WordPress install

Open https://localhost in your browser. You will most likely see a certificate warning first, and that is expected here (see Troubleshooting for why). Accept it for this local test only, and you should land on the WordPress language and install screen.

Fill in the site title and an admin user with a strong password. Because you reached the installer over HTTPS, WordPress saves https://localhost as the site address.

How HTTPS works behind the proxy

This is the part people skip, and then wonder why the admin screen loops forever.

The browser talks HTTPS to Caddy. Caddy talks plain HTTP to WordPress. So from inside the WordPress container, every request looks like HTTP. If WordPress believes the site lives at an https:// address, it can keep redirecting to HTTPS, and each redirect lands right back in the same place.

The fix is a header called X-Forwarded-Proto. A proxy adds it to say which protocol the browser originally used. Caddy's reverse_proxy sets X-Forwarded-Proto by default, so there is nothing to add in the Caddyfile.

On the WordPress side, the official image already handles it. Its generated wp-config.php checks HTTP_X_FORWARDED_PROTO and treats the request as HTTPS when the header contains https. The image page notes this is added automatically when you configure the container through environment variables, as we did.

Heads up: if you swap Caddy for another proxy, that proxy must send X-Forwarded-Proto itself. If it does not, you will see the loop again. Only trust that header from your own proxy, never straight from the internet, because any client can send it.

If you later move this onto a public server and also want old HTTP links forced to HTTPS at the web server level, our guide to an HTTP to HTTPS redirect explains the redirect side.

Variants worth knowing

Using MySQL 8.4 instead of MariaDB

The WordPress requirements accept MySQL 8.4 or greater. At the time of writing, the official MySQL image offers 8.4.13, 8.4 and 8 tags, while its lts tag points at the 9.7 line. endoflife.date lists MySQL 8.4 premier support until 30 April 2029.

To switch, change the image to mysql:8.4 and rename the variables to MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD_FILE and MYSQL_ROOT_PASSWORD_FILE. The MySQL image supports _FILE on all of them, and its root password is mandatory.

Heads up: healthcheck.sh is MariaDB's script and is not part of the MySQL image. You will need a different healthcheck test, so check the MySQL image documentation before you rely on service_healthy with MySQL.

Upgrading a stack that already runs MySQL 8.0

Never swap the image tag on a volume that already holds MySQL 8.0 data. That is a database migration, and it needs an export, a fresh empty volume, an import and a test.

Here is a made-up example: Priya copied the official example a year ago for a client's staging site. She is about to change mysql:8.0 to mariadb:11.8 and run up on the same volume. That is the moment to stop. The safer path is to export the database, bring up the new stack on new volumes, import, and check the site before deleting anything old.

How to check it worked

Run these checks in order. Each one has a clear expected result.

This lists the containers for the project with their status.

docker compose ps

You should see db, wordpress and caddy all running, with the database showing a healthy state.

This runs the same healthcheck by hand and prints the exit code.

docker compose exec db healthcheck.sh --connect --innodb_initialized; echo "exit code: $?"

You want exit code: 0. Anything else means MariaDB is not ready.

This confirms that MariaDB created the wordpress database. It asks for the root password, which you can read from secrets/db_root_password.txt.

docker compose exec db mariadb -u root -p -e "SHOW DATABASES;"

The list should include wordpress.

This confirms the WordPress process can read its password file, by reading it as the www-data user, the account the WordPress files in this image are assigned to.

docker compose exec -u www-data wordpress cat /run/secrets/db_password

You should see the password string. A "Permission denied" message means the web server user cannot read the secret file, so check the file permissions on your machine.

This requests the site over HTTPS and shows only the response headers. The -k flag skips certificate verification, which is fine for this local test.

curl -kI https://localhost/

You should get a 200 response once WordPress is installed. Before the install, a redirect to the installer is normal.

Finally, log in at https://localhost/wp-admin/ and open Settings > General. Both WordPress Address (URL) and Site Address (URL) should start with https://.

Troubleshooting

"Error establishing a database connection"

Symptom: WordPress shows this message instead of the installer.

Likely cause: WordPress cannot log in to MariaDB. Either the password files differ, WordPress cannot read its secret, or the user and database names do not match on both sides.

Fix: run the www-data read check above. Confirm WORDPRESS_DB_USER matches MARIADB_USER and WORDPRESS_DB_NAME matches MARIADB_DATABASE. Then check the database logs with docker compose logs db.

You changed a password file and nothing changed

Symptom: you regenerated db_password.txt, restarted, and now WordPress cannot connect at all.

Likely cause: the MariaDB image applies MARIADB_USER, MARIADB_PASSWORD and friends only when it starts with an empty data directory. Once db_data holds a database, those variables have no effect, so the old password is still the real one.

Fix: on a throwaway test stack, remove everything including volumes and start again. This command stops the stack and deletes the named volumes, which wipes the database and uploads, so only run it when you have nothing to keep.

docker compose down -v

On a stack you care about, change the password inside MariaDB with SQL first, then update the file to match.

WordPress container keeps waiting or restarting

Symptom: docker compose up --wait hangs or fails, and wordpress never starts.

Likely cause: the database never became healthy, so the service_healthy condition is never met. Common reasons are a missing root password secret or a typo in a _FILE path.

Fix: follow the database log to see the real error.

docker compose logs -f db

The MariaDB image needs one of its root password options, such as MARIADB_ROOT_PASSWORD_FILE here. Press Ctrl+C to stop following the log.

Port 80 or 443 is already in use

Symptom: Caddy fails to start with an error about the port being already allocated or in use.

Likely cause: another web server, another container or a desktop app already listens on that port.

Fix: find and stop the other service, then run docker compose up --wait again. On a test laptop, freeing the port is simpler than remapping it.

Browser warns that the certificate is not trusted

Symptom: a full-page warning when you open https://localhost.

Likely cause: Caddy signed the certificate with its own local authority, and that root lives inside the container. Caddy's docs say installing the root into your trust store automatically is not guaranteed, especially in containers.

Fix: for a quick local test, accept the warning or use curl -k. If you want a clean padlock locally, add Caddy's root certificate from the caddy_data volume to your system trust store yourself, as Caddy's documentation describes.

Redirect loop on wp-admin

Symptom: the browser says the page redirected too many times.

Likely cause: the proxy in front is not sending X-Forwarded-Proto, or you added a second proxy or CDN in front of Caddy that terminates TLS differently.

Fix: with the Caddyfile above this should not happen. If you replaced Caddy, make the new proxy set X-Forwarded-Proto to https. If something sits in front of Caddy, read Caddy's notes on trusted_proxies so it accepts forwarded headers only from that hop.

Pro tips before you go further

Pin exact tags once you are happy. wordpress:7.1.5-php8.3-apache and mariadb:11.8 were current at the time of writing, but both images change often. Pin, test an upgrade on a copy, then move the pin.

Keep the volumes safe. db_data and wp_data hold the whole site. A backup that only covers the compose.yaml file backs up nothing that matters.

Use the stack to rehearse risky work. It is a good place to practise moving WP-Cron to a real cron job, or to verify WordPress files with WP-CLI checksums before you try either on a live site.

If this staging copy will become the live site on a new server, lower your DNS TTL before a move a day or two ahead, so the switch spreads quickly.

When to ask for help: if the site handles payments, personal data or real traffic, bring in a developer or your host for the production design.

The one message worth forwarding

If a colleague or freelancer set up your Docker WordPress stack from the official example, this is the message to send them:

"Hi, quick check on our WordPress Docker stack. The official compose example uses mysql:8.0, and endoflife.date lists MySQL 8.0 extended support as ended on 30 April 2026. WordPress now recommends MariaDB 10.11 or newer, or MySQL 8.4 or newer. Can you tell me which database image and tag we run, whether the database passwords are in Compose secrets or plain environment variables, and whether we have a tested database export before any change? If we are on 8.0, could we plan a migration on a staging copy first?"

The short version: the copied example works, but it starts you on a database that has run out of support, so fix the image, the secrets and the startup order before you build anything on top of it.

Reader questions

Can I still use the mysql:8.0 image from the official WordPress example?

It will run, but endoflife.date lists MySQL 8.0 premier support as ended on 30 April 2025 and extended support as ended on 30 April 2026. WordPress recommends MariaDB 10.11 or newer, or MySQL 8.4 or newer, so pick one of those for a new stack.

Should I use the mariadb:lts tag or a version number?

Use a version line such as mariadb:11.8 or an exact tag. The lts tag moves to each new long-term release, which at the time of writing is 12.3, so a routine pull could change your major version without warning.

Does the WordPress container create the database for me?

No. The WordPress image page says the database named in WORDPRESS_DB_NAME must already exist. Setting MARIADB_DATABASE on the MariaDB container creates it on the first start with an empty data directory.

Why use Compose secrets instead of environment variables for passwords?

Docker's Compose documentation advises against passing sensitive values such as passwords through environment variables, because they are often available to all processes. Secrets are mounted as files under /run/secrets, and both images read them through their _FILE variables.

Do I need to edit wp-config.php for HTTPS behind a reverse proxy?

Not with the official image configured through environment variables. Its generated wp-config.php sets HTTPS on when the X-Forwarded-Proto header contains https, and Caddy's reverse_proxy sets that header by default.

Is this Docker Compose stack ready for production?

Treat it as a local, testing or staging setup. Production also needs tested backups of the volumes, monitoring, a plan for image updates and a real domain with a trusted certificate.

Does docker compose down delete my WordPress data?

Plain docker compose down keeps named volumes. Adding -v removes the named volumes declared in the file, which deletes the database and uploads, so use it only on a throwaway stack.

Sources & further reading

  1. WordPress Docker Official Image
  2. MariaDB Docker Official Image
  3. MariaDB: Using healthcheck.sh
  4. Docker Docs: Control startup order in Compose
  5. Docker Docs: Manage secrets in Docker Compose
  6. WordPress Requirements
  7. MariaDB Foundation: About and maintenance policy
  8. endoflife.date: MySQL
  9. Docker Docs: Install Docker Engine
  10. Caddy Docs: reverse_proxy directive

Originally published . About our editorial updates.

Your next project deserves a better foundation.

Explore hosting built for your next chapter.

Explore hosting

Find your next answer.

Search published guides and articles.

Ctrl / ⌘ K to open · Esc to close