Skip to content

Commit 6094bb4

Browse files
j4nKeonik1missytake
committed
feat: add Docker and Compose support
Add Docker-based deployment: Dockerfile based on systemd image, docker-compose.yaml, build script, entrypoint, external certificate monitoring, CI workflow, and documentation. This builds on the chatmaild/cmdeploy preparation in the previous commit (j4n/docker-prep-chatmail) which added the env-var-driven feature flags (CHATMAIL_NOSYSCTL, CHATMAIL_NOPORTCHECK, CHATMAIL_NOACME) and @Local deployment support needed by the container. This is commit 2 of 3 to merge squashed changes on j4n/docker and docker branches, original commits were beef0ec..606f36e Architecture overview (mostly by original author Keonik1): - Debian-systemd image wrapping the existing cmdeploy install - Host networking to not manually expose the many ports needed - Config via MAIL_DOMAIN env var or (new) mounted chatmail.ini - New: cmdeploy stages: install at build, configure+activate at startup - New: Monitoring service for external certs via systemd timer (chatmail-certmon) - New: Image version tracking for automatic upgrade detection (cm + config hash) - New: docker-compose.override.yaml pattern for user customizations - New: GitHub Actions CI for ghcr.io image builds Traefik reverse-proxy support is prepared but the specific files are excluded from this PR and will be submitted separately. TODO: - [ ] Pull out CHATMAIL_NOACME as PR #855 introduced a proper mechanism - [ ] Check if underlying image could be based on regular debian-slim images with a step to enable systemd, similar to https://github.com/alexdzyoba/docker-debian-systemd Files added: .dockerignore .github/workflows/docker-build.yaml docker-compose.yaml docker-compose.override.yaml.example docker/build.sh docker/chatmail_relay.dockerfile docker/files/chatmail-certmon.{service,sh,timer} docker/files/entrypoint.sh docker/files/setup_chatmail.service docker/files/setup_chatmail_docker.sh env.example doc/source/docker.rst Files modified: .gitignore doc/source/getting_started.rst doc/source/index.rst Co-authored-by: Keonik1 <keonik.dev@gmail.com> Co-authored-by: missytake <missytake@systemli.org>
1 parent ad286d4 commit 6094bb4

17 files changed

Lines changed: 699 additions & 0 deletions

‎.dockerignore‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
data/
2+
venv/
3+
__pycache__
4+
*.pyc
5+
*.orig
6+
*.ini
7+
.pytest_cache
8+
.env
9+
10+
# Slim build context — .git/ alone can be 100s of MB
11+
.git
12+
.github/
13+
docs/
14+
tests/
15+
16+
# Exclude markdown files but keep www/src/*.md (used by WebsiteDeployer)
17+
*.md
18+
!www/**/*.md

