How to deploy a Chatmail server

Why run your own Chatmail relay?

Chatmail relays enable permission-free onboarding for chat applications and bots.
Users don’t need pre-created accounts — chatmail addresses are created automatically on first login and secured with a password for future use. Chatmail is end-to-end encrypted and encrypted at rest.

Running your own relay gives you:

Full control over identity infrastructure
Privacy-first onboarding
Independence from centralized providers
A lightweight system that scales to thousands of users on minimal hardware

This guide walks you through deploying a fully functional Chatmail relay using the official automated deployment scripts.

This article accompanies the video below. If you prefer watching the full deployment in real time, start there. If you want a precise written reference, keep reading.

⚠️ Important compatibility note ⚠️

This deployment requires Debian 12 on the server.

Debian 13 is not supported
Other Linux distributions may work, but require undocumented changes

If you use Debian 13 or another OS, expect additional steps to be needed that are not covered by this documentation.

Architecture overview

You will need two machines:

1. Deployment server

This becomes your Chatmail relay.

Debian 12
1 GB RAM
1 CPU
~10 GB storage
Public IPv4 (IPv6 strongly recommended)
Open ports:22, 25, 80, 443, 143, 465, 587, 993, 3478

2. Local computer

Used to deploy and manage the relay.

Linux or Unix-like OS
In this guide I use: Ubuntu 24.04

The deployment process runs from your local machine, not directly on the server.

Security note about SSH

The official deployment process assumes SSH access to the server as root. This is temporary.

Recommended options:

Restrict SSH to your IP
Deploy from the same LAN using local DNS
Disable root password login after setup (we do this at the end)

Local machine requirements

Install the required packages:

sudo apt install python3-dev sudo apt install python3.12-venv sudo apt install gcc

These are required to create the Python virtual environment used by the deployment scripts.

Preparing the Debian 12 server

If running in a VM, consider installing the qemu-guest-agent:

apt install qemu-guest-agent

Edit the SSH configuration:

nano /etc/ssh/sshd_config

Edit and set:

PermitRootLogin yes

Restart SSH:

systemctl restart ssh

This is temporary and will be reverted after deployment.

DNS setup (before deployment)

In this guide we use the following FQDN (Fully qualified domain):

chat.example.org

Replace this with your own domain. Then, create the following DNS records (TTL: 3600 seconds):

chat.example.org. 3600 IN A 198.51.100.5
chat.example.org. 3600 IN AAAA 2001:db8::5
www.chat.example.org. 3600 IN CNAME chat.example.org.
mta-sts.chat.example.org.3600 IN CNAME chat.example.org.

These must exist before running the deployment.

Cloning the Chatmail relay repository

On your local machine:

git clone https://github.com/chatmail/relay cd relay scripts/initenv.sh

This bootstraps the Python virtual environment.

Initial Chatmail configuration

Create the Chatmail configuration file:

scripts/cmdeploy init chat.example.org

This generates the chatmail.ini for your domain.

SSH key setup (mandatory)

The deployment process cannot prompt for passwords, so SSH key authentication is required.

1. Generate a dedicated key

ssh-keygen -t ed25519 -C "chatmail-deploy" -f ~/.ssh/id_ed25519_chatmail

2. Start an SSH agent and load the key

eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519_chatmail

3. Copy the key to the server

ssh-copy-id -i ~/.ssh/id_ed25519_chatmail root@chat.example.org

4. Verify access

ssh root@chat.example.org

You should connect without being prompted for a password.

Running the deployment

From your local machine:

scripts/cmdeploy run

This step installs and configures:

Mail services
TLS certificates
Chatmail logic
Required dependencies

Wait until the script completes.

Completing DNS configuration

After deployment, check which DNS records are still missing:

scripts/cmdeploy dns

Add the missing records to your DNS provider. Once DNS propagates, verify the system status:

scripts/cmdeploy status

Testing and benchmarking

Run a functional test:

scripts/cmdeploy test

Then measure performance:

scripts/cmdeploy bench

These confirm that authentication, mail flow, and system performance are all working correctly.

Locking SSH back down (important)

Disable root password login again on your Debian 12 server: