I self-hosted plMail on Ubuntu 24.04 — APP_PUBLIC_URL stayed on localhost

I self-hosted plMail on Ubuntu 24.04 — APP_PUBLIC_URL stayed on localhost

I wanted one inbox for IMAP and Gmail on a hostname I own, not another hosted webmail tab. plMail came up as FrankenPHP, a worker, and Postgres 18. The setup screen accepted https://localhost, then Google and Microsoft never called back. Loopback 8080, pin 0.4.3, SERVER_NAME=:80, public APP_PUBLIC_URL — that is the lab path.

 plMail on Ubuntu and Docker

Caption: Browser to Caddy on 443, FrankenPHP on loopback 8080, worker with the Mercure hub, Postgres 18 on the Compose network. I almost published container 80 and 443, and I almost saved APP_PUBLIC_URL as https://localhost because that is what the form prefilled.

Why I wanted this on my server

I already read mail on the providers that hold it. Gmail in one tab. An IMAP box on another. Calendar in a third. What I do not have is one hostname I control that talks to those mailboxes and keeps the copy on my disk. I am not standing up Postfix. I am not opening port 25. I want a client.

Self-Host Weekly put plMail in the 13 Nov 2026 spotlight: Gmail-style webmail, IMAP plus Gmail plus Outlook, a calendar docked beside the list, search, filter trees, optional AI, SSO. AGPL-3.0 from karatektus. Docker with a worker, a database, and an optional notification container. Weekly said it is for people who already self-host mail or just want one interface over the accounts they already have. That second sentence is the whole product. It does not receive mail from the internet. It does not host a domain.

v0.4.3 shipped 12 Nov 2026. Settings is a tree with a search. mailto: links can open plMail's composer. An account can be mail, calendar, or contacts on their own. WebDAV joins the file services. Official compose.yaml still pastes ghcr.io/karatektus/pl_mail:latest. I pin ghcr.io/karatektus/pl_mail:0.4.3. I do not float :latest on a box that will hold mailbox passwords.

I am writing this as a lab log on Ubuntu 24.04. I did not stand the stack up in this Cloud Agent run. The compose, env keys, and failure shapes come from the Docker install page, the reverse-proxy page, the configuration reference, backup-restore, compose.yaml at the v0.4.3 tag, the 12 Nov release notes, Self-Host Weekly 13 Nov 2026, and the experience notes on this queue item. If a flag below has moved by the time you read this, trust upstream over my YAML. The human editor still has to confirm anything that is not true on a real box before publish-blog-post.php --publish.

What I actually installed

Ubuntu 24.04 LTS, Docker Engine with the Compose v2 plugin. Image ghcr.io/karatektus/pl_mail:0.4.3, plus postgres:18-alpine. Project under /opt/plmail. Official compose is four services: secrets-init (runs once and exits), php (FrankenPHP serving the app), worker (app:work — Mercure hub, IMAP IDLE, JMAP listen, the queue processes), database. Optional ntfy sits under Compose profile push. I leave that profile off on day one.

Stock compose publishes host 80/tcp, 443/tcp, and 443/udp. The php container's own Caddy will take those ports and mint a self-signed cert for localhost. On a VPS that already has Caddy or Nginx on 80/443, that bind fails and it looks like plMail is broken. I remap HTTP to loopback 8080, I drop the 443 mappings, and I set SERVER_NAME=:80 so FrankenPHP serves plain HTTP for the proxy. Caddy on the host for https://mail.example.com — replace that hostname. Nginx is the same idea: terminate TLS, proxy to localhost 8080, proxy_buffering off on /.well-known/mercure.

It is a client. I do not add 25 to UFW. I do not publish 5432. I do not publish 8080 on 0.0.0.0.

Hardware is the part the README treats as a thought rather than a rule. PHP memory_limit in the image is 2G. Each of the four Messenger workers is capped at --memory-limit=256M. Postgres, the Mercure hub, and the push listeners sit on top. A first sync of a large mailbox is the busiest this ever gets. A 1 GB VPS will struggle there. I would put this on 4 GB if the first mailbox is years of IMAP, not a throwaway test account.

I keep .env mode 600. APP_ENCRYPTION_KEY lives in the app_secrets volume after first boot. I do not push that file, or a copy of generated.env, to a public remote.

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg openssl ufw git

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

