Skip to content
How to install

Architecture

Every server runs the same small stack of containers, and every site is one more container beside it. The panel runs on the first server and drives the others over SSH. This page is the map: what runs, what it is called, where it keeps its files, and what can reach what.

Container Image What it does
wpl7-traefik traefik:v3.7 Takes ports 80 and 443, with UDP 443 for HTTP/3, gets certificates, routes each hostname to its site, applies site protection and writes the access log
wpl7-mariadb mariadb:11.4 The database server, with one user per site and that site’s databases. Its buffer pool is an eighth of the server’s memory, from 256 MB to 4 GB, unless MARIADB_POOL_SIZE says otherwise
wpl7-mail boky/postfix The mail relay: takes every site’s mail, queues it and delivers it
wpl7-dkim instrumentisto/opendkim Signs outgoing mail for the relay
wpl7-panel ghcr.io/andyfo/wpl7/panel The API, the web interface and the job queue. On the panel’s server only
wp-<slug> wpl7-wordpress:php<version> One site, WordPress or PHP: nginx, Apache and PHP-FPM, with Redis when it is on
wpl7-ftp wpl7-sftpgo The FTP and SFTP gateway. Only on a server with FTP logins
wpl7-ftp-<slug> wpl7-sftpgo The file server behind one site’s FTP logins
wpl7-adminer wpl7-adminer Adminer, only while someone uses it. The panel reaches it through docker exec, so it listens on no network

Malware scans, offsite copies and database imports run in throwaway containers that exist for one task.

  • A worker runs the same stack without the panel container.
  • Each site lives on one server, with its files, database, mail and certificates.
  • The panel reaches a worker over SSH only, as the wpl7-panel user, which can use Docker and sudo. A server’s SSH host key is pinned on the first connection.
  • Adding a server pushes the panel’s own copy of provision/ and deploy/, then runs setup.sh --role=worker. After a panel update, the panel does the same on every worker.
Network Internal Members
wpl7_proxy no Traefik, the panel, the relay and the signer. No sites
wpl7_db yes MariaDB and the panel. No sites
wpl7_site_<slug> yes One site, plus Traefik, the relay as mail and MariaDB as mariadb
wpl7_egress no, with traffic between containers switched off Every site container. Its only use is the way out to the internet
wpl7_ftp yes The FTP gateway and the file servers
wpl7_ftp_edge no, with traffic between containers switched off The FTP gateway alone, for its published ports
wpl7_adminer yes Adminer and MariaDB as mariadb

A site can reach the infrastructure it needs and the internet. It cannot reach another site or the panel. A docker compose up recreates Traefik, MariaDB and the relay without the site networks, so the panel attaches them again at boot and every minute.

All names follow from the site’s slug, 3 to 32 lowercase letters, digits and dashes.

Thing Pattern For northwind-bakery
Container wp-<slug> wp-northwind-bakery
Database and database user wp_ and the slug with dashes turned into underscores wp_northwind_bakery
A database added to the site Its own name, which never starts with wp_ northwind_orders
Site network wpl7_site_<slug> wpl7_site_northwind-bakery
Traefik router and service wp-<slug> wp-northwind-bakery
Redirect from extra domains wp-<slug>-canonical wp-northwind-bakery-canonical
Relay login <slug>@wpl7 northwind-bakery@wpl7
FTP file server wpl7-ftp-<slug> wpl7-ftp-northwind-bakery

Site containers carry the labels wpl7.managed=true, wpl7.site=<slug>, wpl7.role=wordpress and wpl7.php=<version>. One on the current setup also has wpl7.stack=2, and one without it runs Apache with mod_php. A PHP site’s container also has wpl7.app=php. A container app’s has wpl7.role=app and traefik.enable=false, and its routers in its routes file are wpl7app_r<route id>_<slug>. To list one site’s containers:

Terminal window
docker ps -a --filter label=wpl7.site=northwind-bakery

Everything lives under /srv, the SRV_ROOT in deploy/.env. The panel container mounts it at the same path, so every path the panel hands to Docker is valid on the host.

