From 97dd5dc63a982a43412a0da0d746cfe7cb5c9520 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 9 Aug 2025 15:55:37 +0300 Subject: [PATCH 01/14] Add installation via docker compose (MVP 1) - Adds configuration parameters (`change_kernel_settings`, `fs_inotify_max_user_instances_and_watchers`) --- .gitignore | 6 + CHANGELOG.md | 8 + README.md | 12 +- chatmaild/src/chatmaild/config.py | 6 + chatmaild/src/chatmaild/ini/chatmail.ini.f | 10 ++ cmdeploy/src/cmdeploy/__init__.py | 27 +-- cmdeploy/src/cmdeploy/cmdeploy.py | 3 + docker/chatmail_server.dockerfile | 102 +++++++++++ docker/docker-compose-default.yaml | 58 ++++++ docker/example.env | 3 + docker/files/entrypoint.sh | 20 +++ docker/files/setup_chatmail.service | 14 ++ docker/files/setup_chatmail_docker.sh | 74 ++++++++ docker/files/update_ini.sh | 79 +++++++++ docs/DOCKER_INSTALLATION_EN.md | 196 +++++++++++++++++++++ docs/DOCKER_INSTALLATION_RU.md | 176 ++++++++++++++++++ 16 files changed, 777 insertions(+), 17 deletions(-) create mode 100644 docker/chatmail_server.dockerfile create mode 100644 docker/docker-compose-default.yaml create mode 100644 docker/example.env create mode 100755 docker/files/entrypoint.sh create mode 100644 docker/files/setup_chatmail.service create mode 100755 docker/files/setup_chatmail_docker.sh create mode 100644 docker/files/update_ini.sh create mode 100644 docs/DOCKER_INSTALLATION_EN.md create mode 100644 docs/DOCKER_INSTALLATION_RU.md diff --git a/.gitignore b/.gitignore index 6e1054d0..c6260e93 100644 --- a/.gitignore +++ b/.gitignore @@ -164,3 +164,9 @@ cython_debug/ #.idea/ chatmail.zone + +# docker +/data/ +/custom/ +docker-compose.yaml +.env diff --git a/CHANGELOG.md b/CHANGELOG.md index e8f3a1c0..8c015ec2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,14 @@ - Add `--skip-dns-check` argument to `cmdeploy run` command, which disables DNS record checking before installation. ([#661](https://github.com/chatmail/relay/pull/661)) +- Add installation via docker compose (MVP 1). The instructions, known issues and limitations are located in `/docs` + ([#614](https://github.com/chatmail/relay/pull/614)) + +- Add configuration parameters + ([#614](https://github.com/chatmail/relay/pull/614)): + - `change_kernel_settings` - Whether to change kernel parameters during installation (default: `True`) + - `fs_inotify_max_user_instances_and_watchers` - Value for kernel parameters `fs.inotify.max_user_instances` and `fs.inotify.max_user_watches` (default: `65535`) + ## 1.7.0 2025-09-11 - Make www upload path configurable diff --git a/README.md b/README.md index 9f60d113..4324d156 100644 --- a/README.md +++ b/README.md @@ -74,22 +74,23 @@ Please substitute it with your own domain. ``` git clone https://github.com/chatmail/relay cd relay - scripts/initenv.sh ``` -3. On your local PC, create chatmail configuration file `chatmail.ini`: +### Manual installation +1. On your local PC, create chatmail configuration file `chatmail.ini`: ``` + scripts/initenv.sh scripts/cmdeploy init chat.example.org # <-- use your domain ``` -4. Verify that SSH root login to your remote server works: +2. Verify that SSH root login to your remote server works: ``` ssh root@chat.example.org # <-- use your domain ``` -5. From your local PC, deploy the remote chatmail relay server: +3. From your local PC, deploy the remote chatmail relay server: ``` scripts/cmdeploy run @@ -99,6 +100,9 @@ Please substitute it with your own domain. which you should configure at your DNS provider (it can take some time until they are public). +### Docker installation +Installation using docker compose is presented [here](./docs/DOCKER_INSTALLATION_EN.md) + ### Other helpful commands To check the status of your remotely running chatmail service: diff --git a/chatmaild/src/chatmaild/config.py b/chatmaild/src/chatmaild/config.py index c8762af8..c2526dd5 100644 --- a/chatmaild/src/chatmaild/config.py +++ b/chatmaild/src/chatmaild/config.py @@ -45,6 +45,12 @@ def __init__(self, inipath, params): self.mtail_address = params.get("mtail_address") self.disable_ipv6 = params.get("disable_ipv6", "false").lower() == "true" self.acme_email = params.get("acme_email", "") + self.change_kernel_settings = ( + params.get("change_kernel_settings", "true").lower() == "true" + ) + self.fs_inotify_max_user_instances_and_watchers = int( + params["fs_inotify_max_user_instances_and_watchers"] + ) self.imap_rawlog = params.get("imap_rawlog", "false").lower() == "true" if "iroh_relay" not in params: self.iroh_relay = "https://" + params["mail_domain"] diff --git a/chatmaild/src/chatmaild/ini/chatmail.ini.f b/chatmaild/src/chatmaild/ini/chatmail.ini.f index 0aeec0cc..f64f7c45 100644 --- a/chatmaild/src/chatmaild/ini/chatmail.ini.f +++ b/chatmaild/src/chatmaild/ini/chatmail.ini.f @@ -66,6 +66,16 @@ # Your email adress, which will be used in acmetool to manage Let's Encrypt SSL certificates acme_email = +# +# Kernel settings +# + +# if you set "True", the kernel settings will be configured according to the values below +change_kernel_settings = True + +# change fs.inotify.max_user_instances and fs.inotify.max_user_watches kernel settings +fs_inotify_max_user_instances_and_watchers = 65535 + # Defaults to https://iroh.{{mail_domain}} and running `iroh-relay` on the chatmail # service. # If you set it to anything else, the service will be disabled diff --git a/cmdeploy/src/cmdeploy/__init__.py b/cmdeploy/src/cmdeploy/__init__.py index ea192a07..fc717986 100644 --- a/cmdeploy/src/cmdeploy/__init__.py +++ b/cmdeploy/src/cmdeploy/__init__.py @@ -396,20 +396,21 @@ def _configure_dovecot(config: Config, debug: bool = False) -> bool: config=config, ) - # as per https://doc.dovecot.org/configuration_manual/os/ + # as per https://doc.dovecot.org/2.3/configuration_manual/os/ # it is recommended to set the following inotify limits - for name in ("max_user_instances", "max_user_watches"): - key = f"fs.inotify.{name}" - if host.get_fact(Sysctl)[key] > 65535: - # Skip updating limits if already sufficient - # (enables running in incus containers where sysctl readonly) - continue - server.sysctl( - name=f"Change {key}", - key=key, - value=65535, - persist=True, - ) + if config.change_kernel_settings: + for name in ("max_user_instances", "max_user_watches"): + key = f"fs.inotify.{name}" + if host.get_fact(Sysctl)[key] == config.fs_inotify_max_user_instances_and_watchers: + # Skip updating limits if already sufficient + # (enables running in incus containers where sysctl readonly) + continue + server.sysctl( + name=f"Change {key}", + key=key, + value=config.fs_inotify_max_user_instances_and_watchers, + persist=True, + ) timezone_env = files.line( name="Set TZ environment variable", diff --git a/cmdeploy/src/cmdeploy/cmdeploy.py b/cmdeploy/src/cmdeploy/cmdeploy.py index e71d0ce8..9c6f2efa 100644 --- a/cmdeploy/src/cmdeploy/cmdeploy.py +++ b/cmdeploy/src/cmdeploy/cmdeploy.py @@ -118,6 +118,9 @@ def run_cmd(args, out): kwargs=dict(command="cat /var/lib/echobot/invite-link.txt"), ) ) + server_deployed_message = f"Chatmail server started: https://{args.config.mail_domain}/" + delimiter_line = "=" * len(server_deployed_message) + out.green(f"{delimiter_line}\n{server_deployed_message}\n{delimiter_line}") out.green("Deploy completed, call `cmdeploy dns` next.") elif not remote_data["acme_account_url"]: out.red("Deploy completed but letsencrypt not configured") diff --git a/docker/chatmail_server.dockerfile b/docker/chatmail_server.dockerfile new file mode 100644 index 00000000..72c4a042 --- /dev/null +++ b/docker/chatmail_server.dockerfile @@ -0,0 +1,102 @@ +FROM jrei/systemd-debian:12 AS base + +ENV LANG=en_US.UTF-8 + +RUN echo 'APT::Install-Recommends "0";' > /etc/apt/apt.conf.d/01norecommend && \ + echo 'APT::Install-Suggests "0";' >> /etc/apt/apt.conf.d/01norecommend && \ + apt-get update && \ + apt-get install -y \ + ca-certificates && \ + DEBIAN_FRONTEND=noninteractive \ + TZ=Europe/London \ + apt-get install -y tzdata && \ + apt-get install -y locales && \ + sed -i -e "s/# $LANG.*/$LANG UTF-8/" /etc/locale.gen && \ + dpkg-reconfigure --frontend=noninteractive locales && \ + update-locale LANG=$LANG \ + && rm -rf /var/lib/apt/lists/* + +RUN apt-get update && \ + apt-get install -y \ + openssh-client \ + openssh-server \ + git \ + python3 \ + python3-venv \ + python3-virtualenv \ + gcc \ + python3-dev \ + opendkim \ + opendkim-tools \ + curl \ + rsync \ + unbound \ + unbound-anchor \ + dnsutils \ + postfix \ + acl \ + nginx \ + libnginx-mod-stream \ + fcgiwrap \ + cron \ + && for pkg in core imapd lmtpd; do \ + case "$pkg" in \ + core) sha256="43f593332e22ac7701c62d58b575d2ca409e0f64857a2803be886c22860f5587" ;; \ + imapd) sha256="8d8dc6fc00bbb6cdb25d345844f41ce2f1c53f764b79a838eb2a03103eebfa86" ;; \ + lmtpd) sha256="2f69ba5e35363de50962d42cccbfe4ed8495265044e244007d7ccddad77513ab" ;; \ + esac; \ + url="https://download.delta.chat/dovecot/dovecot-${pkg}_2.3.21%2Bdfsg1-3_amd64.deb"; \ + file="/tmp/$(basename "$url")"; \ + curl -fsSL "$url" -o "$file"; \ + echo "$sha256 $file" | sha256sum -c -; \ + apt-get install -y "$file"; \ + rm -f "$file"; \ + done \ + && rm -rf /var/lib/apt/lists/* + +RUN systemctl enable \ + ssh \ + fcgiwrap + +RUN sed -i 's/^#PasswordAuthentication .*/PasswordAuthentication no/' /etc/ssh/sshd_config && \ + sed -i 's/^#PermitRootLogin .*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config && \ + ssh-keygen -P "" -t rsa -b 2048 -f /root/.ssh/id_rsa && \ + mkdir -p /root/.ssh && \ + cat /root/.ssh/id_rsa.pub >> /root/.ssh/authorized_keys && \ + SSH_USER_CONFIG="/root/.ssh/config" && \ + echo "Host localhost" > "$SSH_USER_CONFIG" && \ + echo " HostName localhost" >> "$SSH_USER_CONFIG" && \ + echo " User root" >> "$SSH_USER_CONFIG" && \ + echo " StrictHostKeyChecking no" >> "$SSH_USER_CONFIG" && \ + echo " UserKnownHostsFile /dev/null" >> "$SSH_USER_CONFIG" + ## TODO: deny access for all insteed root form 127.0.0.1 https://unix.stackexchange.com/a/406264 + +WORKDIR /opt/chatmail + +ARG SETUP_CHATMAIL_SERVICE_PATH=/lib/systemd/system/setup_chatmail.service +COPY ./files/setup_chatmail.service "$SETUP_CHATMAIL_SERVICE_PATH" +RUN ln -sf "$SETUP_CHATMAIL_SERVICE_PATH" "/etc/systemd/system/multi-user.target.wants/setup_chatmail.service" + +COPY --chmod=555 ./files/setup_chatmail_docker.sh /setup_chatmail_docker.sh +COPY --chmod=555 ./files/update_ini.sh /update_ini.sh +COPY --chmod=555 ./files/entrypoint.sh /entrypoint.sh + +## TODO: add git clone. +## Problem: how correct save only required files inside container.... +# RUN git clone https://github.com/chatmail/relay.git -b master . \ +# && ./scripts/initenv.sh + +# EXPOSE 443 25 587 143 993 + +VOLUME ["/sys/fs/cgroup", "/home"] + +STOPSIGNAL SIGRTMIN+3 + +ENTRYPOINT ["/entrypoint.sh"] + +CMD [ "--default-standard-output=journal+console", \ + "--default-standard-error=journal+console" ] + +## TODO: Add installation and configuration of chatmaild inside the Dockerfile. +## This is required to ensure repeatable deployment. +## In the current MVP, the chatmaild server is updated on every container restart. diff --git a/docker/docker-compose-default.yaml b/docker/docker-compose-default.yaml new file mode 100644 index 00000000..61e7765f --- /dev/null +++ b/docker/docker-compose-default.yaml @@ -0,0 +1,58 @@ +services: + chatmail: + build: + context: ./docker + dockerfile: chatmail_server.dockerfile + tags: + - chatmail-relay:latest + image: chatmail-relay:latest + restart: unless-stopped + container_name: chatmail + cgroup: host # required for systemd + tty: true # required for logs + tmpfs: # required for systemd + - /tmp + - /run + - /run/lock + logging: + driver: json-file + options: + max-size: "10m" + max-file: "3" + environment: + MAIL_DOMAIN: + CHANGE_KERNEL_SETTINGS: "False" + ACME_EMAIL: + + MAX_MESSAGE_SIZE: "50M" + # DEBUG_COMMANDS_ENABLED: "true" + # FORCE_REINIT_INI_FILE: "true" + # USE_FOREIGN_CERT_MANAGER: "True" + # ENABLE_CERTS_MONITORING: "true" + # CERTS_MONITORING_TIMEOUT: 10 + # IS_DEVELOPMENT_INSTANCE: "True" + ports: + - "25:25" + - "587:587" + - "143:143" + - "993:993" + - "443:443" + volumes: + ## system + - /sys/fs/cgroup:/sys/fs/cgroup:rw # required for systemd + - ./:/opt/chatmail + - ./data/acme:/var/lib/acme + + ## data + - ./data/chatmail:/home + - ./data/chatmail-dkimkeys:/etc/dkimkeys + - ./data/chatmail-echobot:/run/echobot + - ./data/chatmail-acme:/var/lib/acme + + ## custom resources + # - ./custom/www/src/index.md:/opt/chatmail/www/src/index.md + + ## debug + # - ./docker/files/setup_chatmail_docker.sh:/setup_chatmail_docker.sh + # - ./docker/files/entrypoint.sh:/entrypoint.sh + # - ./docker/files/update_ini.sh:/update_ini.sh diff --git a/docker/example.env b/docker/example.env new file mode 100644 index 00000000..ef8ca28a --- /dev/null +++ b/docker/example.env @@ -0,0 +1,3 @@ +MAIL_DOMAIN="chat.example.com" + +PATH_TO_SSL_CONTAINER="/var/lib/acme/live/${MAIL_DOMAIN}" diff --git a/docker/files/entrypoint.sh b/docker/files/entrypoint.sh new file mode 100755 index 00000000..b704c2e3 --- /dev/null +++ b/docker/files/entrypoint.sh @@ -0,0 +1,20 @@ +#!/bin/bash +set -eo pipefail + +if [ "${USE_FOREIGN_CERT_MANAGER,,}" == "true" ]; then + if [ ! -f "$PATH_TO_SSL_CONTAINER/fullchain" ]; then + echo "Error: file '$PATH_TO_SSL_CONTAINER/fullchain' does not exist. Exiting..." > /dev/stderr + exit 1 + fi + if [ ! -f "$PATH_TO_SSL_CONTAINER/privkey" ]; then + echo "Error: file '$PATH_TO_SSL_CONTAINER/privkey' does not exist. Exiting..." > /dev/stderr + exit 1 + fi +fi + +SETUP_CHATMAIL_SERVICE_PATH="${SETUP_CHATMAIL_SERVICE_PATH:-/lib/systemd/system/setup_chatmail.service}" + +env_vars=$(printenv | cut -d= -f1 | xargs) +sed -i "s||$env_vars|g" $SETUP_CHATMAIL_SERVICE_PATH + +exec /lib/systemd/systemd $@ diff --git a/docker/files/setup_chatmail.service b/docker/files/setup_chatmail.service new file mode 100644 index 00000000..2a0a48bc --- /dev/null +++ b/docker/files/setup_chatmail.service @@ -0,0 +1,14 @@ +[Unit] +Description=Run container setup commands +After=multi-user.target +ConditionPathExists=/setup_chatmail_docker.sh + +[Service] +Type=oneshot +ExecStart=/bin/bash /setup_chatmail_docker.sh +RemainAfterExit=true +WorkingDirectory=/opt/chatmail +PassEnvironment= + +[Install] +WantedBy=multi-user.target diff --git a/docker/files/setup_chatmail_docker.sh b/docker/files/setup_chatmail_docker.sh new file mode 100755 index 00000000..7e101791 --- /dev/null +++ b/docker/files/setup_chatmail_docker.sh @@ -0,0 +1,74 @@ +#!/bin/bash + +set -eo pipefail +export INI_FILE="${INI_FILE:-chatmail.ini}" +export ENABLE_CERTS_MONITORING="${ENABLE_CERTS_MONITORING:-true}" +export CERTS_MONITORING_TIMEOUT="${CERTS_MONITORING_TIMEOUT:-60}" +export PATH_TO_SSL_CONTAINER="${PATH_TO_SSL_CONTAINER:-/var/lib/acme/live/${MAIL_DOMAIN}}" +export CHANGE_KERNEL_SETTINGS=${CHANGE_KERNEL_SETTINGS:-"False"} + +if [ -z "$MAIL_DOMAIN" ]; then + echo "ERROR: Environment variable 'MAIL_DOMAIN' must be set!" >&2 + exit 1 +fi + +debug_commands() { + echo "Executing debug commands" + # git config --global --add safe.directory /opt/chatmail + # ./scripts/initenv.sh +} + +calculate_hash() { + find "$PATH_TO_SSL_CONTAINER" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' +} + +monitor_certificates() { + if [ "$ENABLE_CERTS_MONITORING" != "true" ]; then + echo "Certs monitoring disabled." + exit 0 + fi + + current_hash=$(calculate_hash) + previous_hash=$current_hash + + while true; do + current_hash=$(calculate_hash) + if [[ "$current_hash" != "$previous_hash" ]]; then + # TODO: add an option to restart at a specific time interval + echo "[INFO] Certificate's folder hash was changed, restarting nginx, dovecot and postfix services." + systemctl restart nginx.service + systemctl reload dovecot.service + systemctl reload postfix.service + previous_hash=$current_hash + fi + sleep $CERTS_MONITORING_TIMEOUT + done +} + +### MAIN + +if [ "$DEBUG_COMMANDS_ENABLED" == "true" ]; then + debug_commands +fi + +if [ "$FORCE_REINIT_INI_FILE" == "true" ]; then + INI_CMD_ARGS=--force +fi + +/usr/sbin/opendkim-genkey -D /etc/dkimkeys -d $MAIL_DOMAIN -s opendkim +chown opendkim:opendkim /etc/dkimkeys/opendkim.private +chown opendkim:opendkim /etc/dkimkeys/opendkim.txt + +# TODO: Move to debug_commands after git clone is moved to dockerfile. +git config --global --add safe.directory /opt/chatmail +./scripts/initenv.sh + +./scripts/cmdeploy init --config "${INI_FILE}" $INI_CMD_ARGS $MAIL_DOMAIN +bash /update_ini.sh + +./scripts/cmdeploy run --ssh-host localhost --skip-dns-check + +echo "ForwardToConsole=yes" >> /etc/systemd/journald.conf +systemctl restart systemd-journald + +monitor_certificates & diff --git a/docker/files/update_ini.sh b/docker/files/update_ini.sh new file mode 100644 index 00000000..c5d65661 --- /dev/null +++ b/docker/files/update_ini.sh @@ -0,0 +1,79 @@ +#!/bin/bash +set -eo pipefail + +INI_FILE="${INI_FILE:-chatmail.ini}" + +if [ ! -f "$INI_FILE" ]; then + echo "Error: file $INI_FILE not found." >&2 + exit 1 +fi + +TMP_FILE="$(mktemp)" + +convert_to_bytes() { + local value="$1" + if [[ "$value" =~ ^([0-9]+)([KkMmGgTt])$ ]]; then + local num="${BASH_REMATCH[1]}" + local unit="${BASH_REMATCH[2]}" + case "$unit" in + [Kk]) echo $((num * 1024)) ;; + [Mm]) echo $((num * 1024 * 1024)) ;; + [Gg]) echo $((num * 1024 * 1024 * 1024)) ;; + [Tt]) echo $((num * 1024 * 1024 * 1024 * 1024)) ;; + esac + elif [[ "$value" =~ ^[0-9]+$ ]]; then + echo "$value" + else + echo "Error: incorrect size format: $value." >&2 + return 1 + fi +} + +process_specific_params() { + local key=$1 + local value=$2 + local destination_file=$3 + + if [[ "$key" == "max_message_size" ]]; then + converted=$(convert_to_bytes "$value") || exit 1 + if grep -q -e "## .* = .* bytes" "$destination_file"; then + sed "s|## .* = .* bytes|## $value = $converted bytes|g" "$destination_file"; + else + echo "## $value = $converted bytes" >> "$destination_file" + fi + echo "$key = $converted" >> "$destination_file" + else + echo "$key = $value" >> "$destination_file" + fi +} + +while IFS= read -r line; do + if [[ "$line" =~ ^[[:space:]]*#.* || "$line" =~ ^[[:space:]]*$ ]]; then + echo "$line" >> "$TMP_FILE" + continue + fi + + if [[ "$line" =~ ^([a-z0-9_]+)[[:space:]]*=[[:space:]]*(.*)$ ]]; then + key="${BASH_REMATCH[1]}" + current_value="${BASH_REMATCH[2]}" + env_var_name=$(echo "$key" | tr 'a-z' 'A-Z') + env_value="${!env_var_name}" + + if [[ -n "$env_value" ]]; then + process_specific_params "$key" "$env_value" "$TMP_FILE" + else + echo "$line" >> "$TMP_FILE" + fi + else + echo "$line" >> "$TMP_FILE" + fi +done < "$INI_FILE" + +PERMS=$(stat -c %a "$INI_FILE") +OWNER=$(stat -c %u "$INI_FILE") +GROUP=$(stat -c %g "$INI_FILE") + +chmod "$PERMS" "$TMP_FILE" +chown "$OWNER":"$GROUP" "$TMP_FILE" + +mv "$TMP_FILE" "$INI_FILE" diff --git a/docs/DOCKER_INSTALLATION_EN.md b/docs/DOCKER_INSTALLATION_EN.md new file mode 100644 index 00000000..86ff727a --- /dev/null +++ b/docs/DOCKER_INSTALLATION_EN.md @@ -0,0 +1,196 @@ +# Known issues and limitations + +- Chatmail will be reinstalled every time the container is started (longer the first time, faster on subsequent starts). This is how the original installer works because it wasn’t designed for Docker. At the end of the documentation, there’s a [proposed solution](#locking-the-chatmail-version). +- 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. + +## 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. clone the repository on your server. + + ```shell + git clone https://github.com/chatmail/relay + cd relay + ``` + +## Installation + +1. Copy the file `./docker/docker-compose-default.yaml` to `docker-compose.yaml`. This is necessary because `docker-compose.yaml` is in `.gitignore` and won’t cause conflicts when updating the git repository. + +```shell +cp ./docker/docker-compose-default.yaml docker-compose.yaml +``` + +3. 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 +``` + +4. Configure container environment variables. Below is the list of variables used during deployment: + +- `MAIL_DOMAIN` – The domain name of the future server. (required) +- `DEBUG_COMMANDS_ENABLED` – Run debug commands before installation. (default: `false`) +- `FORCE_REINIT_INI_FILE` – Recreate the ini configuration file on startup. (default: `false`) +- `USE_FOREIGN_CERT_MANAGER` – Use a third-party certificate manager. (default: `false`) +- `INI_FILE` – Path to the ini configuration file. (default: `./chatmail.ini`) +- `PATH_TO_SSL_CONTAINER` – Path to where the certificates are stored. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) +- `ENABLE_CERTS_MONITORING` – Enable certificate monitoring if `USE_FOREIGN_CERT_MANAGER=true`. If certificates change, services will be automatically restarted. (default: `false`) +- `CERTS_MONITORING_TIMEOUT` – Interval in seconds to check if certificates have changed. (default: `'60'`) + +You can also use any variables from the [ini configuration file](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/ini/chatmail.ini.f); they must be in uppercase. + +Mandatory variables for deployment via Docker: + +- `CHANGE_KERNEL_SETTINGS` – Change kernel settings (`fs.inotify.max_user_instances` and `fs.inotify.max_user_watches`) on startup. Changing kernel settings inside the container is not possible! (default: `False`) + +5. Configure environment variables in the `.env` file. These variables are used in the `docker-compose.yaml` file to pass repeated values. + +6. Build the Docker image: + +```shell +docker compose build chatmail +``` + +7. Start docker compose and wait for the installation to finish: + +```shell +docker compose up -d # start service +docker compose logs -f chatmail # view container logs, press CTRL+C to exit +``` + +8. After installation is complete, you can open `https://` in your browser. + +## Using custom files + +When using Docker, you can apply modified configuration files to make the installation more personalized. This is usually needed for the `www/src` section so that the Chatmail landing page is customized to your taste, but it can be used for any other cases as well. + +To replace files correctly: + +1. Create the `./custom` directory. It is in `.gitignore`, so it won’t cause conflicts when updating. + +```shell +mkdir -p ./custom +``` + +2. Modify the required file. For example, `index.md`: + +```shell +mkdir -p ./custom/www/src +nano ./custom/www/src/index.md +``` + +3. In `docker-compose.yaml`, add the file mount in the `volumes` section: + +```yaml +services: + chatmail: + volumes: + ... + ## custom resources + - ./custom/www/src/index.md:/opt/chatmail/www/src/index.md +``` + +4. Restart the service: + +```shell +docker compose down +docker compose up -d +``` + +## Locking the Chatmail version + +> [!note] +> These steps are optional and should only be done if you are not satisfied that the service is installed each time the container starts. + +Since the current Docker version installs the Chatmail service every time the container starts, you can lock the container version after installation as follows: + +1. Commit the current state of the configured container: + +```shell +docker container commit chatmail configured-chatmail:$(date +'%Y-%m-%d') +docker image ls | grep configured-chatmail +``` + +2. Change the entrypoint for the container in `docker-compose.yaml` to: + +```yaml +services: + chatmail: + image: + volumes: + ... + ## custom resources + - ./custom/setup_chatmail_docker.sh:/setup_chatmail_docker.sh +``` + +3. Create the file `./custom/setup_chatmail_docker.sh` with the new configuration: + +```shell +mkdir -p ./custom +cat > ./custom/setup_chatmail_docker.sh << 'EOF' +#!/bin/bash + +set -eo pipefail + +export ENABLE_CERTS_MONITORING="${ENABLE_CERTS_MONITORING:-true}" +export CERTS_MONITORING_TIMEOUT="${CERTS_MONITORING_TIMEOUT:-60}" +export PATH_TO_SSL_CONTAINER="${PATH_TO_SSL_CONTAINER:-/var/lib/acme/live/${MAIL_DOMAIN}}" + +calculate_hash() { + find "$PATH_TO_SSL_CONTAINER" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' +} + +monitor_certificates() { + if [ "$ENABLE_CERTS_MONITORING" != "true" ]; then + echo "Certs monitoring disabled." + exit 0 + fi + + current_hash=$(calculate_hash) + previous_hash=$current_hash + + while true; do + current_hash=$(calculate_hash) + if [[ "$current_hash" != "$previous_hash" ]]; then + # TODO: add an option to restart at a specific time interval + echo "[INFO] Certificate's folder hash was changed, restarting nginx, dovecot and postfix services." + systemctl restart nginx.service + systemctl reload dovecot.service + systemctl reload postfix.service + previous_hash=$current_hash + fi + sleep $CERTS_MONITORING_TIMEOUT + done +} + +monitor_certificates & +EOF +``` + +4. Restart the service: + +```shell +docker compose down +docker compose up -d +``` diff --git a/docs/DOCKER_INSTALLATION_RU.md b/docs/DOCKER_INSTALLATION_RU.md new file mode 100644 index 00000000..f6224390 --- /dev/null +++ b/docs/DOCKER_INSTALLATION_RU.md @@ -0,0 +1,176 @@ +# Известные проблемы и ограничения +- Chatmail будет переустановлен при каждом запуске контейнера (при первом - долго, при последующих быстрее). Так устроен изначальный установщик, потому что он не был заточен под docker. В конце документации [представлено](#фиксирование-версии-chatmail) возможное решение +- Требуется настроенный в системе cgroups v2. Работа с cgroups v1 не тестировалась. +- Да, понятно дело что systemd использовать в контейнере костыль и надо это всё разнести на несколько сервисов, но это MVP и в первом приближении оказалось сделать проще так, чем переписывать всю систему развертывания. +- docker образ подходит только для amd64, если нужно запустить на другой архитектуре, попробуйте изменить dockerfile (конкретно ту часть что ответсвенна за установку dovecot) + +# Docker installation +Здесь представлена инструкция по установке chatmail с помощью docker-compose. + +## Предварительная настройка +We use `chat.example.org` as the chatmail domain in the following steps. +Please substitute it with your own domain. + +1. Настройте начальные записи DNS.Ниже приведен пример в привычном формате файла зоны BIND сTTL 1 час (3600 секунд). + Замените домен и IP-адреса на свои. + + ``` + 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. Склонируйте репозиторий на свой сервер. + + ```shell + git clone https://github.com/chatmail/relay + cd relay + ``` + +## Installation + +1. Скопировать файл `./docker/docker-compose-default.yaml` в `docker-compose.yaml`. Это нужно потому что `docker-compose.yaml` находится в `.gitignore` и не будет создавать конфликты при обновлении гит репозитория. +```shell +cp ./docker/docker-compose-default.yaml docker-compose.yaml +``` + +3. Настроить параметры ядра, потому что внутри контейнера их нельзя изменить, а конкретно `fs.inotify.max_user_instances` и `fs.inotify.max_user_watches`. Для этого выполнить следующее: +```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 +``` + +4. Настроить переменные окружения контейнера. Ниже перечислен список переменных учавствующих при развертывании. +- `MAIL_DOMAIN` - Доменное имя будущего сервера. (required) +- `DEBUG_COMMANDS_ENABLED` - Выполнить debug команды перед установкой. (default: `false`) +- `FORCE_REINIT_INI_FILE` - Пересоздавать ini файл конфигурации при запуске. (default: `false`) +- `USE_FOREIGN_CERT_MANAGER` - Использовать сторонний менеджер сертификатов. (default: `false`) +- `INI_FILE` - путь к ini файлу конфигурации. (default: `./chatmail.ini`) +- `PATH_TO_SSL_CONTAINER` - Путь где располагаются сертификаты. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) +- `ENABLE_CERTS_MONITORING` - Включить мониторинг сертификатов, если `USE_FOREIGN_CERT_MANAGER=true`. Если сертфикаты изменятся сервисы будут автоматически перезапущены. (default: `false`) +- `CERTS_MONITORING_TIMEOUT` - Раз во сколько секунд проверять что изменились сертификаты. (default: `'60'`) + +Также могут быть использованы все переменные из [ini файла конфигурации](https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/ini/chatmail.ini.f), они обязаны быть в uppercase формате. + +Ниже перечислены переменные, которые обязательны быть выставлены при развертывании через docker: +- `CHANGE_KERNEL_SETTINGS` - Менять настройки ядра (`fs.inotify.max_user_instances` и `fs.inotify.max_user_watches`) при запуске. При запуске в контейнере смена настроек ядра не может быть выполнена! (default: `False`) + +5. Настроить переменные окружения в `.env` файле. Эти переменные используются в `docker-compose.yaml` файле, чтобы передавать повторяющиеся значения. + +6. Собрать docker образ +```shell +docker compose build chatmail +``` + +7. Запустить docker compose и дождаться завершения установки +```shell +docker compose up -d # запуск сервиса +docker compose logs -f chatmail # просмотр логов контейнера. Для выхода нажать CTRL+C +``` + +8. По окончанию установки можно открыть в браузер `https://` + +## Использование кастомных файлов +При использовании docker есть возможность использовать измененые файлы конфигурации, чтобы сделать установку более персонализированной. Обычно это требуется для секции `www/src`, чтобы ознакомительная страница Chatmail была сделана на ваш вкус. Но также это можно использовать и для любых других случаев. + +Для того чтобы корректно выполнить подмену файлов необходимо +1. создать каталог `./custom`, он находится в `.gitignore`, поэтому при обновлении не вызовет конфликтов. +```shell +mkdir -p ./custom +``` + +2. Изменить нужный файл. Для примера возьмем `index.md` +```shell +mkdir -p ./custom/www/src +nano ./custom/www/src/index.md +``` + +3. В `docker-compose.yaml` добавить монтирование файла с помощью секции `volumes` +```yaml +services: + chatmail: + volumes: + ... + ## custom resources + - ./custom/www/src/index.md:/opt/chatmail/www/src/index.md +``` + +4. Перезапустить сервис +```shell +docker compose down +docker compose up -d +``` + +## Фиксирование версии Chatmail +> [!note] +> Это опциональные шаги, их делать требуется только если вас не устраивает что сервис устанавливается каждый раз при запуске + +Поскольку в текущей версии docker chatmail сервис устанавливается каждый раз запуске контейнера, чтобы этого не происходило можно зафиксировать версию контейнера после установки. Делается это следующим образом: + +1. Зафиксировать текущее состояние сконфигурированного контейнера +```shell +docker container commit chatmail configured-chatmail:$(date +'%Y-%m-%d') +docker image ls | grep configured-chatmail +``` + +2. Изменить entrypoint для контейнера в `docker-compose.yaml` на +```yaml +services: + chatmail: + image: + volumes: + ... + ## custom resources + - ./custom/setup_chatmail_docker.sh:/setup_chatmail_docker.sh +``` + +3. Создать файл `./custom/setup_chatmail_docker.sh` с новым файлом конфигурации +```shell +mkdir -p ./custom +cat > ./custom/setup_chatmail_docker.sh << 'EOF' +#!/bin/bash + +set -eo pipefail + +export ENABLE_CERTS_MONITORING="${ENABLE_CERTS_MONITORING:-true}" +export CERTS_MONITORING_TIMEOUT="${CERTS_MONITORING_TIMEOUT:-60}" +export PATH_TO_SSL_CONTAINER="${PATH_TO_SSL_CONTAINER:-/var/lib/acme/live/${MAIL_DOMAIN}}" + +calculate_hash() { + find "$PATH_TO_SSL_CONTAINER" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' +} + +monitor_certificates() { + if [ "$ENABLE_CERTS_MONITORING" != "true" ]; then + echo "Certs monitoring disabled." + exit 0 + fi + + current_hash=$(calculate_hash) + previous_hash=$current_hash + + while true; do + current_hash=$(calculate_hash) + if [[ "$current_hash" != "$previous_hash" ]]; then + # TODO: add an option to restart at a specific time interval + echo "[INFO] Certificate's folder hash was changed, restarting nginx, dovecot and postfix services." + systemctl restart nginx.service + systemctl reload dovecot.service + systemctl reload postfix.service + previous_hash=$current_hash + fi + sleep $CERTS_MONITORING_TIMEOUT + done +} + +monitor_certificates & +EOF +``` + +4. Перезапустить сервис +```shell +docker compose down +docker compose up -d +``` From 5c12f3b5851094c617f623721065ba3f5c4e57fc Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 15:26:00 +0300 Subject: [PATCH 02/14] rename dockerfile https://github.com/chatmail/relay/pull/614#discussion_r2270031966 --- .../{chatmail_server.dockerfile => chatmail_relay.dockerfile} | 0 docker/docker-compose-default.yaml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docker/{chatmail_server.dockerfile => chatmail_relay.dockerfile} (100%) diff --git a/docker/chatmail_server.dockerfile b/docker/chatmail_relay.dockerfile similarity index 100% rename from docker/chatmail_server.dockerfile rename to docker/chatmail_relay.dockerfile diff --git a/docker/docker-compose-default.yaml b/docker/docker-compose-default.yaml index 61e7765f..cfdc3a55 100644 --- a/docker/docker-compose-default.yaml +++ b/docker/docker-compose-default.yaml @@ -2,7 +2,7 @@ services: chatmail: build: context: ./docker - dockerfile: chatmail_server.dockerfile + dockerfile: chatmail_relay.dockerfile tags: - chatmail-relay:latest image: chatmail-relay:latest From 57598dbf9c712fbcaa0bf5d1c836437b1927cf22 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 15:27:30 +0300 Subject: [PATCH 03/14] add port 80 to docker-compose-default https://github.com/chatmail/relay/pull/614#discussion_r2279656441 --- docker/docker-compose-default.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/docker/docker-compose-default.yaml b/docker/docker-compose-default.yaml index cfdc3a55..be29e4a6 100644 --- a/docker/docker-compose-default.yaml +++ b/docker/docker-compose-default.yaml @@ -32,6 +32,7 @@ services: # CERTS_MONITORING_TIMEOUT: 10 # IS_DEVELOPMENT_INSTANCE: "True" ports: + - "80:80" - "25:25" - "587:587" - "143:143" From c83d1cf4f32c2d3af3656f431c8735c4d314da89 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 15:28:44 +0300 Subject: [PATCH 04/14] add 465 port https://github.com/chatmail/relay/pull/614#discussion_r2279707059 --- docker/docker-compose-default.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docker/docker-compose-default.yaml b/docker/docker-compose-default.yaml index be29e4a6..33f5c6d5 100644 --- a/docker/docker-compose-default.yaml +++ b/docker/docker-compose-default.yaml @@ -33,11 +33,12 @@ services: # IS_DEVELOPMENT_INSTANCE: "True" ports: - "80:80" + - "443:443" - "25:25" - "587:587" - "143:143" + - "465:465" - "993:993" - - "443:443" volumes: ## system - /sys/fs/cgroup:/sys/fs/cgroup:rw # required for systemd From 54e268faef4e3b0c2149e380f1ce286aae2cb1bc Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 15:37:18 +0300 Subject: [PATCH 05/14] add RECREATE_VENV var https://github.com/chatmail/relay/pull/614#discussion_r2279742769 --- docker/docker-compose-default.yaml | 4 ++-- docker/files/setup_chatmail_docker.sh | 4 ++++ docs/DOCKER_INSTALLATION_EN.md | 1 + docs/DOCKER_INSTALLATION_RU.md | 1 + 4 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docker/docker-compose-default.yaml b/docker/docker-compose-default.yaml index 33f5c6d5..4edfbe55 100644 --- a/docker/docker-compose-default.yaml +++ b/docker/docker-compose-default.yaml @@ -23,8 +23,8 @@ services: MAIL_DOMAIN: CHANGE_KERNEL_SETTINGS: "False" ACME_EMAIL: - - MAX_MESSAGE_SIZE: "50M" + # RECREATE_VENV: "false" + # MAX_MESSAGE_SIZE: "50M" # DEBUG_COMMANDS_ENABLED: "true" # FORCE_REINIT_INI_FILE: "true" # USE_FOREIGN_CERT_MANAGER: "True" diff --git a/docker/files/setup_chatmail_docker.sh b/docker/files/setup_chatmail_docker.sh index 7e101791..bdff4984 100755 --- a/docker/files/setup_chatmail_docker.sh +++ b/docker/files/setup_chatmail_docker.sh @@ -6,6 +6,7 @@ export ENABLE_CERTS_MONITORING="${ENABLE_CERTS_MONITORING:-true}" export CERTS_MONITORING_TIMEOUT="${CERTS_MONITORING_TIMEOUT:-60}" export PATH_TO_SSL_CONTAINER="${PATH_TO_SSL_CONTAINER:-/var/lib/acme/live/${MAIL_DOMAIN}}" export CHANGE_KERNEL_SETTINGS=${CHANGE_KERNEL_SETTINGS:-"False"} +export RECREATE_VENV=${RECREATE_VENV:-"false"} if [ -z "$MAIL_DOMAIN" ]; then echo "ERROR: Environment variable 'MAIL_DOMAIN' must be set!" >&2 @@ -61,6 +62,9 @@ chown opendkim:opendkim /etc/dkimkeys/opendkim.txt # TODO: Move to debug_commands after git clone is moved to dockerfile. git config --global --add safe.directory /opt/chatmail +if [ "$RECREATE_VENV" == "true" ]; then + rm -rf venv +fi ./scripts/initenv.sh ./scripts/cmdeploy init --config "${INI_FILE}" $INI_CMD_ARGS $MAIL_DOMAIN diff --git a/docs/DOCKER_INSTALLATION_EN.md b/docs/DOCKER_INSTALLATION_EN.md index 86ff727a..ab2ef97e 100644 --- a/docs/DOCKER_INSTALLATION_EN.md +++ b/docs/DOCKER_INSTALLATION_EN.md @@ -53,6 +53,7 @@ sudo sysctl --system - `DEBUG_COMMANDS_ENABLED` – Run debug commands before installation. (default: `false`) - `FORCE_REINIT_INI_FILE` – Recreate the ini configuration file on startup. (default: `false`) - `USE_FOREIGN_CERT_MANAGER` – Use a third-party certificate manager. (default: `false`) +- `RECREATE_VENV` - Recreate the virtual environment (venv). If set to `true`, the environment will be recreated when the container starts, which will increase the startup time of the service but can help avoid certain errors. (default: `false`) - `INI_FILE` – Path to the ini configuration file. (default: `./chatmail.ini`) - `PATH_TO_SSL_CONTAINER` – Path to where the certificates are stored. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) - `ENABLE_CERTS_MONITORING` – Enable certificate monitoring if `USE_FOREIGN_CERT_MANAGER=true`. If certificates change, services will be automatically restarted. (default: `false`) diff --git a/docs/DOCKER_INSTALLATION_RU.md b/docs/DOCKER_INSTALLATION_RU.md index f6224390..329ed28c 100644 --- a/docs/DOCKER_INSTALLATION_RU.md +++ b/docs/DOCKER_INSTALLATION_RU.md @@ -47,6 +47,7 @@ sudo sysctl --system - `DEBUG_COMMANDS_ENABLED` - Выполнить debug команды перед установкой. (default: `false`) - `FORCE_REINIT_INI_FILE` - Пересоздавать ini файл конфигурации при запуске. (default: `false`) - `USE_FOREIGN_CERT_MANAGER` - Использовать сторонний менеджер сертификатов. (default: `false`) +- `RECREATE_VENV` - Пересоздать виртуальное окружение (venv). Если выставлено `true`, то окружение будет пересоздано при запуске контейнера, из-за чего включение сервиса займет больше времени, но поможет избежать ряда ошибок. (default: `false`) - `INI_FILE` - путь к ini файлу конфигурации. (default: `./chatmail.ini`) - `PATH_TO_SSL_CONTAINER` - Путь где располагаются сертификаты. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) - `ENABLE_CERTS_MONITORING` - Включить мониторинг сертификатов, если `USE_FOREIGN_CERT_MANAGER=true`. Если сертфикаты изменятся сервисы будут автоматически перезапущены. (default: `false`) From ce2b536ebe7c35ee91a00a00e6b946c0be3b66da Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 18:06:53 +0300 Subject: [PATCH 06/14] change "restart nginx" to "reload nginx" https://github.com/chatmail/relay/pull/614#discussion_r2269896158 --- docker/files/setup_chatmail_docker.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docker/files/setup_chatmail_docker.sh b/docker/files/setup_chatmail_docker.sh index bdff4984..f3fb4d4f 100755 --- a/docker/files/setup_chatmail_docker.sh +++ b/docker/files/setup_chatmail_docker.sh @@ -36,8 +36,8 @@ monitor_certificates() { current_hash=$(calculate_hash) if [[ "$current_hash" != "$previous_hash" ]]; then # TODO: add an option to restart at a specific time interval - echo "[INFO] Certificate's folder hash was changed, restarting nginx, dovecot and postfix services." - systemctl restart nginx.service + echo "[INFO] Certificate's folder hash was changed, reloading nginx, dovecot and postfix services." + systemctl reload nginx.service systemctl reload dovecot.service systemctl reload postfix.service previous_hash=$current_hash From c7a316806c7c74bc2a1637b518dfd9ffd4dba619 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 18:16:33 +0300 Subject: [PATCH 07/14] pass values to `MAIL_DOMAIN` and `ACME_EMAIL` from vars for docker-compose-default https://github.com/chatmail/relay/pull/614#discussion_r2279591922 --- docker/docker-compose-default.yaml | 4 ++-- docs/DOCKER_INSTALLATION_EN.md | 8 ++++---- docs/DOCKER_INSTALLATION_RU.md | 8 ++++---- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docker/docker-compose-default.yaml b/docker/docker-compose-default.yaml index 4edfbe55..104c2bfa 100644 --- a/docker/docker-compose-default.yaml +++ b/docker/docker-compose-default.yaml @@ -20,9 +20,9 @@ services: max-size: "10m" max-file: "3" environment: - MAIL_DOMAIN: + MAIL_DOMAIN: $MAIL_DOMAIN CHANGE_KERNEL_SETTINGS: "False" - ACME_EMAIL: + ACME_EMAIL: $ACME_EMAIL # RECREATE_VENV: "false" # MAX_MESSAGE_SIZE: "50M" # DEBUG_COMMANDS_ENABLED: "true" diff --git a/docs/DOCKER_INSTALLATION_EN.md b/docs/DOCKER_INSTALLATION_EN.md index ab2ef97e..92354739 100644 --- a/docs/DOCKER_INSTALLATION_EN.md +++ b/docs/DOCKER_INSTALLATION_EN.md @@ -39,7 +39,9 @@ Please substitute it with your own domain. cp ./docker/docker-compose-default.yaml docker-compose.yaml ``` -3. 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: +3. Configure environment variables in the `.env` file. These variables are used in the `docker-compose.yaml` file to pass repeated values. + +4. 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 @@ -47,7 +49,7 @@ echo "fs.inotify.max_user_watches=65536" | sudo tee -a /etc/sysctl.d/99-inotify. sudo sysctl --system ``` -4. Configure container environment variables. Below is the list of variables used during deployment: +5. Configure container environment variables. Below is the list of variables used during deployment: - `MAIL_DOMAIN` – The domain name of the future server. (required) - `DEBUG_COMMANDS_ENABLED` – Run debug commands before installation. (default: `false`) @@ -65,8 +67,6 @@ Mandatory variables for deployment via Docker: - `CHANGE_KERNEL_SETTINGS` – Change kernel settings (`fs.inotify.max_user_instances` and `fs.inotify.max_user_watches`) on startup. Changing kernel settings inside the container is not possible! (default: `False`) -5. Configure environment variables in the `.env` file. These variables are used in the `docker-compose.yaml` file to pass repeated values. - 6. Build the Docker image: ```shell diff --git a/docs/DOCKER_INSTALLATION_RU.md b/docs/DOCKER_INSTALLATION_RU.md index 329ed28c..1c715fdd 100644 --- a/docs/DOCKER_INSTALLATION_RU.md +++ b/docs/DOCKER_INSTALLATION_RU.md @@ -35,14 +35,16 @@ Please substitute it with your own domain. cp ./docker/docker-compose-default.yaml docker-compose.yaml ``` -3. Настроить параметры ядра, потому что внутри контейнера их нельзя изменить, а конкретно `fs.inotify.max_user_instances` и `fs.inotify.max_user_watches`. Для этого выполнить следующее: +3. Настроить переменные окружения в `.env` файле. Эти переменные используются в `docker-compose.yaml` файле, чтобы передавать повторяющиеся значения. + +4. Настроить параметры ядра, потому что внутри контейнера их нельзя изменить, а конкретно `fs.inotify.max_user_instances` и `fs.inotify.max_user_watches`. Для этого выполнить следующее: ```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 ``` -4. Настроить переменные окружения контейнера. Ниже перечислен список переменных учавствующих при развертывании. +5. Настроить переменные окружения контейнера. Ниже перечислен список переменных учавствующих при развертывании. - `MAIL_DOMAIN` - Доменное имя будущего сервера. (required) - `DEBUG_COMMANDS_ENABLED` - Выполнить debug команды перед установкой. (default: `false`) - `FORCE_REINIT_INI_FILE` - Пересоздавать ini файл конфигурации при запуске. (default: `false`) @@ -58,8 +60,6 @@ sudo sysctl --system Ниже перечислены переменные, которые обязательны быть выставлены при развертывании через docker: - `CHANGE_KERNEL_SETTINGS` - Менять настройки ядра (`fs.inotify.max_user_instances` и `fs.inotify.max_user_watches`) при запуске. При запуске в контейнере смена настроек ядра не может быть выполнена! (default: `False`) -5. Настроить переменные окружения в `.env` файле. Эти переменные используются в `docker-compose.yaml` файле, чтобы передавать повторяющиеся значения. - 6. Собрать docker образ ```shell docker compose build chatmail From 128cca0bae8cee21734364bae6712aad48b82ad9 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 21:30:08 +0300 Subject: [PATCH 08/14] Fix bug with attaching certs --- docker/example.env | 2 -- docker/files/entrypoint.sh | 11 ----------- docker/files/setup_chatmail_docker.sh | 4 ++-- docs/DOCKER_INSTALLATION_EN.md | 6 +++--- docs/DOCKER_INSTALLATION_RU.md | 6 +++--- 5 files changed, 8 insertions(+), 21 deletions(-) diff --git a/docker/example.env b/docker/example.env index ef8ca28a..48655812 100644 --- a/docker/example.env +++ b/docker/example.env @@ -1,3 +1 @@ MAIL_DOMAIN="chat.example.com" - -PATH_TO_SSL_CONTAINER="/var/lib/acme/live/${MAIL_DOMAIN}" diff --git a/docker/files/entrypoint.sh b/docker/files/entrypoint.sh index b704c2e3..2bc5d76f 100755 --- a/docker/files/entrypoint.sh +++ b/docker/files/entrypoint.sh @@ -1,17 +1,6 @@ #!/bin/bash set -eo pipefail -if [ "${USE_FOREIGN_CERT_MANAGER,,}" == "true" ]; then - if [ ! -f "$PATH_TO_SSL_CONTAINER/fullchain" ]; then - echo "Error: file '$PATH_TO_SSL_CONTAINER/fullchain' does not exist. Exiting..." > /dev/stderr - exit 1 - fi - if [ ! -f "$PATH_TO_SSL_CONTAINER/privkey" ]; then - echo "Error: file '$PATH_TO_SSL_CONTAINER/privkey' does not exist. Exiting..." > /dev/stderr - exit 1 - fi -fi - SETUP_CHATMAIL_SERVICE_PATH="${SETUP_CHATMAIL_SERVICE_PATH:-/lib/systemd/system/setup_chatmail.service}" env_vars=$(printenv | cut -d= -f1 | xargs) diff --git a/docker/files/setup_chatmail_docker.sh b/docker/files/setup_chatmail_docker.sh index f3fb4d4f..50f1e4ca 100755 --- a/docker/files/setup_chatmail_docker.sh +++ b/docker/files/setup_chatmail_docker.sh @@ -4,7 +4,7 @@ set -eo pipefail export INI_FILE="${INI_FILE:-chatmail.ini}" export ENABLE_CERTS_MONITORING="${ENABLE_CERTS_MONITORING:-true}" export CERTS_MONITORING_TIMEOUT="${CERTS_MONITORING_TIMEOUT:-60}" -export PATH_TO_SSL_CONTAINER="${PATH_TO_SSL_CONTAINER:-/var/lib/acme/live/${MAIL_DOMAIN}}" +export PATH_TO_SSL="${PATH_TO_SSL:-/var/lib/acme/live/${MAIL_DOMAIN}}" export CHANGE_KERNEL_SETTINGS=${CHANGE_KERNEL_SETTINGS:-"False"} export RECREATE_VENV=${RECREATE_VENV:-"false"} @@ -20,7 +20,7 @@ debug_commands() { } calculate_hash() { - find "$PATH_TO_SSL_CONTAINER" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' + find "$PATH_TO_SSL" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' } monitor_certificates() { diff --git a/docs/DOCKER_INSTALLATION_EN.md b/docs/DOCKER_INSTALLATION_EN.md index 92354739..0a2e4a3e 100644 --- a/docs/DOCKER_INSTALLATION_EN.md +++ b/docs/DOCKER_INSTALLATION_EN.md @@ -57,7 +57,7 @@ sudo sysctl --system - `USE_FOREIGN_CERT_MANAGER` – Use a third-party certificate manager. (default: `false`) - `RECREATE_VENV` - Recreate the virtual environment (venv). If set to `true`, the environment will be recreated when the container starts, which will increase the startup time of the service but can help avoid certain errors. (default: `false`) - `INI_FILE` – Path to the ini configuration file. (default: `./chatmail.ini`) -- `PATH_TO_SSL_CONTAINER` – Path to where the certificates are stored. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) +- `PATH_TO_SSL` – Path to where the certificates are stored. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) - `ENABLE_CERTS_MONITORING` – Enable certificate monitoring if `USE_FOREIGN_CERT_MANAGER=true`. If certificates change, services will be automatically restarted. (default: `false`) - `CERTS_MONITORING_TIMEOUT` – Interval in seconds to check if certificates have changed. (default: `'60'`) @@ -156,10 +156,10 @@ set -eo pipefail export ENABLE_CERTS_MONITORING="${ENABLE_CERTS_MONITORING:-true}" export CERTS_MONITORING_TIMEOUT="${CERTS_MONITORING_TIMEOUT:-60}" -export PATH_TO_SSL_CONTAINER="${PATH_TO_SSL_CONTAINER:-/var/lib/acme/live/${MAIL_DOMAIN}}" +export PATH_TO_SSL="${PATH_TO_SSL:-/var/lib/acme/live/${MAIL_DOMAIN}}" calculate_hash() { - find "$PATH_TO_SSL_CONTAINER" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' + find "$PATH_TO_SSL" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' } monitor_certificates() { diff --git a/docs/DOCKER_INSTALLATION_RU.md b/docs/DOCKER_INSTALLATION_RU.md index 1c715fdd..f05a6382 100644 --- a/docs/DOCKER_INSTALLATION_RU.md +++ b/docs/DOCKER_INSTALLATION_RU.md @@ -51,7 +51,7 @@ sudo sysctl --system - `USE_FOREIGN_CERT_MANAGER` - Использовать сторонний менеджер сертификатов. (default: `false`) - `RECREATE_VENV` - Пересоздать виртуальное окружение (venv). Если выставлено `true`, то окружение будет пересоздано при запуске контейнера, из-за чего включение сервиса займет больше времени, но поможет избежать ряда ошибок. (default: `false`) - `INI_FILE` - путь к ini файлу конфигурации. (default: `./chatmail.ini`) -- `PATH_TO_SSL_CONTAINER` - Путь где располагаются сертификаты. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) +- `PATH_TO_SSL` - Путь где располагаются сертификаты. (default: `/var/lib/acme/live/${MAIL_DOMAIN}`) - `ENABLE_CERTS_MONITORING` - Включить мониторинг сертификатов, если `USE_FOREIGN_CERT_MANAGER=true`. Если сертфикаты изменятся сервисы будут автоматически перезапущены. (default: `false`) - `CERTS_MONITORING_TIMEOUT` - Раз во сколько секунд проверять что изменились сертификаты. (default: `'60'`) @@ -137,10 +137,10 @@ set -eo pipefail export ENABLE_CERTS_MONITORING="${ENABLE_CERTS_MONITORING:-true}" export CERTS_MONITORING_TIMEOUT="${CERTS_MONITORING_TIMEOUT:-60}" -export PATH_TO_SSL_CONTAINER="${PATH_TO_SSL_CONTAINER:-/var/lib/acme/live/${MAIL_DOMAIN}}" +export PATH_TO_SSL="${PATH_TO_SSL:-/var/lib/acme/live/${MAIL_DOMAIN}}" calculate_hash() { - find "$PATH_TO_SSL_CONTAINER" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' + find "$PATH_TO_SSL" -type f -exec sha1sum {} \; | sort | sha1sum | awk '{print $1}' } monitor_certificates() { From c0efe81d14afb110f11adc9a3ca334a7424188d0 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 21:36:16 +0300 Subject: [PATCH 09/14] fix docs - nginx "restart" to "reload" https://github.com/chatmail/relay/pull/614#discussion_r2269896158 --- docs/DOCKER_INSTALLATION_EN.md | 4 ++-- docs/DOCKER_INSTALLATION_RU.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/DOCKER_INSTALLATION_EN.md b/docs/DOCKER_INSTALLATION_EN.md index 0a2e4a3e..7a66e456 100644 --- a/docs/DOCKER_INSTALLATION_EN.md +++ b/docs/DOCKER_INSTALLATION_EN.md @@ -175,8 +175,8 @@ monitor_certificates() { current_hash=$(calculate_hash) if [[ "$current_hash" != "$previous_hash" ]]; then # TODO: add an option to restart at a specific time interval - echo "[INFO] Certificate's folder hash was changed, restarting nginx, dovecot and postfix services." - systemctl restart nginx.service + echo "[INFO] Certificate's folder hash was changed, reloading nginx, dovecot and postfix services." + systemctl reload nginx.service systemctl reload dovecot.service systemctl reload postfix.service previous_hash=$current_hash diff --git a/docs/DOCKER_INSTALLATION_RU.md b/docs/DOCKER_INSTALLATION_RU.md index f05a6382..e90cf889 100644 --- a/docs/DOCKER_INSTALLATION_RU.md +++ b/docs/DOCKER_INSTALLATION_RU.md @@ -156,8 +156,8 @@ monitor_certificates() { current_hash=$(calculate_hash) if [[ "$current_hash" != "$previous_hash" ]]; then # TODO: add an option to restart at a specific time interval - echo "[INFO] Certificate's folder hash was changed, restarting nginx, dovecot and postfix services." - systemctl restart nginx.service + echo "[INFO] Certificate's folder hash was changed, reloading nginx, dovecot and postfix services." + systemctl reload nginx.service systemctl reload dovecot.service systemctl reload postfix.service previous_hash=$current_hash From a67184c8dddf985c8740ff819b058dab475cbbe1 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sat, 23 Aug 2025 22:47:32 +0300 Subject: [PATCH 10/14] Delete ssh connection from docker installation - https://github.com/chatmail/relay/pull/614#discussion_r2269986372 - https://github.com/chatmail/relay/pull/614#discussion_r2269991175 - https://github.com/chatmail/relay/pull/614#discussion_r2269995037 - https://github.com/chatmail/relay/pull/614#discussion_r2270004922 --- docker/chatmail_relay.dockerfile | 19 ------------------- docker/files/setup_chatmail_docker.sh | 2 +- 2 files changed, 1 insertion(+), 20 deletions(-) diff --git a/docker/chatmail_relay.dockerfile b/docker/chatmail_relay.dockerfile index 72c4a042..3ec5f81e 100644 --- a/docker/chatmail_relay.dockerfile +++ b/docker/chatmail_relay.dockerfile @@ -18,8 +18,6 @@ RUN echo 'APT::Install-Recommends "0";' > /etc/apt/apt.conf.d/01norecommend && \ RUN apt-get update && \ apt-get install -y \ - openssh-client \ - openssh-server \ git \ python3 \ python3-venv \ @@ -54,23 +52,6 @@ RUN apt-get update && \ done \ && rm -rf /var/lib/apt/lists/* -RUN systemctl enable \ - ssh \ - fcgiwrap - -RUN sed -i 's/^#PasswordAuthentication .*/PasswordAuthentication no/' /etc/ssh/sshd_config && \ - sed -i 's/^#PermitRootLogin .*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config && \ - ssh-keygen -P "" -t rsa -b 2048 -f /root/.ssh/id_rsa && \ - mkdir -p /root/.ssh && \ - cat /root/.ssh/id_rsa.pub >> /root/.ssh/authorized_keys && \ - SSH_USER_CONFIG="/root/.ssh/config" && \ - echo "Host localhost" > "$SSH_USER_CONFIG" && \ - echo " HostName localhost" >> "$SSH_USER_CONFIG" && \ - echo " User root" >> "$SSH_USER_CONFIG" && \ - echo " StrictHostKeyChecking no" >> "$SSH_USER_CONFIG" && \ - echo " UserKnownHostsFile /dev/null" >> "$SSH_USER_CONFIG" - ## TODO: deny access for all insteed root form 127.0.0.1 https://unix.stackexchange.com/a/406264 - WORKDIR /opt/chatmail ARG SETUP_CHATMAIL_SERVICE_PATH=/lib/systemd/system/setup_chatmail.service diff --git a/docker/files/setup_chatmail_docker.sh b/docker/files/setup_chatmail_docker.sh index 50f1e4ca..dafeb2df 100755 --- a/docker/files/setup_chatmail_docker.sh +++ b/docker/files/setup_chatmail_docker.sh @@ -70,7 +70,7 @@ fi ./scripts/cmdeploy init --config "${INI_FILE}" $INI_CMD_ARGS $MAIL_DOMAIN bash /update_ini.sh -./scripts/cmdeploy run --ssh-host localhost --skip-dns-check +./scripts/cmdeploy run --ssh-host docker --skip-dns-check echo "ForwardToConsole=yes" >> /etc/systemd/journald.conf systemctl restart systemd-journald From ea5332792303d8bec11e554afe87c28b09b2a9de Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Sun, 24 Aug 2025 16:14:45 +0300 Subject: [PATCH 11/14] Fix issue with acmetool - https://github.com/chatmail/relay/pull/614#discussion_r2279630626 --- docker/docker-compose-default.yaml | 1 - docker/files/entrypoint.sh | 2 ++ 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docker/docker-compose-default.yaml b/docker/docker-compose-default.yaml index 104c2bfa..224ac938 100644 --- a/docker/docker-compose-default.yaml +++ b/docker/docker-compose-default.yaml @@ -43,7 +43,6 @@ services: ## system - /sys/fs/cgroup:/sys/fs/cgroup:rw # required for systemd - ./:/opt/chatmail - - ./data/acme:/var/lib/acme ## data - ./data/chatmail:/home diff --git a/docker/files/entrypoint.sh b/docker/files/entrypoint.sh index 2bc5d76f..3a2fb191 100755 --- a/docker/files/entrypoint.sh +++ b/docker/files/entrypoint.sh @@ -1,6 +1,8 @@ #!/bin/bash set -eo pipefail +unlink /etc/nginx/sites-enabled/default + SETUP_CHATMAIL_SERVICE_PATH="${SETUP_CHATMAIL_SERVICE_PATH:-/lib/systemd/system/setup_chatmail.service}" env_vars=$(printenv | cut -d= -f1 | xargs) From c1c07de39cb824969a0f36322b18fe03e514b897 Mon Sep 17 00:00:00 2001 From: Keonik1 Date: Mon, 25 Aug 2025 22:07:40 +0300 Subject: [PATCH 12/14] fix unlink if default nginx conf is not exist - https://github.com/chatmail/relay/pull/614#discussion_r2297828830 --- docker/files/entrypoint.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/files/entrypoint.sh b/docker/files/entrypoint.sh index 3a2fb191..bce52a56 100755 --- a/docker/files/entrypoint.sh +++ b/docker/files/entrypoint.sh @@ -1,7 +1,7 @@ #!/bin/bash set -eo pipefail -unlink /etc/nginx/sites-enabled/default +unlink /etc/nginx/sites-enabled/default || true SETUP_CHATMAIL_SERVICE_PATH="${SETUP_CHATMAIL_SERVICE_PATH:-/lib/systemd/system/setup_chatmail.service}" From 8537a0755046038ef934ad944b6a33b7bf8e2343 Mon Sep 17 00:00:00 2001 From: missytake Date: Tue, 26 Aug 2025 10:46:48 +0200 Subject: [PATCH 13/14] docker: enable DNS checks before cmdeploy run again --- docker/files/setup_chatmail_docker.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/files/setup_chatmail_docker.sh b/docker/files/setup_chatmail_docker.sh index dafeb2df..6e06d98f 100755 --- a/docker/files/setup_chatmail_docker.sh +++ b/docker/files/setup_chatmail_docker.sh @@ -70,7 +70,7 @@ fi ./scripts/cmdeploy init --config "${INI_FILE}" $INI_CMD_ARGS $MAIL_DOMAIN bash /update_ini.sh -./scripts/cmdeploy run --ssh-host docker --skip-dns-check +./scripts/cmdeploy run --ssh-host docker echo "ForwardToConsole=yes" >> /etc/systemd/journald.conf systemctl restart systemd-journald From 8541139867750e3e029c1d0c2087a4bb38787ace Mon Sep 17 00:00:00 2001 From: missytake Date: Wed, 8 Oct 2025 12:34:57 +0200 Subject: [PATCH 14/14] README: docker compose support is experimental --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4324d156..5a6ae81e 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,10 @@ Please substitute it with your own domain. (it can take some time until they are public). ### Docker installation -Installation using docker compose is presented [here](./docs/DOCKER_INSTALLATION_EN.md) + +We have experimental support for [docker compose](./docs/DOCKER_INSTALLATION_EN.md), +but it is not covered by automated tests yet, +so don't expect everything to work. ### Other helpful commands