Self-host WordPress
Your WordPress on a computer of its own, with wp-admin only you can reach.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe.dev/deploy/wordpress/prompt.txt | ssh exe.dev new --prompt=/dev/stdinWordPress 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.
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
wpcommand (WP-CLI) on the VM, and nightly backups of the database and wp-content.
What's running, and where
https://my-wordpress.exe.xyz/
your site, until you make it public
https://my-wordpress.exe.xyz/wp-admin/
the WordPress dashboard, for exe.dev accounts you list, even when the site is public
wp command, run in its own container
Deploy with Shelley#
Click Deploy and Shelley will set up WordPress on a new VM, then check that it works. No config-file wrangling required.
Prefer a terminal?
curl -fsSL \
https://exe.dev/deploy/wordpress/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhat Shelley is told
Set up WordPress on this VM by following the exe.dev recipe at https://exe.dev/deploy/wordpress.md from top to bottom.
The recipe's example VM name is my-wordpress. This VM's name is the output of `hostname`: use it wherever the recipe writes my-wordpress. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- 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.
Read the whole recipe, including the closed details. For initial setup,
follow "Install by hand" from top to bottom: Docker, ~/wordpress with
.env, compose.yaml and php.ini, the owner's email in
~/wordpress/exe-dev/admin-emails (from the reflection integration; if
that fails, ask the owner), the four exe.dev plugins, the wp command,
and the backup timer. Never overwrite an existing ~/wordpress/.env.
Don't run the WordPress installer yourself, and don't make the site
public, add a domain, install plugins, migrate a site, or run the
Restore or Update instructions during initial setup; the walkthrough
sections are for the owner afterwards. Check the login gate on localhost
with no email, a wrong email, and the owner's email. Do not reboot.
Until the owner runs the installer, wp commands that need the site (wp
option, wp eval) fail; that's expected, and the mail and loopback
plugins can only be tried after it. Finish with the private URL
https://<vm>.exe.xyz/ and ask the owner to open it, choose a site title,
username and password in the WordPress installer, and log in. Don't
paste the database passwords into the chat; say they are in
~/wordpress/.env.
Finish with the URLs I should open.
Also at /deploy/wordpress/prompt.txt. The recipe it follows is /deploy/wordpress.md.
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? 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,
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:
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 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:
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 explains. On your computer:
ssh exe.dev domain add my-wordpress blog.example.com
Then tell WordPress its new address. On the VM:
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
sends it through exe.dev's email gateway: 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:
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 or 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 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 can answer it with no API key.
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:
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):
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 has more on working this way.
Move an existing site here#
The easy way is 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):
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:
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:
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 (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.
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.
Install by hand
Create a VM#
On your computer (pick another name if my-wordpress is taken):
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:
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:
[ -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.
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:
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):
[ -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#
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:
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
lets only the accounts in
exe-dev/admin-emailsreachwp-login.php,wp-admin, andxmlrpc.php(but notadmin-ajax.phpandadmin-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
sends
wp_mail()through exe.dev's email gateway. - exe-dev-loopback.php
sends WordPress's requests to its own URL straight to the
wordpresscontainer. 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 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.
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.dev/deploy/wordpress/$f"
done
ls
Check the gate with no exe.dev email, someone else's, and yours:
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:
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 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.
curl -fsSL -o ~/wordpress/backup.sh https://exe.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:
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. Then check the address WordPress uses, and that permalinks are on:
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.
Back up and restore
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:
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:
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:
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. On a VM with a different name, run
the commands in 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.
Update WordPress, PHP, and MariaDB
WordPress, plugins, and themes update from the dashboard, under Dashboard → Updates, or on the VM:
~/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 first.
PHP, Apache, MariaDB, and WP-CLI come from the Docker images. On the VM:
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.
Something not working?
Logs first. On the VM:
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.
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.
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. 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 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.
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 plugin for your admin accounts. See 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.
Updated Nov 16, 2026 · tested end to end Nov 16, 2026 · Markdown · manifest.json · Something wrong? Tell us