diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst index f31d2da6..2553eff1 100644 --- a/doc/source/getting_started.rst +++ b/doc/source/getting_started.rst @@ -16,15 +16,16 @@ 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. +- A Debian 12 **deployment 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 +- A Linux or Unix **build machine** with key-based SSH access to the root + user of the deployment server. + 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 `_) @@ -34,7 +35,8 @@ Setup with ``scripts/cmdeploy`` We use ``chat.example.org`` as the chatmail domain in the following steps. Please substitute it with your own domain. -1. Setup the initial DNS records. The following is an example in the +1. Setup the initial DNS records for your deployment server. + 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. @@ -54,20 +56,20 @@ steps. Please substitute it with your own domain. cd relay scripts/initenv.sh -3. On your local PC, create chatmail configuration file +3. On your local build machine (PC), create a chatmail configuration file ``chatmail.ini``: :: scripts/cmdeploy init chat.example.org # <-- use your domain -4. Verify that SSH root login to your remote server works: +4. Verify that SSH root login to the deployment server server works: :: ssh root@chat.example.org # <-- use your domain -5. From your local PC, deploy the remote chatmail relay server: +5. From your local build machine, setup and configure the remote deployment server: :: @@ -81,7 +83,7 @@ steps. Please substitute it with your own domain. Other helpful commands ---------------------- -To check the status of your remotely running chatmail service: +To check the status of your deployment server running the chatmail service: :: @@ -158,7 +160,7 @@ Disable automatic address creation -------------------------------------------------------- If you need to stop address creation, e.g. because some script is wildly -creating addresses, login with ssh and run: +creating addresses, login with ssh to the deployment machine and run: :: @@ -166,11 +168,12 @@ creating addresses, login with ssh and run: Chatmail address creation will be denied while this file is present. -Migrating to a new deployment machine + +Migrating to a new build machine ---------------------------------- -To move or add a deployment machine, keep a copy of a working ``chatmail.ini``, -clone the relay repo on the new machine, and recreate ``chatmail.ini`` there. +To move or add a build machine, +clone the relay repository on the new build machine, and copy the ``chatmail.ini`` file from the old build machine. Make sure ``rsync`` is installed, then initialize the environment: :: @@ -184,5 +187,5 @@ Run safety checks before a new deployment: ./scripts/cmdeploy dns ./scripts/cmdeploy status -If you keep multiple deployment machines (ie laptop and desktop), keep ``chatmail.ini`` in sync between +If you keep multiple build machines (ie laptop and desktop), keep ``chatmail.ini`` in sync between them.