Deploy an outpost

Run the outpost on your server or NAS to receive notifications from selected email folders. You need Docker, plus Docker Compose v2 for the recommended Compose installation.

Image availability: available versions are listed in GitHub Releases and GHCR.

1. Choose an installation method

Docker Compose is recommended: installation, updates and backups use the same configuration. The image is ghcr.io/mingzaily/mailwake:latest, for Linux amd64 / arm64. latest follows the stable release. To pin a version, replace latest with a published tag from Releases.

In your server terminal:

mkdir -p ~/mailwake
cd ~/mailwake

Create compose.yaml in that directory with this complete configuration:

services:
  core:
    image: ghcr.io/mingzaily/mailwake:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      MAILWAKE_LISTEN: "0.0.0.0:8080"
      MAILWAKE_DATA_DIR: "/data"
      MAILWAKE_RELAY_URL: "${MAILWAKE_RELAY_URL:-}"
    volumes:
      - core-data:/data
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
volumes:
  core-data:

Pull the image and start the outpost:

docker compose pull core
docker compose up -d
docker compose ps
docker compose logs --tail=50 core

Check the result: core shows Up / running, and the logs contain the initial setup code. Keep the terminal available for the next step. Run future Compose commands from ~/mailwake.

The core-data Docker volume stores /data. With this directory name, its default Docker name is mailwake_core-data. Recreating the container preserves it; docker compose down -v deletes the volume and its contents.

Docker Run

Choose this equivalent installation if you prefer a single command. Use one installation method for your instance.

docker volume create mailwake-data
docker run -d \
  --name mailwake \
  --restart unless-stopped \
  --stop-timeout 30 \
  --read-only \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  -p 127.0.0.1:8080:8080 \
  -v mailwake-data:/data \
  ghcr.io/mingzaily/mailwake:latest
docker logs --tail=50 mailwake

This installation uses the mailwake-data volume. The following management commands use Compose; see the Docker Run backup instructions for the alternative.

2. Open the console

On the Docker host: open http://127.0.0.1:8080.

On a remote server or NAS: run this command on your own computer, replacing user@server with your server's SSH user and address:

ssh -L 18080:127.0.0.1:8080 user@server

Keep the connection open and visit http://127.0.0.1:18080 on your computer. This is enough to complete initial setup. Configure HTTPS below when you want ongoing access through a domain.

Check the result: the Mailwake setup screen opens. Enter the setup code from the logs and create an administrator password of at least 12 characters. Restarting the outpost before setup generates a new setup code.

Continue with your first notification to connect a mailbox and a notification channel.

3. Configure HTTPS

Point your domain to the server and configure your reverse proxy to forward to http://127.0.0.1:8080. For Caddy installed on the same host, add your domain to Caddyfile:

mail.example.org {
    reverse_proxy 127.0.0.1:8080
}

Verify DNS and allow inbound ports 80 / 443, then validate and reload:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Open https://mail.example.org, confirm the certificate is valid, and check that you can sign in and open a mailbox. See the official Caddy installation guide to install Caddy. In a proxy panel such as Nginx Proxy Manager, enter the domain and forwarding address and request a certificate in the panel.

For a proxy in another container, join it to the outpost's Docker network and forward to http://core:8080; its 127.0.0.1 refers to itself. Preserve the original Host and set X-Forwarded-For. The outpost accepts proxy information from loopback and private networks; expose port 8080 only to the proxy and trusted local clients.

4. Update the outpost

Complete a backup, then run in the Compose directory:

docker compose pull core
docker compose up -d
docker compose ps
docker compose logs --tail=50 core

For a pinned version, change the image tag in compose.yaml first. Open the console, check mailbox monitoring, and send a new email to verify delivery. Keep the pre-update backup. To roll back, restore both its data and its matching image using the restore tutorial.

5. Troubleshooting

The image cannot be pulled

Check whether GHCR contains the requested version. manifest unknown usually means a missing tag. Check the image address and package visibility for denied errors, or server connectivity to GHCR for timeouts.

The console will not open

127.0.0.1 refers to the computer you are using. Use the SSH tunnel or an HTTPS domain for a remote installation. Check docker compose ps and docker compose logs --tail=50 core first. If 8080 is occupied, change the mapping to 127.0.0.1:18080:8080 and use host port 18080 in the browser and reverse proxy.

Reset an administrator password

Run in the Compose directory and enter the new password at the terminal prompt:

docker compose stop core
docker compose run --rm -it core admin reset-password
docker compose start core

The recovery command acquires the data directory lock, so stop the outpost first. Resetting the password revokes browser sessions and preserves API tokens, mailboxes and the queue.

Connect the official App and Pro

The Free Web console and Bark / Pushover / Webhook delivery work independently. For the official App, follow App integration for HTTPS and pairing.

Source builds and local development are covered in the development guide.

Source builds and process settings

For development builds, follow the source repository README and contributor build guide.

MAILWAKE_LISTEN defaults to 127.0.0.1:8080 outside Docker; the container uses 0.0.0.0:8080. MAILWAKE_DATA_DIR defaults to data; the container uses /data. MAILWAKE_RELAY_URL defaults to https://notify.mailwake.oritx.com. Keep the complete data directory, including secret.key, across restarts and upgrades.

Change the push delivery environment

Production and Sandbox use separate pairing identities. To intentionally change environments, stop the outpost and run the reset against its existing data directory and saved address of the previous push delivery service:

docker compose stop core
docker compose run --rm -it core admin reset-native-push

Type reset-native-push when prompted. The command revokes pairings at the old push delivery service. If that service is unreachable, keep the old configuration and retry when it is reachable. After it confirms zero unresolved targets, set the new MAILWAKE_RELAY_URL, recreate the outpost with docker compose up -d, and pair again. The command preserves the outpost signing identity and ordinary-channel history.

Markdown · AGPL-3.0-only · Mailwake contributors