For MailRules v0.3.0View this page on GitHub
Install
Run MailRules with Docker, Docker Compose, Homebrew, a release binary or a systemd service, and upgrade it later.
MailRules is one program, mailrules, with the web UI built in. Every release is published three ways:
- a Docker image,
ghcr.io/turtlebyte-in/mailrules, for amd64 and arm64, tagged with the version (for example0.1.0, without thev) andlatest; - archives for Linux and macOS on amd64 and arm64, with a
checksums.txt, on the Releases page; - a Homebrew cask in the tap TurtleByte-IN/homebrew-tap, for macOS and Linux.
Pick one of the methods below. Whichever you choose, MailRules listens on 127.0.0.1:8080, so open http://127.0.0.1:8080 on the same machine to continue with First run.
Docker
docker run -d --name mailrules --restart unless-stopped \
--read-only --tmpfs /tmp -p 127.0.0.1:8080:8080 \
-e MAILRULES_COOKIE_SECURE=false -v mailrules-data:/data \
ghcr.io/turtlebyte-in/mailrules:0.1.0
- The image is distroless and runs as a non-root user (uid 65532). Its root filesystem can be read-only: everything MailRules writes goes to
/data, here the volumemailrules-data. - Inside the container the daemon listens on every interface, and
-p 127.0.0.1:8080:8080publishes the port to this machine only. MAILRULES_COOKIE_SECURE=falselets you stay signed in over plain HTTP athttp://127.0.0.1:8080. Change it totrueonce a TLS reverse proxy is in front; see Security.- Pass other settings with more
-e NAME=valueoptions, or with--env-file. All of them are in the settings reference. Model keys can also be entered in the browser instead. - Proton Mail does not work from Docker. Proton Mail Bridge listens on the machine’s own address,
127.0.0.1, and inside a container that address is the container itself, so MailRules cannot reach Bridge there. The same holds for Docker Compose. To sort Proton Mail, use the Homebrew or single binary install on the machine Bridge runs on; see Proton Mail.
The image has no shell. To run a mailrules command against the running container, use docker exec:
docker exec mailrules /mailrules dry-run
Docker Compose
The compose file is deploy/docker-compose.yml in the repository, so you need a checkout:
git clone https://github.com/TurtleByte-IN/mailrules.git
cd mailrules
To run the published image, put this line in deploy/.env and start it:
MAILRULES_IMAGE=ghcr.io/turtlebyte-in/mailrules:0.1.0
docker compose -f deploy/docker-compose.yml up -d
To build the image from the checkout instead, leave MAILRULES_IMAGE unset and add --build. Pass VERSION so the build reports the release it was made from (for example 0.1.1) rather than dev:
VERSION=$(make -s version) docker compose -f deploy/docker-compose.yml up -d --build
What the compose file sets up:
- The port is published to
127.0.0.1only. If port 8080 is taken, putMAILRULES_PORT=8090(or any free port) indeploy/.env. - Data lives in the
mailrules-datavolume. - The container runs with a read-only root filesystem, no capabilities and
no-new-privileges. MAILRULES_COOKIE_SECUREdefaults tofalse, for the same reason as withdocker run. Set it totrueindeploy/.envonce a TLS reverse proxy is in front.- As with
docker run, MailRules in the container cannot reach Proton Mail Bridge on this machine (see Docker).
Put your settings in deploy/.env, never in the compose file itself. Compose passes on only the variables listed in the environment: section of deploy/docker-compose.yml. That is every setting in the settings reference except MAILRULES_LISTEN: inside the container MailRules must listen on 0.0.0.0:8080 for the published port to work, so change the port on your machine with MAILRULES_PORT instead.
The _FILE settings (MAILRULES_MASTER_KEY_FILE, MAILRULES_SMTP_PASSWORD_FILE) name a path inside the container, which has a read-only filesystem, so mount the file there first or MailRules will not start. The compose file has a commented secrets: example that mounts a key file at /run/secrets/master_key.
Run commands with exec:
docker compose -f deploy/docker-compose.yml exec mailrules /mailrules dry-run
Homebrew (macOS and Linux)
brew install --cask turtlebyte-in/tap/mailrules
mailrules serve
The release binaries are not signed or notarized by Apple. The cask removes the macOS quarantine attribute when it installs, so macOS opens the binary without a prompt.
mailrules serve runs in the foreground; stop it with Ctrl-C. It keeps its data in ./data, relative to the directory you start it from, so start it from the same directory every time, or set a fixed data directory (see Choosing a data directory):
MAILRULES_DATA_DIR="$HOME/.local/share/mailrules" mailrules serve
Homebrew does not set MailRules up as a background service. Run it in a terminal, or under a service manager of your choice.
Single binary
Download the archive for your system and checksums.txt from the Releases page. Archives are named mailrules_<version>_<os>_<arch>.tar.gz, where <os> is linux or darwin (macOS) and <arch> is amd64 or arm64. For example, on Linux on amd64:
curl -LO https://github.com/TurtleByte-IN/mailrules/releases/download/v0.1.0/mailrules_0.1.0_linux_amd64.tar.gz
curl -LO https://github.com/TurtleByte-IN/mailrules/releases/download/v0.1.0/checksums.txt
sha256sum --ignore-missing -c checksums.txt
tar xzf mailrules_0.1.0_linux_amd64.tar.gz
./mailrules serve
On macOS, check the archive with shasum -a 256 --ignore-missing -c checksums.txt instead. The check must print OK for the archive you downloaded; if it does not, do not run the binary.
The archive holds the mailrules binary with the web UI built in, LICENSE, README.md and the systemd unit deploy/mailrules.service.
On macOS, a binary downloaded with a browser is quarantined, and macOS refuses to open it because it is not signed. Remove the quarantine attribute:
xattr -d com.apple.quarantine mailrules
As with Homebrew, the data directory is ./data unless you set MAILRULES_DATA_DIR. mailrules version prints the version.
Build from source
You need Go 1.27 or newer and Node.js 24 (for the web UI).
git clone https://github.com/TurtleByte-IN/mailrules.git
cd mailrules
make build
./bin/mailrules serve
make build builds the web UI and embeds it in bin/mailrules.
Run as a systemd service (Linux)
deploy/mailrules.service is a hardened systemd unit. It runs MailRules as its own system user, keeps its data in /var/lib/mailrules, and listens on 127.0.0.1:8080. From an unpacked release archive:
sudo useradd --system --home-dir /var/lib/mailrules --shell /usr/sbin/nologin mailrules
sudo install -m 0755 mailrules /usr/local/bin/mailrules
sudo install -m 0644 deploy/mailrules.service /etc/systemd/system/mailrules.service
sudo systemctl daemon-reload && sudo systemctl enable --now mailrules
From a source checkout, install bin/mailrules instead of mailrules.
Put settings in /etc/mailrules/env, one NAME=value per line, owned by root with mode 0600, then sudo systemctl restart mailrules. The logs are in the journal: journalctl -u mailrules.
To run a mailrules command against the service’s data, run it as the service user with the same data directory:
sudo -u mailrules MAILRULES_DATA_DIR=/var/lib/mailrules /usr/local/bin/mailrules dry-run
If /etc/mailrules/env sets MAILRULES_MASTER_KEY_FILE, pass that too to commands that read stored passwords, such as mailrules accounts test.
The service is reachable from the server itself only. To open the UI from your own computer, use an SSH tunnel (ssh -L 8080:127.0.0.1:8080 your-server, then open http://127.0.0.1:8080), or put a reverse proxy with TLS in front as described in Security.
Choosing a data directory
The data directory holds the database and the master key that encrypts your mailbox passwords and model keys. See Backup and the master key for what is in it.
| How you run it | Data directory |
|---|---|
| Docker and Docker Compose | /data in the container, the mailrules-data volume |
| systemd unit | /var/lib/mailrules |
| Homebrew, release binary, source build | ./data, relative to the directory you start it from |
Set MAILRULES_DATA_DIR (or --data-dir) to choose another one. Use an absolute path when you run the binary yourself, so it does not depend on the directory you start from. The directory is created with mode 0700 if it does not exist. Keep it on a local disk: the database is SQLite in WAL mode, which does not work reliably on network file systems.
The Settings screen shows the data directory in use, in the Self-hosting card.
The hosted build’s database (Postgres)
Self-hosting keeps the SQLite database in the data directory and needs none of this. The hosted service keeps every team in one Postgres database (16 or later) instead, with row-level security: each query runs for one team, and the database itself returns no other team’s rows. It uses three logins, so that the program serving the web app owns no table and cannot change the schema:
| Login | Member of | Used by |
|---|---|---|
| the owner | none; it needs CREATEROLE |
mailrules migrate only. It owns the tables and creates the group roles mailrules_app, mailrules_worker and mailrules_definer the first time. |
| the app login | mailrules_app |
mailrules serve, through MAILRULES_DATABASE_URL |
| the worker login | mailrules_worker |
the mailbox workers in mailrules serve, through MAILRULES_WORKER_DATABASE_URL. It cannot read password hashes or sessions. Leave the URL empty to use the app login. |
Set it up once, as a database superuser:
CREATE ROLE mailrules_owner LOGIN CREATEROLE PASSWORD '…';
CREATE DATABASE mailrules OWNER mailrules_owner;
Then create the schema as the owner, and the two logins once the group roles exist:
MAILRULES_MIGRATE_DATABASE_URL='postgres://mailrules_owner:…@db:5432/mailrules?sslmode=require' mailrules migrate
CREATE ROLE mailrules_web LOGIN PASSWORD '…' IN ROLE mailrules_app;
CREATE ROLE mailrules_mailboxes LOGIN PASSWORD '…' IN ROLE mailrules_worker;
Start mailrules serve with MAILRULES_DATABASE_URL and MAILRULES_WORKER_DATABASE_URL set to those two logins, and the master key in MAILRULES_MASTER_KEY, the same for every copy of the program, so that no copy generates a key of its own. On an upgrade, run mailrules migrate with the new version before starting it: on Postgres, mailrules serve never changes the schema, and it stops with a message while the schema is not the one it was built for. See Settings for the three variables.
Upgrading
MailRules updates its database by itself the first time a new version starts, so upgrading is: back up, replace the program, restart. Back up the data directory first (see Backup and the master key); MailRules has no command to undo a database update, so the backup is how you would go back to the older version.
Docker. Pull the new tag, then remove and recreate the container with the same volume:
docker pull ghcr.io/turtlebyte-in/mailrules:<new-version>
docker stop mailrules && docker rm mailrules
# then the same docker run command as before, with the new tag
Docker Compose with the published image. Change the tag in MAILRULES_IMAGE in deploy/.env (or keep latest), then:
docker compose -f deploy/docker-compose.yml pull
docker compose -f deploy/docker-compose.yml up -d
Docker Compose from a checkout. Update the checkout and rebuild:
git pull
VERSION=$(make -s version) docker compose -f deploy/docker-compose.yml up -d --build
Homebrew.
brew upgrade --cask mailrules
Then stop mailrules serve and start it again.
Release binary. Download and check the new archive as above, replace the old mailrules binary, and restart it.
systemd. Download and check the new archive, then:
sudo install -m 0755 mailrules /usr/local/bin/mailrules
sudo systemctl restart mailrules
If a new release changes deploy/mailrules.service, install the new unit as well and run sudo systemctl daemon-reload before the restart.