Path What it holds
/srv/sites/<slug>/wordpress/ The site’s files, owned by uid 33
/srv/sites/<slug>/config/ The site’s PHP limits in uploads.ini, its relay login and its protection settings. runtime/ holds what its nginx, PHP-FPM, OPcache, Redis and wp-cache.php read, and its default mail sender
/srv/sites/<slug>/quarantine/ Files a malware scan moved out of the site. Mounted into no site
/srv/sites/<slug>/site.json A description of the site, for recovery by hand
/srv/sites/<slug>/db-uploads/ A dump uploaded for an import, until the import is done. Mounted into no site
/srv/sites/<slug>/data/, mounts/ A container app’s data folders and mounts, owned by the user it runs as. mount-uploads/ holds an archive until it is unpacked
/srv/panel/app-uploads/ Image archives uploaded for container apps, on the panel’s server, until a deploy loads them
/srv/backups/<slug>/<timestamp>/ Backups, unless the server’s backup location was moved
/srv/backups/panel/<timestamp>/ Nightly copies of the panel’s database, on the panel’s server
/srv/external/<slug>/wordpress/ The copy of a site hosted elsewhere that its next backup builds on, on the server that keeps its backups
/srv/plugins/ Uploaded plugin zips, mounted read-only into every WordPress site
/srv/mysql/ MariaDB’s data
/srv/mail/ The relay’s sender maps and logins, and the DKIM keys and settings
/srv/traefik/acme*.json Certificates and ACME accounts, mode 600
/srv/traefik/dynamic/ Rules Traefik reads from files: sec-<slug>.yml for site protection, app-<slug>.yml for a container app’s routes, wpl7-blocked.yml, and move-<slug>.yml while a moved site waits for DNS
/srv/wpl7-ftp/ The FTP gateway’s and file servers’ settings
/srv/wpl7-firewall/ The block list for the firewall and its status. Root only
/srv/wpl7-scan/<scan-id>/ A running malware scan’s input
/srv/panel/panel.db The panel’s state, in SQLite, mode 600
/srv/panel/ssh/id_ed25519 The panel’s SSH key, on the panel’s server
/srv/panel/geoip/ The internet registries’ country tables, refreshed weekly
/srv/panel/external/listings/ What the last backup of each site hosted elsewhere found, file by file
/srv/panel/update/ The state and log of the last update

The image wpl7-wordpress:php<version> is the official wordpress:php<version>-fpm image with nginx, Apache, Redis and phpredis, msmtp, so PHP’s mail() reaches the relay, and WP-CLI. PHP 8.2 to 8.5 are offered.

Since 0.3.3 The image also runs PHP sites, as its label wpl7.apps says. wpl7-start puts WordPress into a site’s folder only for a container with WordPress’s database settings, which a PHP site’s never has. PHP has PDO’s MySQL driver beside mysqli. wpl7-sendmail runs msmtp for mail() and for /usr/sbin/sendmail, with one sender for each message.

Since 0.3.2 The image turns off PHP’s upload progress tracking, which WordPress does not use. Its build stops when the base image’s PHP is older than the last security release of its branch. When a server’s image changes, the panel rebuilds the containers of that server’s sites on it, at its next start or within the hour.

Since 0.3.3 A container runs up to four services. tini is process 1, and wpl7-start runs them in the foreground. When one exits by itself, the others stop and the container exits, so the restart policy brings the whole site back.

Service Where What it does
nginx Port 8080, which Traefik reaches The page cache of a WordPress site. Stored pages are in /var/cache/nginx/wpl7, about 256 MB at most, and every start empties it. On a PHP site it passes every request to Apache
Apache, with the event MPM 127.0.0.1:80 .htaccess, static files, Brotli and gzip, and cache times: 30 days for images, fonts, audio and video, 7 days for CSS and JS
PHP-FPM /run/wpl7/php-fpm.sock Runs files named .php, in a pool sized from the site’s limits
Redis /run/wpl7/redis.sock The object cache, or a PHP site’s own Redis, only while it is on

The panel’s REST tool asks Apache on the loopback, so it skips the cache. A visitor cannot: nginx is the only way in from outside.

