---
title: "Self-host WordPress"
description: "Run WordPress on a VM of its own: official Docker images and MariaDB, wp-admin behind exe.dev login, email that works, nightly backups, and your own domain."
url: https://exe-staging.dev/deploy/wordpress
category: "Web apps"
updated: 2026-11-16
---

# Self-host WordPress

Your WordPress on a computer of its own, with wp-admin only you can reach.

- **Software:** WordPress (https://wordpress.org)
- **Source:** https://github.com/WordPress/wordpress-develop
- **License:** GPL-2.0-or-later
- **Time:** 10 minutes
- **Example VM name:** `my-wordpress` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe-staging.dev/deploy/wordpress/manifest.json
- **File:** https://exe-staging.dev/deploy/wordpress/backup.sh
- **File:** https://exe-staging.dev/deploy/wordpress/exe-dev-integrations.php
- **File:** https://exe-staging.dev/deploy/wordpress/exe-dev-login-gate.php
- **File:** https://exe-staging.dev/deploy/wordpress/exe-dev-loopback.php
- **File:** https://exe-staging.dev/deploy/wordpress/exe-dev-mail.php

## What you get

- WordPress 7.1 on PHP 8.4 with MariaDB 12.3, under Docker Compose, restarting after a reboot.
- The WordPress installer waiting at your private URL, for you to pick the site title and your login.
- wp-login.php and wp-admin open only to exe.dev accounts you list, whether or not the site is public.
- Password resets and notices emailed through exe.dev, and WordPress's own background jobs working on a private site.
- The `wp` command (WP-CLI) on the VM, and nightly backups of the database and wp-content.

Running on the VM:

- **WordPress 7.1**: the official wordpress image, PHP 8.4 and Apache, under Docker Compose, port 8000, data in `~/wordpress/html`
- **MariaDB 12.3 LTS**: the official mariadb image, reachable only from WordPress, data in `~/wordpress/db`
- **exe.dev plugins**: four must-use plugins for login, email, loopback requests, and the LLM gateway, data in `~/wordpress/html/wp-content/mu-plugins`
- **WP-CLI**: the `wp` command, run in its own container
- **Nightly backups**: database, wp-content, and settings; keeps a week, data in `~/wordpress/backups`

How it is reached:

- https://my-wordpress.exe.xyz/ (private): your site, until you make it public
- https://my-wordpress.exe.xyz/wp-admin/ (private): the WordPress dashboard, for exe.dev accounts you list, even when the site is public

## Deploy with Shelley

Open https://exe-staging.dev/new?prompt=Set%20up%20WordPress%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fwordpress.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-wordpress.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-wordpress.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20WordPress%207.1%20on%20PHP%208.4%20with%20MariaDB%2012.3%2C%20under%20Docker%20Compose%2C%20restarting%20after%20a%20reboot.%0A-%20The%20WordPress%20installer%20waiting%20at%20your%20private%20URL%2C%20for%20you%20to%20pick%20the%20site%20title%20and%20your%20login.%0A-%20wp-login.php%20and%20wp-admin%20open%20only%20to%20exe.dev%20accounts%20you%20list%2C%20whether%20or%20not%20the%20site%20is%20public.%0A-%20Password%20resets%20and%20notices%20emailed%20through%20exe.dev%2C%20and%20WordPress%27s%20own%20background%20jobs%20working%20on%20a%20private%20site.%0A-%20The%20%60wp%60%20command%20%28WP-CLI%29%20on%20the%20VM%2C%20and%20nightly%20backups%20of%20the%20database%20and%20wp-content.%0A%0ARead%20the%20whole%20recipe%2C%20including%20the%20closed%20details.%20For%20initial%20setup%2C%0Afollow%20%22Install%20by%20hand%22%20from%20top%20to%20bottom%3A%20Docker%2C%20~%2Fwordpress%20with%0A.env%2C%20compose.yaml%20and%20php.ini%2C%20the%20owner%27s%20email%20in%0A~%2Fwordpress%2Fexe-dev%2Fadmin-emails%20%28from%20the%20reflection%20integration%3B%20if%0Athat%20fails%2C%20ask%20the%20owner%29%2C%20the%20four%20exe.dev%20plugins%2C%20the%20wp%20command%2C%0Aand%20the%20backup%20timer.%20Never%20overwrite%20an%20existing%20~%2Fwordpress%2F.env.%0ADon%27t%20run%20the%20WordPress%20installer%20yourself%2C%20and%20don%27t%20make%20the%20site%0Apublic%2C%20add%20a%20domain%2C%20install%20plugins%2C%20migrate%20a%20site%2C%20or%20run%20the%0ARestore%20or%20Update%20instructions%20during%20initial%20setup%3B%20the%20walkthrough%0Asections%20are%20for%20the%20owner%20afterwards.%20Check%20the%20login%20gate%20on%20localhost%0Awith%20no%20email%2C%20a%20wrong%20email%2C%20and%20the%20owner%27s%20email.%20Do%20not%20reboot.%0AUntil%20the%20owner%20runs%20the%20installer%2C%20wp%20commands%20that%20need%20the%20site%20%28wp%0Aoption%2C%20wp%20eval%29%20fail%3B%20that%27s%20expected%2C%20and%20the%20mail%20and%20loopback%0Aplugins%20can%20only%20be%20tried%20after%20it.%20Finish%20with%20the%20private%20URL%0Ahttps%3A%2F%2F%3Cvm%3E.exe.xyz%2F%20and%20ask%20the%20owner%20to%20open%20it%2C%20choose%20a%20site%20title%2C%0Ausername%20and%20password%20in%20the%20WordPress%20installer%2C%20and%20log%20in.%20Don%27t%0Apaste%20the%20database%20passwords%20into%20the%20chat%3B%20say%20they%20are%20in%0A~%2Fwordpress%2F.env.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe-staging.dev/deploy/wordpress/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Or follow the steps below by hand.

WordPress runs a large share of the web, and it's at its best on a
machine you control. Here it gets a VM of its own with a persistent disk:
the official Docker images for WordPress and MariaDB, the files in plain
directories you and Shelley can edit, and nightly backups. The site
stays private until you make it public, and even then `wp-admin` opens
only for the exe.dev accounts you list, so nobody can guess passwords at
your login page. WordPress's email goes out through exe.dev with no mail
provider, and the WordPress AI plugins can use exe.dev's LLM gateway with
no API key.

## Finish the install

Open **https://my-wordpress.exe.xyz/**. You'll sign in to exe.dev if you
haven't, then land on WordPress's installer: pick a language, a site
title, a username, a strong password, and your email. Nobody else can
reach the installer, because the VM is private. Then log in, and you're
on the dashboard.

Write your first post, upload a few pictures, and look at the site.
Uploads up to 128 MB work; [Something not
working?](#troubleshooting) shows how to raise that.

## Who can sign in

There are two locks on the dashboard. The first is exe.dev's: requests
for `wp-login.php`, `wp-admin`, and `xmlrpc.php` need an exe.dev sign-in
whose email is in `~/wordpress/exe-dev/admin-emails`, which starts with
yours. The second is WordPress's own login. exe.dev's proxy adds the
signed-in email to each request and removes any copy a visitor sends, so
the first lock can't be faked; it's
[exe-dev-login-gate.php](https://exe-staging.dev/deploy/wordpress/exe-dev-login-gate.php),
a must-use plugin of 40 lines.

To add a writer or an editor: add their email to
`~/wordpress/exe-dev/admin-emails` on the VM (one per line), and create
their WordPress user under **Users → Add New**. While the site is
private, also share it with them. On your computer:

```bash
ssh exe.dev share add my-wordpress editor@example.com
```

If your visitors log in to WordPress themselves (a shop, a membership
site, comments that need an account), the gate is in their way. Delete
`~/wordpress/html/wp-content/mu-plugins/exe-dev-login-gate.php`, install
[Two Factor](https://wordpress.org/plugins/two-factor/) from the WordPress
team, and turn it on for every account that can publish. exe.dev makes
one port public, and WordPress serves its site and its dashboard from
the same one, so without the gate `wp-login.php` faces the internet like
on any other host.

## Make it public

When the site is ready, on your computer:

```bash
ssh exe.dev share set-public my-wordpress
```

Now anyone can read https://my-wordpress.exe.xyz/, and `wp-admin` still
asks for your exe.dev sign-in first. Go to **Settings → Reading** and
clear **Discourage search engines** if you ticked it. To take the site
private again: `ssh exe.dev share set-private my-wordpress`.

Public means public: comments, contact forms, and whatever pages your
plugins add are open to everyone, as on any host. Install few plugins,
keep them updated, and turn on auto-updates for the ones you trust.

## Use your own domain

Point a CNAME at `my-wordpress.exe.xyz` (apex domains need an ALIAS or A
record) and tell exe.dev about it, as the [custom domain
guide](/docs/cnames) explains. On your computer:

```bash
ssh exe.dev domain add my-wordpress blog.example.com
```

Then tell WordPress its new address. On the VM:

```bash
cd ~/wordpress
old=$(grep ^WP_URL= .env | cut -d= -f2)
sed -i 's|^WP_URL=.*|WP_URL=https://blog.example.com|' .env
docker compose up -d --wait
wp search-replace "$old" https://blog.example.com --all-tables --skip-columns=guid
```

`WP_URL` sets WordPress's `WP_HOME` and `WP_SITEURL`, so the address
can't drift from the settings screen; `search-replace` fixes the links
already stored in posts. Open https://blog.example.com/wp-admin/ to
check the dashboard. exe.dev issues the TLS certificate itself. If your
DNS is at Cloudflare, turn its proxy (the orange cloud) off, as the
guide explains.

## Email

WordPress sends email for password resets, new comments, and update
notices. [exe-dev-mail.php](https://exe-staging.dev/deploy/wordpress/exe-dev-mail.php)
sends it through exe.dev's [email gateway](/docs/send-email): no mail
server, no provider, no password. The gateway is for you, not your
visitors: it delivers plain text to you, your exe.dev team, and people
you've shared the VM with, and it's rate-limited. Mail to anyone else
fails, and WordPress logs why (`docker compose logs wordpress`). To
test it, log out and use **Lost your password?**, or on the VM:

```bash
wp eval 'var_dump(wp_mail(get_option("admin_email"), "Test", "Hello from WordPress"));'
```

To email your readers or customers (newsletters, shop receipts,
contact-form copies), use a mail provider: install
[FluentSMTP](https://wordpress.org/plugins/fluent-smtp/) or [WP Mail
SMTP](https://wordpress.org/plugins/wp-mail-smtp/), enter the
provider's SMTP details, and delete `exe-dev-mail.php` so WordPress uses
the plugin. exe.dev VMs can connect out to SMTP servers on ports 465
and 587. The plugin keeps the provider's password in WordPress's database, where
your backups carry it. For a provider with an HTTP API, you can keep the
key off the VM entirely: add it as an [http-proxy
integration](/docs/integrations-http-proxy) and send the API's host to
it in `exe-dev-integrations.php`, the way that file sends AI calls to
the LLM gateway; ask Shelley to set it up and send a test email.

## Add AI to the editor

WordPress 7 has a built-in AI client that plugins share, and exe.dev's
[LLM gateway](/docs/integrations-llm) can answer it with no API key.
[exe-dev-integrations.php](https://exe-staging.dev/deploy/wordpress/exe-dev-integrations.php)
sends WordPress's calls to `api.anthropic.com` and `api.openai.com` to
the gateway instead, and they count against your exe.dev plan. Under
**Plugins → Add New**, install **AI** (by WordPress.org) and **AI Provider
for Anthropic**. Under **Settings → Connectors**, give Anthropic any
text as its key (say `exe-dev`); the gateway ignores it. Then choose
what to turn on under **Settings → AI**. To pay a provider directly
instead, enter a real key and delete `exe-dev-integrations.php`.

## Edit themes and plugins with Shelley

Shelley runs on the VM, next to WordPress's files, so it can write a
child theme, a block, or a small plugin and check it in the browser.
Open https://my-wordpress.exe.xyz/ in Shelley's browser and ask, for
example:

> Make a child theme of Twenty Twenty-Five with a narrower content column
> and our logo in the header, activate it, and show me the home page.

The files are in `~/wordpress/html/wp-content`, owned by your user, and
Shelley has the `wp` command for everything else: `wp plugin list`,
`wp theme activate`, `wp user create`, `wp search-replace`. Keep your
own themes and plugins in git: `git init` in their directory.

## Try changes on a copy

Before a big change (a new theme, a major update, a plugin you don't
know), copy the whole VM and try it there first. A copy is a separate
VM with its own disk, so nothing you do there reaches the live site. On
your computer:

```bash
ssh exe.dev cp my-wordpress my-wordpress-staging
ssh exe.dev share set-private my-wordpress-staging
```

The copy takes the original's sharing, so if your site is public, make
the copy private right away. Give it a minute to start, then point the copy at its own address. On
the copy (`ssh my-wordpress-staging.exe.xyz`):

```bash
cd ~/wordpress
old=$(grep ^WP_URL= .env | cut -d= -f2)
sed -i "s|^WP_URL=.*|WP_URL=https://$(hostname).exe.xyz|" .env
docker compose up -d --wait
wp search-replace "$old" "https://$(hostname).exe.xyz" --all-tables --skip-columns=guid
wp option update blog_public 0
```

Now https://my-wordpress-staging.exe.xyz/ is a private twin of your
site. When you're happy, make the same change on the live VM, and delete
the copy with `ssh exe.dev rm my-wordpress-staging`. [Dev, test, and
prod on exe.dev](/deploy/dev-test-prod) has more on working this way.

## Move an existing site here

The easy way is [All-in-One WP
Migration](https://wordpress.org/plugins/all-in-one-wp-migration/):
install it on the old site and export to a file, then install it here
and import that file under **All-in-One WP Migration → Import**. The
free plugin exports a site of any size; how big a file it can import is
the upload limit in `~/wordpress/php.ini` (128 MB). The import replaces
your users with the old site's, so log in with your old password
afterwards. Check that the four `exe-dev-*.php` files are still in
`~/wordpress/html/wp-content/mu-plugins`.

For a big site, or if you'd rather see each step, move the database and
`wp-content` yourself. On the old host (with WP-CLI, in the WordPress
directory):

```bash
wp db export site.sql
tar -czf wp-content.tar.gz wp-content
grep table_prefix wp-config.php
```

Copy both files to `~/` on the VM with `scp`. If the table prefix isn't
`wp_`, add `WORDPRESS_TABLE_PREFIX: yourprefix_` under
`x-wordpress-env` in `~/wordpress/compose.yaml` and run
`docker compose up -d --wait`. Then, on the VM:

```bash
cd ~/wordpress
./backup.sh
docker compose exec -T db sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb -uroot wordpress' < ~/site.sql
mv html/wp-content html/wp-content.before
tar -xzf ~/wp-content.tar.gz -C html
mkdir -p html/wp-content/mu-plugins
cp html/wp-content.before/mu-plugins/exe-dev-*.php html/wp-content/mu-plugins/
rm -f html/wp-content/object-cache.php html/wp-content/advanced-cache.php
wp search-replace https://old.example.com "https://$(hostname).exe.xyz" --all-tables --skip-columns=guid
wp rewrite flush
wp cache flush
```

Replace `https://old.example.com` with the old site's address, exactly as
it appears in its **Settings → General**. Removing `object-cache.php`
and `advanced-cache.php` drops the old host's caching, which needs
services this VM doesn't run; also look in `html/wp-content/mu-plugins`
for the old host's own must-use plugins and delete them. Log in with
the old site's username and password, and when everything looks right,
delete `html/wp-content.before`. Ask Shelley to do any of this for you.

## Keep your site

Every night, a backup of the database, `wp-content` (uploads, themes,
and plugins), `wp-config.php`, and `~/wordpress/.env` lands in
`~/wordpress/backups`; the newest 7 stay. A backup on the same disk
won't survive losing the VM, so keep a copy **off the VM**. On your
computer:

```bash
scp -r my-wordpress.exe.xyz:wordpress/backups wordpress-backups
```

The backups hold your database password and everything on the site, so
keep them private. exe.dev's [VM backups](/docs/vm-backups) (in
preview) can also copy the whole disk to your own S3 bucket. Before any
big change, run `~/wordpress/backup.sh` on the VM. To restore, see [Back
up and restore](#back-up-and-restore).

Something odd? On the VM, `cd ~/wordpress && docker compose logs --tail
50` usually explains it, or ask Shelley to look.

## The nuts and bolts

Happy clicking Deploy? You can stop here. These are the same setup steps
Shelley follows, plus the maintenance commands for later.

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Install by hand</summary>

### Create a VM

On your computer (pick another name if `my-wordpress` is taken):

```bash
ssh exe.dev new --name=my-wordpress
ssh my-wordpress.exe.xyz
```

All remaining installation commands run **on the VM**, as `exedev`.
Commands use `hostname`, so your VM can have any name.

### Write the settings

Docker comes with the VM; make sure it starts at boot:

```bash
sudo systemctl enable --now docker.service
mkdir -p ~/wordpress/exe-dev ~/wordpress/html && cd ~/wordpress
```

Generate the database passwords once, into a file only you can read.
`WP_URL` is the site's address:

```bash
[ -e .env ] || (umask 077; cat > .env <<EOF
WP_URL=https://$(hostname).exe.xyz
DB_PASSWORD=$(openssl rand -hex 24)
DB_ROOT_PASSWORD=$(openssl rand -hex 24)
EOF
)
```

Back up `.env` with the rest: WordPress can't reach its database
without it.

Now `compose.yaml`. The `wordpress` service is the official image with
PHP 8.4 and Apache, run as your user (uid 1000) rather than root, so
the files in `~/wordpress/html` belong to you and WordPress can update
itself.
`WP_HOME` and `WP_SITEURL` come from `WP_URL`. The image's generated
`wp-config.php` turns on HTTPS when exe.dev's proxy sends
`X-Forwarded-Proto: https`, so WordPress builds `https://` links behind
the proxy without redirect loops. `db` is MariaDB 12.3, the current
long-term release, on no published port. The health checks let
`docker compose up --wait` return only once MariaDB is ready and
WordPress's files are in place. `cli` runs WP-CLI on demand.

```bash
cat > compose.yaml <<'EOF'
name: wordpress
x-wordpress-env: &wordpress-env
  WORDPRESS_DB_HOST: db
  WORDPRESS_DB_NAME: wordpress
  WORDPRESS_DB_USER: wordpress
  WORDPRESS_DB_PASSWORD: ${DB_PASSWORD:?}
  WORDPRESS_CONFIG_EXTRA: |
    define('WP_HOME', '${WP_URL:?}');
    define('WP_SITEURL', '${WP_URL:?}');
services:
  db:
    image: mariadb:12.3
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: ${DB_PASSWORD:?}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:?}
      MARIADB_AUTO_UPGRADE: "1"
    volumes: ["./db:/var/lib/mysql"]
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 30
  wordpress:
    image: wordpress:php8.4-apache
    restart: unless-stopped
    user: "1000:1000"
    depends_on:
      db: { condition: service_healthy }
    environment: *wordpress-env
    ports: ["8000:80"]
    volumes:
      - ./html:/var/www/html
      - ./php.ini:/usr/local/etc/php/conf.d/zz-exe-dev.ini:ro
      - ./exe-dev:/etc/exe-dev:ro
    healthcheck:
      test: ["CMD", "curl", "-fso", "/dev/null", "http://localhost/wp-includes/images/blank.gif"]
      interval: 30s
      timeout: 5s
      start_period: 60s
      start_interval: 2s
  cli:
    image: wordpress:cli-2-php8.4
    profiles: [cli]
    user: "1000:1000"
    environment:
      <<: *wordpress-env
      HOME: /tmp
    volumes:
      - ./html:/var/www/html
      - ./php.ini:/usr/local/etc/php/conf.d/zz-exe-dev.ini:ro
      - ./exe-dev:/etc/exe-dev:ro
EOF
```

PHP's limits, for uploads and imports up to 128 MB:

```bash
cat > php.ini <<'EOF'
upload_max_filesize = 128M
post_max_size = 128M
memory_limit = 256M
max_execution_time = 120
EOF
```

The exe.dev accounts allowed into `wp-admin`, starting with yours (one
email per line):

```bash
[ -s exe-dev/admin-emails ] || curl -fsS https://reflection.int.exe.xyz/email | jq -r .email > exe-dev/admin-emails
cat exe-dev/admin-emails
```

It should print your email. If it doesn't, write your email into that
file yourself.

### Start WordPress

```bash
docker compose up -d --wait --quiet-pull
docker compose ps
```

Both `db` and `wordpress` should be up and healthy. On first
start, the image copies WordPress into `~/wordpress/html` and writes
`wp-config.php` with fresh secret keys. Check it answers:

```bash
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' \
  -H "Host: $(hostname).exe.xyz" -H 'X-Forwarded-Proto: https' http://localhost:8000/
```

That prints `302 https://<your VM>.exe.xyz/wp-admin/install.php`.

### Add the exe.dev plugins

Four must-use plugins, which WordPress loads on every request and which
can't be switched off from the dashboard:

- [exe-dev-login-gate.php](https://exe-staging.dev/deploy/wordpress/exe-dev-login-gate.php)
  lets only the accounts in `exe-dev/admin-emails` reach
  `wp-login.php`, `wp-admin`, and `xmlrpc.php` (but not `admin-ajax.php`
  and `admin-post.php`, which themes and forms use on public pages). It
  also turns off application passwords, which would sign in past it.
- [exe-dev-mail.php](https://exe-staging.dev/deploy/wordpress/exe-dev-mail.php)
  sends `wp_mail()` through exe.dev's email gateway.
- [exe-dev-loopback.php](https://exe-staging.dev/deploy/wordpress/exe-dev-loopback.php)
  sends WordPress's requests to its own URL straight to the `wordpress`
  container. A private site answers anonymous requests with exe.dev's
  sign-in, so without it WP-Cron (scheduled posts, update checks), Site
  Health, and the installer's permalink check fail.
- [exe-dev-integrations.php](https://exe-staging.dev/deploy/wordpress/exe-dev-integrations.php)
  sends calls to the Anthropic and OpenAI APIs to exe.dev's LLM gateway.
  It does nothing until an AI plugin makes such a call.

```bash
mkdir -p ~/wordpress/html/wp-content/mu-plugins && cd ~/wordpress/html/wp-content/mu-plugins
for f in exe-dev-login-gate.php exe-dev-mail.php exe-dev-loopback.php exe-dev-integrations.php; do
  curl -fsSL -O "https://exe-staging.dev/deploy/wordpress/$f"
done
ls
```

Check the gate with no exe.dev email, someone else's, and yours:

```bash
cd ~/wordpress
for email in "" someone@example.com "$(head -n 1 exe-dev/admin-emails)"; do
  curl -s -o /dev/null -w "${email:-no email}: %{http_code}\n" -H "X-ExeDev-Email: $email" \
    -H "Host: $(hostname).exe.xyz" -H 'X-Forwarded-Proto: https' http://localhost:8000/wp-admin/install.php
done
```

That prints `302` (off to exe.dev's sign-in), `403`, and `200`.

### Add the wp command

A wrapper that runs WP-CLI in the `cli` container, against the same
files and database:

```bash
cat > ~/wordpress/wp <<'EOF'
#!/bin/sh
# Run WP-CLI against this WordPress: wp plugin list, wp user list, ...
cd "$(dirname "$(readlink -f "$0")")" && exec docker compose run --rm --quiet-pull cli wp "$@"
EOF
chmod +x ~/wordpress/wp
sudo ln -sf ~/wordpress/wp /usr/local/bin/wp
wp core version
```

It prints the WordPress version, `7.1.4` or newer. Docker prints a
`Container ... Running` line or two first; that's normal.

### Set up nightly backups

[backup.sh](https://exe-staging.dev/deploy/wordpress/backup.sh) dumps the
database with `mariadb-dump` and packs it with `.env`, `compose.yaml`,
`php.ini`, `exe-dev/`, `wp-config.php`, `.htaccess`, and `wp-content`
(minus caches) into one `.tar.gz` in `~/wordpress/backups`, keeping the
newest 7. WordPress itself isn't in it: the image brings it back.

```bash
curl -fsSL -o ~/wordpress/backup.sh https://exe-staging.dev/deploy/wordpress/backup.sh
chmod +x ~/wordpress/backup.sh
```

Run it at 03:30 every night, or soon after the VM starts if it was off:

```bash
sudo tee /etc/systemd/system/wordpress-backup.service >/dev/null <<EOF
[Unit]
Description=Back up WordPress to ~/wordpress/backups
After=docker.service

[Service]
Type=oneshot
User=$USER
ExecStart=$HOME/wordpress/backup.sh
EOF
sudo tee /etc/systemd/system/wordpress-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up WordPress every night

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now wordpress-backup.timer
sudo systemctl start wordpress-backup.service
ls -l ~/wordpress/backups
```

You should see one `wordpress-<date>.tar.gz`, and
`systemctl list-timers wordpress-backup.timer` shows the next run.

### Run the installer

Open https://my-wordpress.exe.xyz/ in your browser and fill in the
installer, as in [Finish the install](#finish-the-install). Then check
the address WordPress uses, and that permalinks are on:

```bash
wp option get home
wp option get permalink_structure
```

The first prints `https://<your VM>.exe.xyz`, the second
`/%year%/%monthnum%/%day%/%postname%/` (change it under **Settings →
Permalinks**). Under **Tools → Site Health → Info**, nothing should be
critical, and the loopback request, REST API, and background updates
checks should pass.

</details>

<details id="back-up-and-restore" class="dp-details">
<summary>Back up and restore</summary>

On the VM, `~/wordpress/backup.sh` takes an extra backup and prints its
file name. Each backup holds `wordpress.sql` (the database), `.env`,
`compose.yaml`, `php.ini`, `exe-dev/`, `html/wp-config.php`,
`html/.htaccess`, and `html/wp-content`. Look inside one with
`tar -tzf ~/wordpress/backups/<file> | less`.

### Undo a mistake in the database

Deleted the wrong page? WordPress's trash keeps posts and pages for 30
days. For anything else, load a backup's database **next to** the live
one and copy back what you need. On the VM:

```bash
cd ~/wordpress
ls backups
tar -xzf backups/wordpress-<date>.tar.gz -C /tmp wordpress.sql
docker compose exec -T db sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb -uroot -e "CREATE DATABASE restored"'
docker compose exec -T db sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb -uroot restored' < /tmp/wordpress.sql
```

Shelley can compare the two and copy rows across. Drop the copy when
you're done:

```bash
docker compose exec -T db sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb -uroot -e "DROP DATABASE restored"'
rm /tmp/wordpress.sql
```

### Put the whole site back

To roll the site back to a backup, on the same VM or a new one: on a
new VM, run `sudo systemctl enable --now docker.service` first. Copy the
backup to `~/` on the VM (`scp` it from your computer, or
`cp ~/wordpress/backups/wordpress-<date>.tar.gz ~/`), then:

```bash
mkdir -p ~/wordpress && cd ~/wordpress
docker compose down 2>/dev/null; sudo rm -rf db html
tar -xzf ~/wordpress-<date>.tar.gz
docker compose up -d --wait --quiet-pull
docker compose exec -T db sh -c 'MYSQL_PWD="$MARIADB_ROOT_PASSWORD" exec mariadb -uroot wordpress' < wordpress.sql
rm wordpress.sql
```

This deletes the VM's current database and files first, so on a VM
with a site you want to keep, take a backup before. The image puts
WordPress back around the restored `wp-content` and keeps the restored
`wp-config.php`. Then add the `wp` command and the backup timer from
[Install by hand](#create-the-vm). On a VM with a different name, run
the commands in [Use your own domain](#use-your-own-domain) with the new
`https://<VM>.exe.xyz` address. Log in with your usual WordPress
password.

### Back up more often

For hourly backups, change `OnCalendar` in
`/etc/systemd/system/wordpress-backup.timer` to `hourly` and the `keep`
line in `~/wordpress/backup.sh` to keep a day or two, then run
`sudo systemctl daemon-reload`.

</details>

<details id="update" class="dp-details">
<summary>Update WordPress, PHP, and MariaDB</summary>

**WordPress, plugins, and themes** update from the dashboard, under
**Dashboard → Updates**, or on the VM:

```bash
~/wordpress/backup.sh
wp core update
wp plugin update --all
wp theme update --all
```

WordPress installs minor and security releases by itself. Try a major
release, or a plugin you rely on, on [a copy](#try-changes-on-a-copy)
first.

**PHP, Apache, MariaDB, and WP-CLI** come from the Docker images. On the
VM:

```bash
cd ~/wordpress
./backup.sh
docker compose pull --quiet
docker compose up -d --wait
docker image prune -f
```

That picks up fixes within PHP 8.4 and MariaDB 12.3; MariaDB upgrades
its data files itself (`MARIADB_AUTO_UPGRADE`). To move to a newer PHP
or MariaDB release, change the `image:` tags in `compose.yaml`
(`wordpress:php8.5-apache`, say, once your plugins support it) and run
the same commands, on a copy first.

</details>

<details id="troubleshooting" class="dp-details">
<summary>Something not working?</summary>

Logs first. On the VM:

```bash
cd ~/wordpress
docker compose ps
docker compose logs --tail 50 wordpress
docker compose logs --tail 50 db
```

**"Error establishing a database connection."** `docker compose ps`
shows whether `db` is up and healthy. If you changed `DB_PASSWORD` in
`.env` after the first start, change it back: MariaDB set the password
when it created the database and doesn't read it again.

**Redirected to exe.dev's sign-in, or "can't open the WordPress
admin".** That's the login gate. Add the email you sign in to exe.dev
with to `~/wordpress/exe-dev/admin-emails`; it takes effect at once.

**Too many redirects, or `http://` links.** Something in front of
exe.dev's proxy, such as Cloudflare's orange-cloud proxy, is changing the
request; turn it off. Check that `WP_URL` in `.env` is the address you
use, with `https://`, and that **Settings → General** shows it greyed out.

**The upload is too large.** Raise `upload_max_filesize` and
`post_max_size` in `~/wordpress/php.ini`, then
`docker compose restart wordpress`.

**Scheduled posts miss their time, or Site Health says the loopback
request failed.** Check that `exe-dev-loopback.php` is in
`~/wordpress/html/wp-content/mu-plugins`. WP-Cron runs when someone
visits the site; for exact timing on a quiet site, ask Shelley to run
`wp cron event run --due-now` from a systemd timer every few minutes.

**Email doesn't arrive.** `docker compose logs wordpress | grep 'exe.dev
mail'` shows what the gateway said. It only delivers to you, your team,
and people you've shared the VM with; see [Email](#email).

**Locked out of WordPress.** Reset a password on the VM:
`wp user update <username> --user_pass='<new password>'`, or
`wp user list` to see the usernames.

**The site is down after a restart.** `systemctl is-enabled
docker.service` should say `enabled`; both services have
`restart: unless-stopped`, so they come back with Docker unless you
stopped them with `docker compose stop` or `down`. Start them with
`docker compose up -d`.

</details>

## Frequently asked questions

### Is WordPress free?

Yes. WordPress is open source under the GPL, and so are the Docker images, MariaDB, WP-CLI, and every plugin this page installs. You pay for the VM; see [exe.dev plans](https://exe.dev/pricing). Email through exe.dev and calls through the LLM gateway come with your plan, within its limits.

### Why Docker and not PHP-FPM and nginx installed on the VM?

The official `wordpress` image is what most of the WordPress world tests against: PHP with every extension WordPress asks for, Apache with `.htaccess` permalinks, and OPcache, all in one tag you can update with `docker compose pull`. Ubuntu's own PHP lags behind and third-party PHP packages need another repository. WordPress still lives in plain files in `~/wordpress/html`, so Shelley, `wp`, and your editor see the same thing. A native install is fine too, if you prefer; ask Shelley.

### Why MariaDB and not MySQL?

Both work, and WordPress supports both. MariaDB's official image upgrades its own data files when you move to a newer version, which makes updates one command. To use MySQL, set up [MySQL on exe.dev](/deploy/mysql) on this VM or another one, point `WORDPRESS_DB_HOST` at it, and drop the `db` service.

### Does WordPress update itself?

Yes. WordPress owns the files in `~/wordpress/html` and applies minor and security releases on its own; you approve major releases and plugin updates in the dashboard (or turn on auto-updates per plugin). The Docker image only supplies PHP and Apache, which you update with `docker compose pull`. See [Update](#update).

### My visitors need to log in (a shop, a membership site, comments). Will that work?

Not with the login gate as it is: it sends everyone who isn't on your list to exe.dev's sign-in. Delete `exe-dev-login-gate.php` and use WordPress's own logins instead, with the [Two Factor](https://wordpress.org/plugins/two-factor/) plugin for your admin accounts. See [Who can sign in](#who-can-sign-in).

### Can I run several sites on one VM?

Yes, as WordPress Multisite, or with a second copy of `~/wordpress` on another port, though only port 8000 can be made public. A VM per site is simpler: each gets its own URL, backups, and copies for staging.

### How big a site fits?

A new VM has room for the Docker images (about 2 GB) and many gigabytes of uploads. Run `df -h /` on the VM to see what's free; `ssh exe.dev resize my-wordpress --disk=50GB` grows the disk when it fills up.


## Related

- [Self-host MySQL](https://exe-staging.dev/deploy/mysql.md): Your own MySQL on a real disk, private by default, with backups you've restored.
- [Dev, Test, Prod: Choose One, Two, or Three](https://exe-staging.dev/deploy/dev-test-prod.md): You can build, test, and deploy on exe.dev.
- [Deploy a Laravel app](https://exe-staging.dev/deploy/laravel.md): Your Laravel app on a server of its own. git push to deploy.
- [Self-host Uptime Kuma](https://exe-staging.dev/deploy/uptime-kuma.md): A little lookout for your websites. Green bars encouraged.
- [Self-host n8n](https://exe-staging.dev/deploy/n8n-2.md): Connect your apps. Let the boring bits run themselves.
- [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
