mirror of
https://github.com/chatmail/relay.git
synced 2026-05-10 16:04:37 +00:00
docker: integrate documentation
delete original markdown notes (the russian version was severely outdated) and add a new section.
This commit is contained in:
j4n
262
doc/source/docker.rst
Normal file
262
doc/source/docker.rst
Normal file
@@ -0,0 +1,262 @@
|
||||
Docker installation
|
||||
===================
|
||||
|
||||
This section provides instructions for installing a chatmail relay
|
||||
using Docker Compose.
|
||||
|
||||
.. note::
|
||||
|
||||
Docker support is experimental and not yet covered by automated tests, please report bugs.
|
||||
|
||||
|
||||
Known limitations
|
||||
-----------------
|
||||
|
||||
- Requires cgroups v2 on the host. Operation with cgroups v1 has not been tested.
|
||||
- This preliminary image simply wraps the cmdeploy process detailed in the :doc:`getting_started` instructions in a full Debian-systemd image.
|
||||
- Currently, the image has only been tested and built on amd64, though arm64 should theoretically work as well.
|
||||
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
- **Docker Compose v2** (``docker compose``, not ``docker-compose``) is
|
||||
required for its ``cgroup: host`` support (`Install instructions <https://docs.docker.com/engine/install/debian/#install-using-the-repository>`_:)
|
||||
|
||||
- **DNS records** for your domain (see step 1 below).
|
||||
|
||||
- **Kernel parameters** — ``fs.inotify.max_user_instances`` and
|
||||
``fs.inotify.max_user_watches`` must be raised on the host because they
|
||||
cannot be changed inside the container (see step 2 below).
|
||||
|
||||
|
||||
Preliminary setup
|
||||
-----------------
|
||||
|
||||
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 familiar BIND zone file format with
|
||||
a TTL of 1 hour (3600 seconds).
|
||||
Please substitute your domain and IP addresses.
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
||||
2. Configure kernel parameters on the host, as these can not be set from the container::
|
||||
|
||||
echo "fs.inotify.max_user_instances=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
|
||||
echo "fs.inotify.max_user_watches=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
|
||||
sudo sysctl --system
|
||||
|
||||
|
||||
Docker Compose Setup
|
||||
--------------------
|
||||
|
||||
Pre-built images are available from GitHub Container Registry. The
|
||||
``main`` branch and tagged releases are pushed automatically by CI::
|
||||
|
||||
docker pull ghcr.io/chatmail/relay:main # latest main branch
|
||||
docker pull ghcr.io/chatmail/relay:1.2.3 # tagged release
|
||||
|
||||
|
||||
Create service directory
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Either:
|
||||
|
||||
- Create a service directory, e.g., `/srv/chatmail-relay`::
|
||||
|
||||
mkdir -p /srv/chatmail-relay && cd /srv/chatmail-relay
|
||||
wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker-compose.yaml https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker-compose.override.yaml.example
|
||||
wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker/env.example -O .env
|
||||
|
||||
|
||||
- or clone the chatmail repo ::
|
||||
|
||||
git clone https://github.com/chatmail/relay
|
||||
cd relay
|
||||
cp example.env .env
|
||||
|
||||
|
||||
|
||||
Customize and start
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. All local customizations (data paths, extra volumes, config mounts) go in
|
||||
``docker-compose.override.yaml``, which Compose merges automatically with
|
||||
the base file. By default, all data is stored in docker volumes, you will
|
||||
likely want to at least create and configure the mail storage location. Copy
|
||||
the example to get started::
|
||||
|
||||
cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
|
||||
# and edit docker-compose.override.yaml
|
||||
|
||||
|
||||
2. Configure the ``.env`` file. Only ``MAIL_DOMAIN`` is required, the domain
|
||||
name of the future server.
|
||||
|
||||
The container generates a ``chatmail.ini`` with defaults from
|
||||
``MAIL_DOMAIN`` on first start. To customize chatmail settings, mount
|
||||
your own ``chatmail.ini`` instead (see `Custom chatmail.ini`_ below).
|
||||
|
||||
3. Start the container::
|
||||
|
||||
docker compose up -d
|
||||
docker compose logs -f chatmail # view logs, Ctrl+C to exit
|
||||
|
||||
4. After installation is complete, open ``https://chat.example.org`` in
|
||||
your browser.
|
||||
|
||||
|
||||
Managing the server
|
||||
-------------------
|
||||
|
||||
Use ``docker exec`` to run cmdeploy commands inside the container::
|
||||
|
||||
# Show required DNS records
|
||||
docker exec chatmail /opt/cmdeploy/bin/cmdeploy dns --ssh-host @local
|
||||
|
||||
# Check server status
|
||||
docker exec chatmail /opt/cmdeploy/bin/cmdeploy status --ssh-host @local
|
||||
|
||||
# Run benchmarks (can also run from any machine with cmdeploy installed)
|
||||
docker exec chatmail /opt/cmdeploy/bin/cmdeploy bench chat.example.org
|
||||
|
||||
|
||||
Customization
|
||||
-------------
|
||||
|
||||
Custom website
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
You can customize the chatmail landing page by mounting a directory with
|
||||
your own website source files.
|
||||
|
||||
1. Create a directory with your custom website source::
|
||||
|
||||
mkdir -p ./custom/www/src
|
||||
nano ./custom/www/src/index.md
|
||||
|
||||
2. Add the volume mount in ``docker-compose.override.yaml``::
|
||||
|
||||
services:
|
||||
chatmail:
|
||||
volumes:
|
||||
- ./custom/www:/opt/chatmail-www
|
||||
|
||||
3. Restart the service::
|
||||
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
|
||||
|
||||
Custom chatmail.ini
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
There are two configuration modes:
|
||||
|
||||
**Simple (default):** Set ``MAIL_DOMAIN`` in ``.env``. The container
|
||||
auto-generates ``chatmail.ini`` with defaults on first start. This is
|
||||
sufficient for most deployments.
|
||||
|
||||
**Advanced:** Generate a ``chatmail.ini``, edit it, and mount it into
|
||||
the container. This gives you full control over all chatmail settings.
|
||||
|
||||
1. Extract the generated config from a running container::
|
||||
|
||||
docker cp chatmail:/etc/chatmail/chatmail.ini ./chatmail.ini
|
||||
|
||||
2. Edit ``chatmail.ini`` as needed.
|
||||
|
||||
3. Add the volume mount in ``docker-compose.override.yaml`` ::
|
||||
|
||||
services:
|
||||
chatmail:
|
||||
volumes:
|
||||
- ./chatmail.ini:/etc/chatmail/chatmail.ini
|
||||
|
||||
4. Restart the container, the container skips generating a new one: ::
|
||||
|
||||
docker compose down && docker compose up -d
|
||||
|
||||
|
||||
Migrating from a bare-metal install
|
||||
------------------------------------
|
||||
|
||||
If you have an existing bare-metal chatmail installation and want to
|
||||
switch to Docker:
|
||||
|
||||
1. Stop all existing services::
|
||||
|
||||
systemctl stop postfix dovecot doveauth nginx opendkim unbound \
|
||||
acmetool-redirector filtermail filtermail-incoming chatmail-turn \
|
||||
iroh-relay chatmail-metadata lastlogin mtail
|
||||
systemctl disable postfix dovecot doveauth nginx opendkim unbound \
|
||||
acmetool-redirector filtermail filtermail-incoming chatmail-turn \
|
||||
iroh-relay chatmail-metadata lastlogin mtail
|
||||
|
||||
2. Copy your existing ``chatmail.ini`` and mount it into the container
|
||||
(see `Custom chatmail.ini`_ above)::
|
||||
|
||||
cp /usr/local/lib/chatmaild/chatmail.ini ./chatmail.ini
|
||||
|
||||
3. Copy persistent data into the ``./data/`` subdirectories (for example, as configured in `Customize and start`_) ::
|
||||
|
||||
mkdir -p data/chatmail-dkimkeys data/chatmail-acme data/chatmail
|
||||
|
||||
# DKIM keys
|
||||
cp -a /etc/dkimkeys/* data/chatmail-dkimkeys/
|
||||
|
||||
# ACME certificates and account
|
||||
rsync -a /var/lib/acme/ data/chatmail-acme/
|
||||
|
||||
# Mail data
|
||||
rsync -a /home/ data/chatmail/
|
||||
|
||||
Alternatively, mount ``/home/vmail`` directly by changing the volume
|
||||
in ``docker-compose-override.yaml``::
|
||||
|
||||
- /home/vmail:/home/vmail
|
||||
|
||||
The three ``./data/`` subdirectories cover all persistent state.
|
||||
Everything else is regenerated by the ``configure`` and ``activate``
|
||||
stages on container start.
|
||||
|
||||
Building the image
|
||||
------------------
|
||||
|
||||
Clone the repository and build the Docker image::
|
||||
|
||||
git clone https://github.com/chatmail/relay
|
||||
cd relay
|
||||
docker compose build chatmail
|
||||
|
||||
The build bakes all binaries, Python packages, and the install stage
|
||||
into the image. After building, only ``docker-compose.yaml`` and ``.env``
|
||||
are needed to run the container.
|
||||
|
||||
You can transfer a locally built image to your server directly (pigz is parallel `gzip` which can be used instead as well) ::
|
||||
|
||||
docker save chatmail-relay:latest | pigz | ssh chat.example.org 'pigz -d | docker load'
|
||||
|
||||
|
||||
Forcing a full reinstall
|
||||
------------------------
|
||||
|
||||
On container start, only the ``configure`` and ``activate`` stages run by default.
|
||||
|
||||
To force a full reinstall (e.g. after updating the source), either
|
||||
rebuild the image::
|
||||
|
||||
docker compose build chatmail
|
||||
docker compose up -d
|
||||
|
||||
Or override the stages at runtime without rebuilding::
|
||||
|
||||
CMDEPLOY_STAGES="install,configure,activate" docker compose up -d
|
||||
@@ -83,9 +83,8 @@ steps. Please substitute it with your own domain.
|
||||
Docker installation
|
||||
-------------------
|
||||
|
||||
We have experimental support for `docker compose <https://github.com/chatmail/relay/blob/docker-rebase/docs/DOCKER_INSTALLATION_EN.md>`_,
|
||||
but it is not covered by automated tests yet,
|
||||
so don't expect everything to work.
|
||||
There is experimental support for running chatmail via Docker Compose.
|
||||
See :doc:`docker` for full setup instructions.
|
||||
|
||||
Other helpful commands
|
||||
----------------------
|
||||
|
||||
@@ -13,6 +13,7 @@ Contributions and feedback welcome through the https://github.com/chatmail/relay
|
||||
:maxdepth: 5
|
||||
|
||||
getting_started
|
||||
docker
|
||||
proxy
|
||||
migrate
|
||||
overview
|
||||
|
||||
@@ -1,231 +0,0 @@
|
||||
# Known issues and limitations
|
||||
|
||||
- Requires cgroups v2 configured in the system. Operation with cgroups v1 has not been tested.
|
||||
- Yes, of course, using systemd inside a container is a hack, and it would be better to split it into several services, but since this is an MVP, it turned out to be easier to do it this way initially than to rewrite the entire deployment system.
|
||||
- The Docker image is only suitable for amd64. If you need to run it on a different architecture, try modifying the Dockerfile (specifically the part responsible for installing dovecot).
|
||||
|
||||
# Docker installation
|
||||
This section provides instructions for installing Chatmail using Docker Compose.
|
||||
|
||||
**Note:** Docker Compose v2 is required (`docker compose`, not `docker-compose`) for its support of the `cgroup: host` option in `docker-compose.yaml` is only supported by Compose v2.
|
||||
[see documentation](https://docs.docker.com/engine/install/debian/#install-using-the-repository)
|
||||
```shell
|
||||
apt install docker-ce docker-compose-plugin docker.io- docker-compose-
|
||||
```
|
||||
|
||||
## Preliminary setup
|
||||
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 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.
|
||||
```
|
||||
|
||||
2. Configure kernel parameters because they cannot be changed inside the container, specifically `fs.inotify.max_user_instances` and `fs.inotify.max_user_watches`. Run the following:
|
||||
|
||||
```shell
|
||||
echo "fs.inotify.max_user_instances=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
|
||||
echo "fs.inotify.max_user_watches=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
|
||||
sudo sysctl --system
|
||||
```
|
||||
|
||||
## Building the image
|
||||
|
||||
Clone the repository and build the Docker image:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/chatmail/relay
|
||||
cd relay
|
||||
docker compose build chatmail
|
||||
```
|
||||
|
||||
The build bakes all binaries, Python packages, and the install stage into the image. After building, only `docker-compose.yaml` and `.env` are needed to run the container.
|
||||
|
||||
Pre-built images are available from GitHub Container Registry. The `main` branch and tagged releases are pushed automatically by CI:
|
||||
|
||||
```shell
|
||||
docker pull ghcr.io/chatmail/relay:main # latest main branch
|
||||
docker pull ghcr.io/chatmail/relay:1.2.3 # tagged release
|
||||
docker pull ghcr.io/chatmail/relay:j4n-docker # feature branch (for testing)
|
||||
```
|
||||
|
||||
You can also transfer a locally built image to your server directly:
|
||||
```shell
|
||||
docker save chatmail-relay:latest | pigz | ssh chat.example.com 'pigz -d | docker load'
|
||||
```
|
||||
## Running with Docker Compose
|
||||
|
||||
1. Copy `docker-compose.yaml` and `docker/example.env` into a working directory:
|
||||
|
||||
```shell
|
||||
cp docker-compose.yaml /path/to/your/workdir/
|
||||
cp docker/example.env /path/to/your/workdir/.env
|
||||
```
|
||||
|
||||
If you are running from the cloned repo directory, just copy the env file:
|
||||
|
||||
```shell
|
||||
cp ./docker/example.env .env
|
||||
```
|
||||
|
||||
All local customizations (data paths, extra volumes, config mounts) go in `docker-compose.override.yaml`, which Compose merges automatically with the base file. Copy the example to get started:
|
||||
|
||||
```shell
|
||||
cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
|
||||
```
|
||||
|
||||
2. Configure the `.env` file. Only `MAIL_DOMAIN` is required:
|
||||
|
||||
- `MAIL_DOMAIN` – The domain name of the future server. (required)
|
||||
- `CMDEPLOY_STAGES` – Deployment stages to run on container start. (default: `"configure,activate"`). Set to `"install,configure,activate"` to force a full reinstall.
|
||||
|
||||
The container generates a `chatmail.ini` with defaults from `MAIL_DOMAIN` on first start. To customize chatmail settings, mount your own `chatmail.ini` instead (see [Customization](#custom-chatmailini) below).
|
||||
|
||||
3. Start the container:
|
||||
|
||||
```shell
|
||||
docker compose up -d # start service
|
||||
docker compose logs -f chatmail # view container logs, press CTRL+C to exit
|
||||
```
|
||||
|
||||
4. After installation is complete, you can open `https://<your_domain_name>` in your browser.
|
||||
|
||||
## Managing the server
|
||||
|
||||
Use `docker exec` to run cmdeploy commands inside the container:
|
||||
|
||||
```shell
|
||||
# Show required DNS records
|
||||
docker exec chatmail /opt/cmdeploy/bin/cmdeploy dns --ssh-host @local
|
||||
|
||||
# Check server status
|
||||
docker exec chatmail /opt/cmdeploy/bin/cmdeploy status --ssh-host @local
|
||||
|
||||
# Run benchmarks (can also run from any machine with cmdeploy installed)
|
||||
docker exec chatmail /opt/cmdeploy/bin/cmdeploy bench chat.example.com
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom website
|
||||
|
||||
You can customize the Chatmail landing page by mounting a directory with your own website source files.
|
||||
|
||||
1. Create a directory with your custom website source:
|
||||
|
||||
```shell
|
||||
mkdir -p ./custom/www/src
|
||||
nano ./custom/www/src/index.md
|
||||
```
|
||||
|
||||
2. Add the volume mount in `docker-compose.override.yaml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
chatmail:
|
||||
volumes:
|
||||
- ./custom/www:/opt/chatmail-www
|
||||
```
|
||||
|
||||
3. Restart the service:
|
||||
|
||||
```shell
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Custom chatmail.ini
|
||||
|
||||
There are two configuration modes:
|
||||
|
||||
**Simple (default):** Set `MAIL_DOMAIN` in `.env`. The container auto-generates `chatmail.ini` with defaults on first start. This is sufficient for most deployments.
|
||||
|
||||
**Advanced:** Generate a `chatmail.ini`, edit it, and mount it into the container. This gives you full control over all chatmail settings.
|
||||
|
||||
1. Extract the generated config from a running container:
|
||||
|
||||
```shell
|
||||
docker cp chatmail:/etc/chatmail/chatmail.ini ./chatmail.ini
|
||||
```
|
||||
|
||||
2. Edit `chatmail.ini` as needed.
|
||||
|
||||
3. Add the volume mount in `docker-compose.override.yaml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
chatmail:
|
||||
volumes:
|
||||
- ./chatmail.ini:/etc/chatmail/chatmail.ini
|
||||
```
|
||||
|
||||
4. Restart the container. The mounted file is used directly — the container skips generating a new one.
|
||||
|
||||
## Migrating from a bare-metal install
|
||||
|
||||
If you have an existing bare-metal Chatmail installation and want to switch to Docker:
|
||||
|
||||
1. Stop all existing services:
|
||||
|
||||
```shell
|
||||
systemctl stop postfix dovecot doveauth nginx opendkim unbound acmetool-redirector \
|
||||
filtermail filtermail-incoming chatmail-turn iroh-relay chatmail-metadata \
|
||||
lastlogin mtail
|
||||
systemctl disable postfix dovecot doveauth nginx opendkim unbound acmetool-redirector \
|
||||
filtermail filtermail-incoming chatmail-turn iroh-relay chatmail-metadata \
|
||||
lastlogin mtail
|
||||
```
|
||||
|
||||
2. Copy your existing `chatmail.ini` and mount it into the container (see [Custom chatmail.ini](#custom-chatmailini) above):
|
||||
|
||||
```shell
|
||||
cp /usr/local/lib/chatmaild/chatmail.ini ./chatmail.ini
|
||||
```
|
||||
|
||||
3. Copy persistent data into the `./data/` subdirectories:
|
||||
|
||||
```shell
|
||||
mkdir -p data/chatmail-dkimkeys data/chatmail-acme data/chatmail
|
||||
|
||||
# DKIM keys
|
||||
cp -a /etc/dkimkeys/* data/chatmail-dkimkeys/
|
||||
|
||||
# ACME certificates and account
|
||||
rsync -a /var/lib/acme/ data/chatmail-acme/
|
||||
|
||||
# Mail data
|
||||
rsync -a /home/ data/chatmail/
|
||||
```
|
||||
|
||||
Alternatively, you can mount `/home/vmail` directly by changing the volume in `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
- /home/vmail:/home/vmail
|
||||
```
|
||||
|
||||
The three `./data/` subdirectories cover all persistent state. Everything else is regenerated by the `configure` and `activate` stages on container start.
|
||||
|
||||
## Forcing a full reinstall
|
||||
|
||||
The Docker image bakes the install stage (binary downloads, package setup, chatmaild venv) into the image at build time. On container start, only the `configure` and `activate` stages run by default.
|
||||
|
||||
To force a full reinstall (e.g., after updating the source), either rebuild the image:
|
||||
|
||||
```shell
|
||||
docker compose build chatmail
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Or override the stages at runtime without rebuilding:
|
||||
|
||||
```shell
|
||||
CMDEPLOY_STAGES="install,configure,activate" docker compose up -d
|
||||
```
|
||||
@@ -1,31 +0,0 @@
|
||||
# Docker Installation (Русский)
|
||||
|
||||
> **Этот документ устарел.** Актуальная документация по установке Docker доступна в
|
||||
> [DOCKER_INSTALLATION_EN.md](DOCKER_INSTALLATION_EN.md).
|
||||
>
|
||||
> This document is outdated. See [DOCKER_INSTALLATION_EN.md](DOCKER_INSTALLATION_EN.md) for current Docker installation instructions.
|
||||
|
||||
## Краткая инструкция
|
||||
|
||||
1. Установите Docker Compose v2 (`docker compose`, не `docker-compose`).
|
||||
|
||||
2. Клонируйте репозиторий и соберите образ:
|
||||
```shell
|
||||
git clone https://github.com/chatmail/relay
|
||||
cd relay
|
||||
docker compose build chatmail
|
||||
```
|
||||
|
||||
3. Скопируйте `docker/example.env` в `.env` и укажите `MAIL_DOMAIN`:
|
||||
```shell
|
||||
cp docker/example.env .env
|
||||
# отредактируйте .env — установите MAIL_DOMAIN
|
||||
```
|
||||
|
||||
4. Запустите:
|
||||
```shell
|
||||
docker compose up -d
|
||||
docker compose logs -f chatmail
|
||||
```
|
||||
|
||||
Подробности: [DOCKER_INSTALLATION_EN.md](DOCKER_INSTALLATION_EN.md)
|
||||
Reference in New Issue
Block a user