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.
The containers
Section titled “The containers”| 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.
Several servers
Section titled “Several servers”- 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-paneluser, which can use Docker andsudo. A server’s SSH host key is pinned on the first connection. - Adding a server pushes the panel’s own copy of
provision/anddeploy/, then runssetup.sh --role=worker. After a panel update, the panel does the same on every worker.
Networks
Section titled “Networks”| 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:
docker ps -a --filter label=wpl7.site=northwind-bakeryFiles on disk
Section titled “Files on disk”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 |
Site containers
Section titled “Site containers”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.phpreads the database settings from the container’sWORDPRESS_DB_*variables.WORDPRESS_CONFIG_EXTRAturns HTTPS on behind Traefik, setsDISABLE_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-runtimebefore 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.phpfor one-click login, andwpl7-licenses.phpfor 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
taron the host, which never follows a link.
Containment
Section titled “Containment”| 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 |
| 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-stagingmoves every certificate to the test service, the wildcard included.TLS_MODEonly chooses betweenhttpsand plainhttp.- 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.
The panel
Section titled “The panel”- 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 thewpl7-mariadbcontainer 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 throughdocker execto the site’s server’swpl7-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 |
Limits
Section titled “Limits”- 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.shreplaces/etc/docker/daemon.jsonwithprovision/daemon.jsonwhenever 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.