> ## Documentation Index
> Fetch the complete documentation index at: https://help.freakhosting.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Run WordPress with Docker Compose

> Run WordPress with Docker Compose: a compose.yaml with the official wordpress and mysql:8.0 images, Nginx and HTTPS in front, plus backup and update steps.

To run WordPress with Docker Compose, create a `compose.yaml` with two services: the official `wordpress` image and a `mysql:8.0` database, each with its own volume. Start it with `sudo docker compose up -d`, put Nginx in front with a free Let's Encrypt certificate, then open `https://blog.example.com` to run the WordPress installer.

| Difficulty | Time | Works on | Needs |
| - | - | - | - |
| Beginner | 20 minutes | Ubuntu 22.04 / 24.04, Debian 12 / 13, AlmaLinux / Rocky 9 / 10 | [Docker](https://help.freakhosting.com/portals/other/how-to-install-docker.md), a domain, ports 80 and 443 open |

## Before you start

* [Install Docker](https://help.freakhosting.com/portals/other/how-to-install-docker.md) from Docker's official repository. The commands use `sudo`; if you are logged in as `root`, leave it out.
* Point a domain or subdomain, for example `blog.example.com`, at your server with an `A` record. See [point a domain to your server](https://help.freakhosting.com/portals/other/how-to-point-a-domain-to-your-server.md).
* [Install Nginx](https://help.freakhosting.com/portals/other/how-to-install-nginx.md) on the server to handle HTTPS. If you prefer containers for this too, use [Nginx Proxy Manager](https://help.freakhosting.com/portals/other/how-to-set-up-nginx-proxy-manager.md) or [Traefik](https://help.freakhosting.com/portals/other/how-to-set-up-traefik-with-docker.md) instead.

Docker Compose runs several containers from one file. Here, one container runs WordPress with Apache and PHP, the other runs MySQL. If you would rather install WordPress directly on the server, see [install WordPress on a VPS](https://help.freakhosting.com/portals/other/how-to-install-wordpress-on-a-vps.md).

## How to set up WordPress with Docker Compose

**1. Create a project folder**

```bash theme={null}
mkdir -p ~/wordpress && cd ~/wordpress
```

**2. Create a .env file with the database password**

```bash theme={null}
echo "DB_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env
```

Docker Compose reads `.env` automatically and fills in `${DB_PASSWORD}` below.

**3. Create compose.yaml**

This follows the example in the [official WordPress image documentation](https://hub.docker.com/_/wordpress), with the password moved to `.env` and the web port bound to `127.0.0.1`:

```yaml theme={null}
services:
  wordpress:
    image: wordpress
    restart: always
    ports:
      - "127.0.0.1:8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wpuser
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wordpress:/var/www/html
    depends_on:
      - db

  db:
    image: mysql:8.0
    restart: always
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wpuser
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_RANDOM_ROOT_PASSWORD: "1"
    volumes:
      - db:/var/lib/mysql

volumes:
  wordpress:
  db:
```

`127.0.0.1:8080` keeps WordPress off the public internet until Nginx serves it with HTTPS. Ports published by Docker bypass `ufw`, so this binding matters. The database has no published port at all; WordPress reaches it on the internal network as `db`.

**4. Start the containers**

```bash theme={null}
sudo docker compose up -d
```

The first start downloads both images and initialises the database, which takes a minute or two.

## How to put WordPress behind Nginx with HTTPS

**1. Create the Nginx site**

Create `/etc/nginx/sites-available/blog.example.com` (Ubuntu / Debian) or `/etc/nginx/conf.d/blog.example.com.conf` (AlmaLinux / Rocky):

```nginx theme={null}
server {
    listen 80;
    listen [::]:80;
    server_name blog.example.com;

    client_max_body_size 64M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

`client_max_body_size` lets you upload media larger than Nginx's 1 MB default. PHP has its own upload limit inside the container.

**2. Enable it and reload Nginx**

On Ubuntu / Debian, link the site first:

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/blog.example.com /etc/nginx/sites-enabled/
```

On AlmaLinux / Rocky, allow Nginx to connect to local ports with `sudo setsebool -P httpd_can_network_connect 1`. Then on any distribution:

```bash theme={null}
sudo nginx -t
sudo systemctl reload nginx
```

**3. Add a free certificate**

```bash theme={null}
sudo certbot --nginx -d blog.example.com
```

See [get a free SSL certificate with Certbot](https://help.freakhosting.com/portals/other/how-to-get-a-free-ssl-certificate-with-certbot.md).

The official image adds the `X-Forwarded-Proto` handling to `wp-config.php` for you, so WordPress knows visitors use HTTPS. No extra setting is needed.

## How to finish the WordPress install

Open `https://blog.example.com` (with `https`, so WordPress saves the HTTPS address). Choose a language, then enter the site title, an admin username (not `admin`), a strong password and your email, and click **Install WordPress**. Log in at `https://blog.example.com/wp-admin`.

> [!WARNING]
>
> Finish the installer straight away. Until you do, anyone who opens the site first can complete it and create the admin account.

## How to check it worked

```bash theme={null}
sudo docker compose ps
curl -I http://127.0.0.1:8080
```

Both services show `Up` (or `running`), and `curl` returns an HTTP response from Apache.

## How to back up WordPress in Docker

Your site lives in two volumes: `wordpress` (core files, themes, plugins and uploads) and `db` (the database). Back up both.

```bash theme={null}
cd ~/wordpress
sudo docker compose exec -T db sh -c 'mysqldump -u wpuser -p"$MYSQL_PASSWORD" wordpress' > wordpress-db.sql
sudo docker compose cp wordpress:/var/www/html ./html-backup
```

Copy both to another server or storage. See [back up Docker volumes](https://help.freakhosting.com/portals/other/how-to-back-up-docker-volumes.md) and [back up and restore MySQL databases](https://help.freakhosting.com/portals/other/how-to-back-up-and-restore-mysql-databases.md).

## How to update WordPress in Docker

There are two parts to update:

* **WordPress core, themes and plugins** update from **Dashboard > Updates** in `wp-admin`, as on any WordPress site. The image copies WordPress into the volume only on first start; after that, WordPress manages its own files.
* **PHP, Apache and MySQL** update when you pull new images:

```bash theme={null}
cd ~/wordpress
sudo docker compose pull
sudo docker compose up -d
```

Back up first. See [update Docker containers](https://help.freakhosting.com/portals/other/how-to-update-docker-containers.md).

## Frequently asked questions

### Why does WordPress show "Error establishing a database connection"?

The database is still starting or the passwords don't match. Wait a minute and reload. If it continues, check that `.env` exists and run `sudo docker compose logs db`. Changing `DB_PASSWORD` after the first start does not change the existing MySQL user's password.

### How do I increase the PHP upload limit?

Add a file such as `uploads.ini` with `upload_max_filesize = 64M` and `post_max_size = 64M`, and mount it into the container at `/usr/local/etc/php/conf.d/uploads.ini`. Keep `client_max_body_size` in Nginx at least as large.

### Why can't WordPress send emails?

The official image includes no mail server. Use an SMTP plugin with your email provider's SMTP details.

### Can I run several WordPress sites on one server?

Yes. Give each site its own project folder, a different local port (for example `127.0.0.1:8081:80`) and its own Nginx server block.

## Related guides

> [card] [VPS and dedicated server guides](https://help.freakhosting.com/portals/other/vps-and-dedicated-server-guides.md)
>
> Every guide in this section.

> [card] [Docker Compose tutorial](https://help.freakhosting.com/portals/other/how-to-use-docker-compose.md)
>
> How compose.yaml works.

> [card] [Install WordPress on a VPS](https://help.freakhosting.com/portals/other/how-to-install-wordpress-on-a-vps.md)
>
> The same site without Docker.

> [card] [Nginx reverse proxy](https://help.freakhosting.com/portals/other/how-to-set-up-nginx-as-a-reverse-proxy.md)
>
> Serve containers on your domain.

> [card] [Secure Docker on a VPS](https://help.freakhosting.com/portals/other/how-to-secure-docker-on-a-vps.md)
>
> Keep container ports private.

***

> [!NOTE]
>
> **Checked against the official [WordPress Docker image documentation](https://hub.docker.com/_/wordpress)** on 4 November 2026 (images `wordpress` and `mysql:8.0`); `compose.yaml` validated with `docker compose config` and the Nginx configuration syntax-tested on Ubuntu 24.04 LTS. Image defaults can change between releases.

> [!NOTE]
>
> ### Need Extra Help?
>
> If you encounter any issues, our support team is ready to assist:
>
> * **Live Chat:** Quick assistance via our website.
> * **Support Ticket:** [Open a Ticket](https://freakhosting.com/clientarea/submitticket.php)
> * **Discord:** [Join our Community](https://discord.gg/freakhosting)
> * **Email:** [support@freakhosting.com](mailto:support@freakhosting.com)

> [!TIP]
>
> ### Save on Your Hosting
>
> Ready to upgrade your hosting? Use code **KB20** at checkout for **20% off** your first order!

***

**Last Updated:** November 2026


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.