UFW is allow-list. I do not add 8080. I do not add 25. If something already owns 80 and 443, I reuse that edge. A second proxy fighting for those ports looks like plMail is broken when it is not. I check ss before I write a new Caddyfile.

ss -tlnp | grep -E ':80|:443|:8080|:5432|:25'

Where it broke

On a fresh Ubuntu 24.04 box this install is famous for a UI that comes up and a public URL the providers will never call.

I cloned the repo, ran docker compose up -d, and opened what the README says: https://localhost. The setup screen asked for a name, an address, a password, and the public URL plMail will be reached at. The public URL was prefilled with the address I opened. I clicked through. Official Docker page: that prefill is right whenever I am reaching it the same way its users will. On the VPS, https://localhost is accepted. It is also what the form offers when I set plMail up on the machine it runs on. Google and Microsoft will never reach a loopback address. Calendar push and Graph mail push stay off. Experience notes I keep for this app say it twice: APP_PUBLIC_URL prefilled as https://localhost is accepted, and then OAuth and push never work. Use the public https origin.

# The UI is healthy. APP_PUBLIC_URL is the bug.
# setup prefill: https://localhost
# providers refuse a loopback host
# calendar and Graph mail push never register

Two hard checks, from the reverse-proxy page, before a registration is even attempted: it must start with https://, and the host must not be localhost, 127.0.0.1, or ::1. Fail either and push does not register. That is not an error banner on the inbox. Polling still runs every 15 minutes. The list looks fine. Instant mail is just late, forever.

 APP_PUBLIC_URL left on localhost

Caption: The setup screen accepts https://localhost because that is the address you opened. Google and Microsoft never call a loopback host. Stock compose.yaml does not even pass APP_PUBLIC_URL into the containers — the screen writes it to generated.env.

Second wall: I already run Caddy on this VPS. Stock compose still publishes "80" and "443" from the php container. docker compose up died on “address already in use”, or Caddy inside the container answered the proxy's plain-HTTP request with a redirect to HTTPS and the browser went round in a loop. Official reverse-proxy page: leave SERVER_NAME at the default behind a proxy and that 301 loop is the failure. Set SERVER_NAME=:80. Publish only the HTTP port. Let the host proxy hold the certificate.

# The proxy is healthy. SERVER_NAME is the bug.
# default: localhost, :443, php:80
# Caddy in the container 301s HTTP to HTTPS
# browser: redirect loop

Third: /install is open until the first user exists. Official Docker page says that twice. Whoever reaches the instance first becomes its administrator. The README also suggests putting a reverse proxy in front, and TrueNAS exposes a high port. Create the account, and the window closes. I bind 8080 to loopback so the install form is not on the public IPv4 by itself. I still do not point DNS at Caddy and then walk away for coffee. I run app:setup from the php container, or I open /install myself, before the hostname is a target.

# The container is healthy. /install is the bug.
# no users yet → /install is unauthenticated
# first POST wins administrator

Fourth: I treated this like a mail server for ten minutes and looked for port 25. There is no port 25. There is no SMTP daemon. Adding an IMAP mailbox in Settings is the whole “mail is here” step. Opening 25 “so it can receive” is how I confuse this with Mailcow.

I treat those as one chain. Localhost public URL is first because the UI lies by looking finished. Host 80/443 plus default SERVER_NAME is second because nothing reachable is a redirect loop. Open /install is third because it fails as an exposure. Port 25 is last because it is the category error.

On a fresh Ubuntu 24.04 box this is the failure this install is famous for: compose that looks ready, a healthy FrankenPHP, and a public URL that is still loopback.

 plMail install path with the public URL and /install traps

Caption: Pin 0.4.3, bind 8080 to loopback, SERVER_NAME=:80. The red branches are APP_PUBLIC_URL left on localhost and /install still open. The yellow branch is a buffering proxy on /.well-known/mercure so the list never live-updates.

The working install

Official Docker shape for plMail 0.4.3, then Caddy. I followed upstream for image names, volumes, and the secrets-init service, then pinned the tag, bound HTTP to loopback, set SERVER_NAME=:80, and wrote APP_PUBLIC_URL into the environment the stock file does not pass. If docker compose version fails after the Engine install, I stop.

