Skip to main content

Quick Start

Mailez is a self-hosted email solution: one command deploys a complete mail system — sending and receiving, spam filtering, authentication, an admin console, Webmail and mobile sync, all delivered as one integrated product. Every tier (dev / community / enterprise) runs the same in-house Mailezine single-binary engine; editions differ only in storage scale and licensed features.

Prerequisites​

  • Docker (Compose v2)
  • Go toolchain (1.26+), only needed when building images from source

The steps above are enough for trying it locally. For going live on the public internet — server sizing, open ports and domain DNS (MX / SPF / DKIM / DMARC, etc.) — see Production Deployment.

Quick Deployment (Community)​

1. Get the release package or the source​

Release package (recommended): download mailez-<version>.tar.gz from the release channel, extract it and run the interactive installer, which handles preflight checks, key generation and port configuration automatically:

tar xzf mailez-<version>.tar.gz && cd mailez-<version>
./install.sh

To deploy from source: clone the repository and continue with the next two steps.

2. Configure environment variables​

cd deploy
cp mailez.env.example mailez.env

Edit mailez.env and set the key settings:

  • MAILEZ_SECRET_KEY — secret used for encryption
  • MAILEZ_STACK_SECRET — shared secret between the control plane and the engine
  • MAILEZ_DOMAIN — your mail domain
  • MAILEZ_HOSTNAMES — mail server hostname

3. One command to start​

All deployment tiers are managed through the single mailezctl entry point:

./deploy/mailezctl.sh up ce   # community edition (production tier)

Production tiers pull prebuilt images by default (MAILEZ_REGISTRY / MAILEZ_IMAGE_TAG select the registry and version); to build from local source, every tier ships a build overlay (MAILEZ_LOCAL_BUILD=1 makes mailezctl run up -d --build with local tags automatically).

Community = the Mailezine engine + SQLite (control plane, MySQL/PostgreSQL optional) + Pebble KV + local-FS blobs: the complete mail platform on a single node — built for Linux servers and existing Docker environments.

Enterprise Edition​

The enterprise edition runs the same Mailezine engine and upgrades the storage to distributed form: MySQL (control plane) + TiDB (engine KV) + MinIO/S3 (message blobs). Stack tiers are layered through the same entry point:

./deploy/mailezctl.sh up ee     # distributed storage (production tier)
./deploy/mailezctl.sh up ha     # enterprise + control-plane replicas
./deploy/mailezctl.sh up multi  # enterprise + fully multi-active engine

Development Mode​

Run the backend on the host with SQLite + Pebble + local FS and orchestrate only the mail-stack dependencies:

./deploy/mailezctl.sh up        # dev tier

Verify the Deployment​

Once the system is up, create the admin account (default admin@example.com / MailezDemo2026!; override with MAILEZ_ADMIN_EMAIL / MAILEZ_ADMIN_PASSWORD before seeding):

docker compose --env-file deploy/mailez.env -f deploy/docker-compose.ce.yml \
  exec backend mailez-seed

When developing from source you can also run go run ./cmd/seed (creates the admin account) and go run ./cmd/e2e (end-to-end check of delivery, DKIM and spam filtering) on the host.

Access the Services​

PortService
http://localhost:8082Admin console
http://localhost:8083Webmail
http://localhost:8081Backend API (for developers)
25/465/587/110/995/143/993/4190Mail protocols (SMTP / POP3 / IMAP / ManageSieve, with implicit TLS)

TLS is off by default for local testing. For production, follow deploy/certs/README.md to enable automated certificates.

Next Steps​