‎.github/workflows/docker-build.yaml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: Docker Build
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docker/**'
7+
- 'docker-compose.yaml'
8+
- '.dockerignore'
9+
- 'chatmaild/**'
10+
- 'cmdeploy/**'
11+
- '.github/workflows/docker-build.yaml'
12+
push:
13+
branches:
14+
- main
15+
- j4n/docker
16+
paths:
17+
- 'docker/**'
18+
- 'docker-compose.yaml'
19+
- '.dockerignore'
20+
- 'chatmaild/**'
21+
- 'cmdeploy/**'
22+
- '.github/workflows/docker-build.yaml'
23+
tags:
24+
- 'v*'
25+
26+
env:
27+
REGISTRY: ghcr.io
28+
IMAGE_NAME: ${{ github.repository }}
29+
30+
jobs:
31+
build:
32+
name: Build Docker image
33+
runs-on: ubuntu-latest
34+
permissions:
35+
contents: read
36+
packages: write
37+
steps:
38+
- uses: actions/checkout@v4
39+
40+
- name: Set up Docker Buildx
41+
uses: docker/setup-buildx-action@v3
42+
43+
- name: Login to GHCR
44+
if: github.event_name == 'push'
45+
uses: docker/login-action@v3
46+
with:
47+
registry: ${{ env.REGISTRY }}
48+
username: ${{ github.actor }}
49+
password: ${{ secrets.GITHUB_TOKEN }}
50+
51+
- name: Extract metadata (tags, labels)
52+
id: meta
53+
uses: docker/metadata-action@v5
54+
with:
55+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
56+
tags: |
57+
# Tagged releases: v1.2.3 → :1.2.3, :1.2, :latest
58+
type=semver,pattern={{version}}
59+
type=semver,pattern={{major}}.{{minor}}
60+
# Branch pushes: j4n/docker → :j4n-docker
61+
type=ref,event=branch
62+
# Always: :sha-<hash>
63+
type=sha
64+
65+
- name: Build and push
66+
uses: docker/build-push-action@v6
67+
with:
68+
context: .
69+
file: docker/chatmail_relay.dockerfile
70+
push: ${{ github.event_name == 'push' }}
71+
tags: ${{ steps.meta.outputs.tags }}
72+
labels: ${{ steps.meta.outputs.labels }}
73+
cache-from: type=gha
74+
cache-to: type=gha,mode=max
75+
build-args: |
76+
GIT_HASH=${{ github.sha }}

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,3 +164,9 @@ cython_debug/
164164
#.idea/
165165

166166
chatmail.zone
167+
168+
# docker
169+
/data/
170+
/custom/
171+
docker-compose.override.yaml
172+
.env

‎doc/source/docker.rst‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
Docker installation
2+
===================
3+
4+
This section provides instructions for installing a chatmail relay
5+
using Docker Compose.
6+
7+
.. note::
8+
9+
Docker support is experimental and not yet covered by automated tests, please report bugs.
10+
11+
12+
Known limitations
13+
-----------------
14+
15+
- Requires cgroups v2 on the host. Operation with cgroups v1 has not been tested.
16+
- This preliminary image simply wraps the cmdeploy process detailed in the :doc:`getting_started` instructions in a full Debian-systemd image.
17+
- Currently, the image has only been tested and built on amd64, though arm64 should theoretically work as well.
18+
19+
20+
Prerequisites
21+
-------------
22+
23+
- **Docker Compose v2** (``docker compose``, not ``docker-compose``) is
24+
required for its ``cgroup: host`` support (`Install instructions <https://docs.docker.com/engine/install/debian/#install-using-the-repository>`_:)
25+
26+
- **DNS records** for your domain (see step 1 below).
27+
28+
- **Kernel parameters** — ``fs.inotify.max_user_instances`` and
29+
``fs.inotify.max_user_watches`` must be raised on the host because they
30+
cannot be changed inside the container (see step 2 below).
31+
32+
33+
Preliminary setup
34+
-----------------
35+
36+
We use ``chat.example.org`` as the chatmail domain in the following
37+
steps. Please substitute it with your own domain.
38+
39+
1. Setup the initial DNS records.
40+
The following is an example in the familiar BIND zone file format with
41+
a TTL of 1 hour (3600 seconds).
42+
Please substitute your domain and IP addresses.
43+
44+
::
45+
46+
chat.example.org. 3600 IN A 198.51.100.5
47+
chat.example.org. 3600 IN AAAA 2001:db8::5
48+
www.chat.example.org. 3600 IN CNAME chat.example.org.
49+
mta-sts.chat.example.org. 3600 IN CNAME chat.example.org.
50+
51+
2. Configure kernel parameters on the host, as these can not be set from the container::
52+
53+
echo "fs.inotify.max_user_instances=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
54+
echo "fs.inotify.max_user_watches=65536" | sudo tee -a /etc/sysctl.d/99-inotify.conf
55+
sudo sysctl --system
56+
57+
58+
Docker Compose Setup
59+
--------------------
60+
61+
Pre-built images are available from GitHub Container Registry. The
62+
``main`` branch and tagged releases are pushed automatically by CI::
63+
64+
docker pull ghcr.io/chatmail/relay:main # latest main branch
65+
docker pull ghcr.io/chatmail/relay:1.2.3 # tagged release
66+
67+
68+
Create service directory
69+
^^^^^^^^^^^^^^^^^^^^^^^^
70+
71+
Either:
72+
73+
- Create a service directory, e.g., `/srv/chatmail-relay`::
74+
75+
mkdir -p /srv/chatmail-relay && cd /srv/chatmail-relay
76+
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
77+
wget https://raw.githubusercontent.com/chatmail/relay/refs/heads/main/docker/env.example -O .env
78+
79+
80+
- or clone the chatmail repo ::
81+
82+
git clone https://github.com/chatmail/relay
83+
cd relay
84+
cp example.env .env
85+
86+
87+
88+
Customize and start
89+
^^^^^^^^^^^^^^^^^^^
90+
91+
1. All local customizations (data paths, extra volumes, config mounts) go in
92+
``docker-compose.override.yaml``, which Compose merges automatically with
93+
the base file. By default, all data is stored in docker volumes, you will
94+
likely want to at least create and configure the mail storage location. Copy
95+
the example to get started::
96+
97+
cp docker/docker-compose.override.yaml.example docker-compose.override.yaml
98+
# and edit docker-compose.override.yaml
99+
100+
101+
2. Configure the ``.env`` file. Only ``MAIL_DOMAIN`` is required, the domain
102+
name of the future server.
103+
104+
The container generates a ``chatmail.ini`` with defaults from
105+
``MAIL_DOMAIN`` on first start. To customize chatmail settings, mount
106+
your own ``chatmail.ini`` instead (see `Custom chatmail.ini`_ below).
107+
108+
3. Start the container::
109+
110+
docker compose up -d
111+
docker compose logs -f chatmail # view logs, Ctrl+C to exit
112+
113+
4. After installation is complete, open ``https://chat.example.org`` in
114+
your browser.
115+
116+
117+
Managing the server
118+
-------------------
119+
120+
Use ``docker exec`` to run cmdeploy commands inside the container::
121+
122+
# Show required DNS records
123+
docker exec chatmail /opt/cmdeploy/bin/cmdeploy dns --ssh-host @local
124+
125+
# Check server status
126+
docker exec chatmail /opt/cmdeploy/bin/cmdeploy status --ssh-host @local
127+
128+
# Run benchmarks (can also run from any machine with cmdeploy installed)
129+
docker exec chatmail /opt/cmdeploy/bin/cmdeploy bench chat.example.org
130+
131+
132+
Customization
133+
-------------
134+
135+
Custom website
136+
^^^^^^^^^^^^^^
137+
138+
You can customize the chatmail landing page by mounting a directory with
139+
your own website source files.
140+
141+
1. Create a directory with your custom website source::
142+
143+
mkdir -p ./custom/www/src
144+
nano ./custom/www/src/index.md
145+
146+
2. Add the volume mount in ``docker-compose.override.yaml``::
147+
148+
services:
149+
chatmail:
150+
volumes:
151+
- ./custom/www:/opt/chatmail-www
152+
153+
3. Restart the service::
154+
155+
docker compose down
156+
docker compose up -d
157+
158+
159+
Custom chatmail.ini
160+
^^^^^^^^^^^^^^^^^^^
161+
162+
There are two configuration modes:
163+
164+
**Simple (default):** Set ``MAIL_DOMAIN`` in ``.env``. The container
165+
auto-generates ``chatmail.ini`` with defaults on first start. This is
166+
sufficient for most deployments.
167+
168+
**Advanced:** Generate a ``chatmail.ini``, edit it, and mount it into
169+
the container. This gives you full control over all chatmail settings.
170+
171+
1. Extract the generated config from a running container::
172+
173+
docker cp chatmail:/etc/chatmail/chatmail.ini ./chatmail.ini
174+
175+
2. Edit ``chatmail.ini`` as needed.
176+
177+
3. Add the volume mount in ``docker-compose.override.yaml`` ::
178+
179+
services:
180+
chatmail:
181+
volumes:
182+
- ./chatmail.ini:/etc/chatmail/chatmail.ini
183+
184+
4. Restart the container, the container skips generating a new one: ::
185+
186+
docker compose down && docker compose up -d
187+
188+
189+
Migrating from a bare-metal install
190+
------------------------------------
191+
192+
If you have an existing bare-metal chatmail installation and want to
193+
switch to Docker:
194+
195+
1. Stop all existing services::
196+
197+
systemctl stop postfix dovecot doveauth nginx opendkim unbound \
198+
acmetool-redirector filtermail filtermail-incoming chatmail-turn \
199+
iroh-relay chatmail-metadata lastlogin mtail
200+
systemctl disable postfix dovecot doveauth nginx opendkim unbound \
201+
acmetool-redirector filtermail filtermail-incoming chatmail-turn \
202+
iroh-relay chatmail-metadata lastlogin mtail
203+
204+
2. Copy your existing ``chatmail.ini`` and mount it into the container
205+
(see `Custom chatmail.ini`_ above)::
206+
207+
cp /usr/local/lib/chatmaild/chatmail.ini ./chatmail.ini
208+
209+
3. Copy persistent data into the ``./data/`` subdirectories (for example, as configured in `Customize and start`_) ::
210+
211+
mkdir -p data/chatmail-dkimkeys data/chatmail-acme data/chatmail
212+
213+
# DKIM keys
214+
cp -a /etc/dkimkeys/* data/chatmail-dkimkeys/
215+
216+
# ACME certificates and account
217+
rsync -a /var/lib/acme/ data/chatmail-acme/
218+
219+
# Mail data
220+
rsync -a /home/ data/chatmail/
221+
222+
Alternatively, mount ``/home/vmail`` directly by changing the volume
223+
in ``docker-compose-override.yaml``::
224+
225+
- /home/vmail:/home/vmail
226+
227+
The three ``./data/`` subdirectories cover all persistent state.
228+
Everything else is regenerated by the ``configure`` and ``activate``
229+
stages on container start.
230+
231+
Building the image
232+
------------------
233+
234+
Clone the repository and build the Docker image::
235+
236+
git clone https://github.com/chatmail/relay
237+
cd relay
238+
docker compose build chatmail
239+
240+
The build bakes all binaries, Python packages, and the install stage
241+
into the image. After building, only ``docker-compose.yaml`` and ``.env``
242+
are needed to run the container.
243+
244+
You can transfer a locally built image to your server directly (pigz is parallel `gzip` which can be used instead as well) ::
245+
246+
docker save chatmail-relay:latest | pigz | ssh chat.example.org 'pigz -d | docker load'
247+
248+
249+
Forcing a full reinstall
250+
------------------------
251+
252+
On container start, only the ``configure`` and ``activate`` stages run by default.
253+
254+
To force a full reinstall (e.g. after updating the source), either
255+
rebuild the image::
256+
257+
docker compose build chatmail
258+
docker compose up -d
259+
260+
Or override the stages at runtime without rebuilding::
261+
262+
CMDEPLOY_STAGES="install,configure,activate" docker compose up -d

‎doc/source/getting_started.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,12 @@ steps. Please substitute it with your own domain.
9898
configure at your DNS provider (it can take some time until they are
9999
public).
100100

101+
Docker installation
102+
-------------------
103+
104+
There is experimental support for running chatmail via Docker Compose.
105+
See :doc:`docker` for full setup instructions.
106+
101107
Other helpful commands
102108
----------------------
103109

‎doc/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Contributions and feedback welcome through the https://github.com/chatmail/relay
1313
:maxdepth: 5
1414

1515
getting_started
16+
docker
1617
proxy
1718
migrate
1819
overview

0 commit comments

Comments
 (0)