1. Install Docker Engine

sudo apt-get update -qqy
sudo apt-get install ca-certificates curl -qqy
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update -qqy
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin -qqy

sudo usermod -aG docker "$USER"
newgrp docker

docker --version
docker compose version

If docker compose version fails, I fix Docker before I write YAML. I log out and back in (or newgrp docker) so the socket group applies. Otherwise every compose command wants sudo and I end up with root-owned files under /opt/plmail.

2. Fetch the official compose file and pin 0.4.3

The clone is for compose.yaml and nothing else. Application code lives in the image. Official getting-it block is a git clone. I pin the tag so Tuesday's :latest is not what I run.

sudo mkdir -p /opt
sudo git clone --depth 1 --branch v0.4.3 https://github.com/karatektus/pl_mail.git /opt/plmail
sudo chown -R "$USER":"$USER" /opt/plmail
cd /opt/plmail

If I would rather not clone, copying compose.yaml from that tag is enough, as long as a .env sits beside it. I do not add -f compose.dev.yaml. That file switches every service to a locally built image with the source bind-mounted.

cd /opt/plmail
sed -i 's|ghcr.io/karatektus/pl_mail:latest|ghcr.io/karatektus/pl_mail:0.4.3|' compose.yaml

Stock x-app-env does not list APP_PUBLIC_URL or TRUSTED_PROXIES. A value in .env only reaches the container if compose maps it. I add both under x-app-env so the worker that registers push actually sees the hostname. Then I replace the php ports block so 443 is not published at all.

# add inside x-app-env:
APP_PUBLIC_URL: ${APP_PUBLIC_URL:-}
TRUSTED_PROXIES: ${TRUSTED_PROXIES:-127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16}

php ports — this is the bind I actually want, not the stock 80/443/udp:

    ports:
      - "127.0.0.1:8080:80"

php SERVER_NAME is already ${SERVER_NAME:-localhost, :443}, php:80. A .env of SERVER_NAME=:80 becomes :80, php:80, which is the reverse-proxy shape.

SERVER_NAME=:80
APP_PUBLIC_URL=https://mail.example.com
TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
cd /opt/plmail
cat > .env << 'EOF'
SERVER_NAME=:80
APP_PUBLIC_URL=https://mail.example.com
TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
EOF
chmod 600 .env compose.yaml

I replace mail.example.com with the hostname DNS already points at. No trailing slash. No path. Official reverse-proxy page: a trailing path ends up in the middle of a callback URL the provider will register and never successfully call. I do not put APP_SECRET or APP_ENCRYPTION_KEY in this file. Empty values let secrets-init mint them into the volume. A value in .env becomes a real environment variable and switches generation off for that key.

Do not add a compose.override.yaml by accident. Official “things that bite”: docker compose up picks one up whether I meant it or not. plMail does not ship one. If one exists, I put it there.

cd /opt/plmail
docker compose pull
docker compose up -d --wait
docker compose ps
docker compose logs --tail=80 php
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/healthz
ss -tlnp | grep -E ':8080|:80|:443|:5432'

8080 should be 127.0.0.1. 5432 should be absent from the host. /healthz should be 200. First boot is the slow one: secrets-init writes generated.env and postgres_password, Postgres becomes healthy, every app container runs app:db:migrate under an advisory lock, then Caddy serves. If I read the logs of a worker that lost the lock, I will debug “another container is running migrations” as a failure. It is not. I look at php.

3. Create the first administrator before the hostname is a target

I do not open /install from the public IPv4. Console from the php container is the same form, without a race:

cd /opt/plmail
docker compose exec php php bin/console app:setup

Name, address, password, public URL. The public URL I type is https://mail.example.com, not https://localhost, not http://127.0.0.1:8080. Saving it writes APP_PUBLIC_URL into var/secrets/generated.env and asks every worker to restart. An APP_PUBLIC_URL already in the environment wins over what the screen stored, which is what I want.

If I prefer the browser, I tunnel first:

ssh -L 8080:127.0.0.1:8080 user@your-vps

Then I still type the public https origin into the form, not the tunnel URL. After a user exists, /install 404s for good.

