Getting started¶

Minimal requirements and prerequisites¶

You will need the following:

Control over a domain through a DNS provider of your choice.
A Debian 12 server with reachable SMTP/SUBMISSIONS/IMAPS/HTTPS ports. IPv6 is encouraged if available. Chatmail relay servers only require 1GB RAM, one CPU, and perhaps 10GB storage for a few thousand active chatmail addresses.
Key-based SSH authentication to the root user. You must add a passphrase-protected private key to your local ssh-agent because you can’t type in your passphrase during deployment. (An ed25519 private key is required due to an upstream bug in paramiko)

Setup with “script/cmdeploy”¶

We use chat.example.org as the chatmail domain in the following steps. Please substitute it with your own domain.

Setup the initial DNS records. The following is an example in the familiar BIND zone file format with a TTL of 1 hour (3600 seconds). Please substitute your domain and IP addresses.

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

On your local PC, clone the repository and bootstrap the Python virtualenv.

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

On your local PC, create chatmail configuration file chatmail.ini:

scripts/cmdeploy init chat.example.org  # <-- use your domain

Verify that SSH root login to your remote server works:
```
ssh root@chat.example.org  # <-- use your domain
```
From your local PC, deploy the remote chatmail relay server:
```
scripts/cmdeploy run
```
This script will also check that you have all necessary DNS records. If DNS records are missing, it will recommend which you should configure at your DNS provider (it can take some time until they are public).

Other helpful commands¶

To check the status of your remotely running chatmail service:

scripts/cmdeploy status

To display and check all recommended DNS records:

scripts/cmdeploy dns

To test whether your chatmail service is working correctly:

scripts/cmdeploy test

To measure the performance of your chatmail service:

scripts/cmdeploy bench

Modifying the home page¶

cmdeploy run also creates default static web pages and deploys them to a Nginx web server with:

a default index.html along with a QR code that users can click to create an address on your chatmail relay
a default info.html that is linked from the home page
a default policy.html that is linked from the home page

All .html files are generated by the according markdown .md file in the www/src directory.

Refining the web pages¶

scripts/cmdeploy webdev

This starts a local live development cycle for chatmail web pages:

uses the www/src/page-layout.html file for producing static HTML pages from www/src/*.md files
continously builds the web presence reading files from www/src directory and generating HTML files and copying assets to the www/build directory.
Starts a browser window automatically where you can “refresh” as needed.

Custom web pages¶

You can skip uploading a web page by setting www_folder=disabled in chatmail.ini.

If you want to manage your web pages outside this git repository, you can set www_folder in chatmail.ini to a custom directory on your computer. cmdeploy run will upload it as the server’s home page, and if it contains a src/index.md file, will build it with hugo.