Mounted from the host Inside the container
/srv/sites/<slug>/wordpress /var/www/html
/srv/sites/<slug>/config/uploads.ini /usr/local/etc/php/conf.d/zz-site.ini, read-only
/srv/sites/<slug>/config/msmtprc /etc/msmtprc, read-only
/srv/sites/<slug>/config/security-apache.conf /etc/apache2/conf-enabled/zz-wpl7-security.conf, read-only
/srv/sites/<slug>/config/security/ /etc/wpl7, read-only
/srv/sites/<slug>/config/runtime/ /etc/wpl7-runtime, read-only
/srv/plugins /srv/plugins, read-only, on a WordPress site
  • wp-config.php reads the database settings from the container’s WORDPRESS_DB_* variables.
  • WORDPRESS_CONFIG_EXTRA turns HTTPS on behind Traefik, sets DISABLE_WP_CRON, and loads the site’s protection from /etc/wpl7/wp-config-extra.php. It also loads /etc/wpl7-runtime/wp-cache.php, the WordPress side of the caches.
  • The panel writes /etc/wpl7-runtime before every start, and applies a change to a running container in place. Nothing in the site can change that folder.
  • The panel runs each running site’s due cron events every five minutes instead.
  • A PHP site’s container has no WORDPRESS_* variables. Its own cron lines run every minute at the most, as uid 33 in its folder.
  • WP-CLI runs inside the site’s container as uid 33, so the PHP version and mail settings always match the site.
  • The panel keeps two must-use plugins in the site: wpl7-login.php for one-click login, and wpl7-licenses.php for recipe constants.
  • The panel opens single files inside the site’s container, as the site’s user. Backups, restores and moves copy whole folders with tar on the host, which never follows a link.
Measure What it is
Networks Its own network and the way out, nothing else
Ports Only nginx’s, 8080. Apache listens on the loopback, and PHP-FPM and Redis on sockets
Capabilities Docker’s defaults without NET_RAW, MKNOD, SYS_CHROOT, AUDIT_WRITE, SETFCAP and SETPCAP
no-new-privileges Set, so setuid programs cannot raise privileges
CPU, memory and processes Per-site ceilings from Settings, by default 2 cores, 512 MB and 512 processes, or the site’s own. Processes are at least 64
Mail Its own relay login, which may only send from the site’s own domains

The ceilings change on running containers when you save them. Removing a CPU ceiling is the one change Docker cannot make live, so it recreates each site.

Resolver Challenge Used for
letsencrypt HTTP Custom domains, the panel, and dev sites without the wildcard
letsencrypt-staging HTTP The same, against Let’s Encrypt’s test service
letsencrypt-dns DNS One wildcard certificate for *.<dev domain>, shared by a server’s dev sites
letsencrypt-dns-staging DNS The same, against the test service
  • A site on a custom domain always gets its own certificates through the HTTP check.
  • ACME_RESOLVER=letsencrypt-staging moves every certificate to the test service, the wildcard included. TLS_MODE only chooses between https and plain http.
  • The DNS resolvers use DNS_PROVIDER, or Cloudflare when it is empty.

Since 0.3.0-beta.2 The wildcard certificate is a switch per server in Settings → DNS. With Cloudflare, dev sites share it only while the panel has a token to answer the DNS check. Traefik reads the token from /srv/traefik/dns/cloudflare-api-token, which the panel writes on every server, and the panel restarts Traefik when the token changes.

  • One Node 22 process serves the REST API and the web interface, and keeps its state in SQLite.
  • It holds the Docker socket and the SSH key for every server, so it is root-equivalent on its host by design.
  • Long operations are jobs with a log. A server runs one job at a time. Some jobs take a lane of their own instead, so they run beside that server’s site work.
  • Everything recurring runs through one scheduler, listed on Automations → Schedules.
  • Mail traffic and visitor statistics are read from the relay’s and Traefik’s logs every minute.
  • A site’s Database tab reaches MariaDB through docker exec: a relay in the wpl7-mariadb container joins the command’s input and output to MariaDB’s port. It logs in as the site’s own database user. No database port is published, and none is forwarded over SSH.
  • Adminer has a front door of its own in the panel’s process, on port 3001 and the address db.<dev domain>. It passes each request on through docker exec to the site’s server’s wpl7-adminer.
  • AI apps use the same API through /mcp.
Lane What runs in it
The server’s own Work on its sites, such as creating, backing up, restoring, moving and deleting them
offsite:<server> Uploads of offsite copies, one at a time per server
exec:<server> WP-CLI commands, shell commands and REST requests run in sites
scan:<server> Malware scans, and checks of plugin catalog zips
housekeeping The nightly housekeeping job
backup-delete Deleting backups in bulk
external-0, external-1 Every job of a site hosted elsewhere, two such sites at a time
  • Each site has a Docker network of its own, and the panel creates it from Docker’s default address pools. On Docker 29 these hold 31 networks.
  • The stack’s own networks and Docker’s default bridge take four of them, and FTP two more on a server with FTP logins. That leaves room for about 25 sites per server.
  • setup.sh replaces /etc/docker/daemon.json with provision/daemon.json whenever they differ, so a larger address pool added there by hand does not survive the next run.
  • The panel is root-equivalent on its own host. Anyone who can sign in to it can run anything on its servers.