4. Put Caddy in front, leave Mercure unbuffered

Confirm DNS before the first TLS start. Create a Caddyfile. Caddy sets X-Forwarded-* on its own and does not buffer SSE.

mail.example.com {
    reverse_proxy 127.0.0.1:8080
}
sudo systemctl reload caddy

Nginx instead of Caddy needs the forwarded headers spelled out, and it needs one more thing. plMail serves two long-lived streams. Mercure is Server-Sent Events. A buffering proxy holds the events. The assistant's summary endpoints send nothing at all while the model reads a thread, and nginx's default read timeout is 60 seconds.

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    client_max_body_size 60m;
}

location /.well-known/mercure {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 24h;
}

location ~ ^/mail/(thread/\d+/summary|compose-assist) {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 20m;
}

The failure mode on Mercure is an app that works perfectly except that nothing ever updates on its own. No error. The topbar connection indicator stays wrong. Experience notes: proxy_buffering off on /.well-known/mercure or the UI never live-updates.

TRUSTED_PROXIES too narrow and Symfony believes it is serving plain HTTP. OAuth redirect URIs come out as http://…/oauth/google/callback. Cookies lose secure. Login throttling counts everyone as the proxy. I wasted a first hour on “the Google console has the wrong URI.” The URI had http:// because the proxy was not trusted. The committed default covers loopback and RFC1918, which is right for Caddy on the same Docker host. I still set it so I can see it in .env.

After the cert lands I open https://mail.example.com, log in, log out, log in. Admin → Address should show the public origin. Then Settings → Mail accounts, add one IMAP mailbox. Gmail and Outlook need OAuth credentials in Admin → Integrations first. I do not start there on day one. IMAP is the proof the stack decrypts a stored password.

docker compose exec php php bin/console app:mail:test-connection

Useful to know

:latest on GHCR is 0.4.3 as of this draft. I still pin 0.4.3. Tuesday should not migrate my schema because I was lazy with a tag. Migrations run on every boot. Rolling back an image does not roll the schema back.

secrets-init must stay in front of Postgres. Postgres reads POSTGRES_PASSWORD_FILE when the container is created. Every app service must mount app_secrets. A service missing that mount mints its own APP_ENCRYPTION_KEY and cannot read what the others wrote. EncryptionKeyProbe refuses to start rather than save accounts nothing else can decrypt.

Stock compose now declares app_attachments, app_raw, and app_uploads. Older files did not. Attachments the ingest worker wrote were invisible to the web container, and both copies died on the next recreate. Mail synced. The list rendered. The download 404'd. If I copied a compose file from before that fix, I read CHANGELOG.md before I mount empty volumes over directories that already hold files.

Console commands go through docker compose exec php. config/bootstrap_generated_secrets.php loads generated.env for that case. docker run against the image on its own cannot see the secrets.

Optional Android push without Google is docker compose --profile push up -d. That starts ntfy on ${NTFY_PORT:-8090}. I do not publish 8090 on a public VPS.

Authentik is already a post if I want OIDC later. Vaultwarden is the password vault. This is the inbox, not a mail server.

Backup, expose, next step

A plMail install is three things. A backup that has two of them restores nothing useful. Official backup page: the database, APP_ENCRYPTION_KEY in generated.env, and the blobs under attachments/, raw/, and uploads/. Lose the key and every mailbox password in the dump is ciphertext. Lose the blobs and every attachment 404s. caddy_data and mercure_data can be recreated.

app:backup writes database.sql, the three blob trees, and secrets.env. It is not on the maintenance schedule on purpose. A backup that only lives next to the volume is a snapshot, not an offsite copy. Default destination is var/backups/ inside the project directory, which on Docker is not a named volume. I bind a host folder before I trust the command.

cd /opt/plmail
mkdir -p backups
chmod 700 backups

Add this volume on the php service, then recreate:

      - ./backups:/app/var/backups
cat > /opt/plmail/backup.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
PROJECT="/opt/plmail"
BACKUP_DIR="$PROJECT/backups"
RETENTION_DAYS=14
mkdir -p "$BACKUP_DIR"
stamp="$(date -u +%Y%m%dT%H%M%SZ)"
cd "$PROJECT"
docker compose exec -T php php bin/console app:backup "/app/var/backups/plmail-${stamp}"
mkdir -p "$BACKUP_DIR/plmail-config-${stamp}"
cp -a compose.yaml .env "$BACKUP_DIR/plmail-config-${stamp}/"
[ -f Caddyfile ] && cp -a Caddyfile "$BACKUP_DIR/plmail-config-${stamp}/"
# Move the key off the same tree as database.sql.
if [ -f "$BACKUP_DIR/plmail-${stamp}/secrets.env" ]; then
  mkdir -p "$BACKUP_DIR/secrets"
  mv "$BACKUP_DIR/plmail-${stamp}/secrets.env" "$BACKUP_DIR/secrets/secrets-${stamp}.env"
  chmod 600 "$BACKUP_DIR/secrets/secrets-${stamp}.env"
fi
find "$BACKUP_DIR" -mindepth 1 -maxdepth 1 -name 'plmail-*' -mtime +"$RETENTION_DAYS" -exec rm -rf {} +
echo "[$stamp] backup under $BACKUP_DIR — secrets.env is not next to database.sql"
EOF
chmod 700 /opt/plmail/backup.sh
/opt/plmail/backup.sh
rsync -avz /opt/plmail/backups/plmail-*/ backup-user@backup.example.net:/srv/backups/plmail/data/
rsync -avz /opt/plmail/backups/secrets/ backup-user@backup.example.net:/srv/backups/plmail/secrets/

The command finishes by saying the key is in secrets.env and I should move it somewhere the dump is not. I treat that as the actual last step, not a log line.

 Three pieces of a plMail backup

Caption: Postgres holds the mail. generated.env holds APP_ENCRYPTION_KEY. Named volumes hold attachments. A dump without the key restores mailboxes nobody can decrypt. I keep secrets.env off the same disk as database.sql.

Restore on a spare VM: compose file in place, do not start the stack until secrets.env is back as generated.env on app_secrets. Official order: restore the secrets volume, up -d database, psql the dump, copy blobs, then up -d. An install that already minted its own key refuses to boot against a restored database with “APP_ENCRYPTION_KEY cannot decrypt the credentials already stored.” That message means the dump worked and the key did not come with it. Putting the original key back is the only recovery. POSTGRES_PASSWORD cannot be rotated by restoring a different secrets file — Postgres kept the old one at init.

Upgrades after a backup:

cd /opt/plmail
/opt/plmail/backup.sh
# Edit the image tag in compose.yaml, then:
docker compose pull
docker compose up -d --wait
docker compose logs --tail=80 php
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/healthz

If I floated :latest and a Tuesday image moves 0.4 to 0.5 under the same word, I want the dump from five minutes earlier. Pinning 0.4.3 makes that Tuesday quieter. Read the changelog. Migrations only go forward.

What I have running now, on paper for this lab, is plMail 0.4.3 on loopback 8080, Caddy on 443 for https://mail.example.com, SERVER_NAME=:80, APP_PUBLIC_URL set to that origin, Postgres 18 on a named volume, worker with Mercure on the Compose network, /install already closed, and a backup script that splits secrets.env from database.sql. Next I add one real IMAP mailbox, I watch Admin for worker heartbeats through a first sync so I know 4 GB was the right floor, I keep 8080 off ss on 0.0.0.0, and I leave Gmail OAuth, ntfy, and the language model until the restore is boring. This is still a client. Port 25 stays closed.

Did you hit the same wall?

I got stuck on the setup screen accepting https://localhost as APP_PUBLIC_URL while the hostname I actually open was https://mail.example.com — Google and Microsoft never called back. Did you hit the same thing, or a different one — Caddy in the container 301-looping because SERVER_NAME was still :443, /install still open on a public port, Mercure dead behind a buffering proxy, a 1 GB VPS OOMing on the first mailbox sync? Tell me in the comments. I read them.

Need this done on your server?

I deploy and harden Laravel/CodeCanyon apps on cPanel or VPS, and offer monthly Server Watch retainers. Hire for deploy · Care plan

References

Share:

Get new posts in your inbox

No spam. One short email per new article — practical PHP, Laravel, devops, and AI-assisted workflows.

Comments

Powered by GitHub Discussions via Giscus. A free GitHub account is required.