feat: serve an APPVERSIONS.json index file to clients via IMAP metadata

This is designed to help implement self-updating APKs (and later other clients), see counterpart https://github.com/chatmail/core/pull/8557
2026-08-12 11:30:52 +00:00 · 2026-08-12 10:21:56 +02:00
14 changed files with 218 additions and 197 deletions
@@ -8,7 +8,7 @@ name: Trigger Docker build

 on:
  push:
-    branches: [main, j4n/dovecot-multidist]
+    branches: [main]
    tags: ['[0-9]+.[0-9]+.[0-9]+']
  workflow_dispatch:

@@ -0,0 +1,15 @@
+{
+  "clients": [
+    {
+      "clientId": "deltachat",
+      "sources": [
+        {
+          "sourceId": "gplay",
+          "versionInteger": 754,
+          "versionString": "2.57.0",
+          "downloadUrl": "https://github.com/deltachat/deltachat-android/releases/download/v2.57.0/deltachat-gplay-release-2.57.0.apk"
+        }
+      ]
+    }
+  ]
+}
@@ -5,3 +5,6 @@ We use [git-cliff] to generate the changelog from commit messages before the rel

 [Conventional Commits]: https://www.conventionalcommits.org/
 [git-cliff]: https://git-cliff.org/
+
+To update client app version information,
+edit [APPVERSIONS.json](APPVERSIONS.json).
@@ -63,6 +63,9 @@ class Config:
        self.turn_socket_path = params.pop(
            "turn_socket_path", "/run/chatmail-turn/turn.socket"
        )
+        self.appversions_path = Path(
+            params.pop("appversions_path", "/usr/local/lib/chatmaild/appversions.json")
+        )
        iroh_relay = params.pop("iroh_relay", None)
        if iroh_relay is None:
            self.iroh_relay = "https://" + raw_domain
@@ -1,3 +1,4 @@
+import json
 import logging
 import socket
 import sys
@@ -18,6 +19,18 @@ def turn_credentials(turn_socket_path):
            return file.readline().decode("utf-8").strip()


+def read_appversions(path):
+    try:
+        data = json.loads(path.read_bytes())
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError):
+        logging.exception(f"failed to read {path}")
+        return None
+    # the dict protocol is line-based, keep the value single-line
+    return json.dumps(data, separators=(",", ":"))
+
+
 def _is_valid_token_timestamp(timestamp, now):
    # Token if invalid after 90 days
    # or if the timestamp is in the future.
@@ -94,6 +107,7 @@ class MetadataDictProxy(DictProxy):
        iroh_relay=None,
        turn_hostname=None,
        turn_socket_path=None,
+        appversions_path=None,
    ):
        super().__init__()
        self.notifier = notifier
@@ -101,6 +115,7 @@ class MetadataDictProxy(DictProxy):
        self.iroh_relay = iroh_relay
        self.turn_hostname = turn_hostname
        self.turn_socket_path = turn_socket_path
+        self.appversions_path = appversions_path

    def handle_lookup(self, parts):
        # Lpriv/43f5f508a7ea0366dff30200c15250e3/devicetoken\tlkj123poi@c2.testrun.org
@@ -125,6 +140,9 @@ class MetadataDictProxy(DictProxy):
                        case "maxsmtprecipients":
                            # postfix default  (see "postconf smtpd_recipient_limit")
                            return "O1000\n"
+                        case "appversions" if self.appversions_path:
+                            value = read_appversions(self.appversions_path)
+                            return f"O{value}\n" if value else "N\n"

        logging.warning(f"lookup ignored: {parts!r}")
        return "N\n"
@@ -170,6 +188,7 @@ def main():
        iroh_relay=iroh_relay,
        turn_hostname=mail_domain,
        turn_socket_path=socket_path,
+        appversions_path=config.appversions_path,
    )

    dictproxy.serve_forever_from_socket(socket)
@@ -47,6 +47,9 @@ def test_read_config_basic_using_defaults(tmp_path, maildomain):
    assert example_config.password_min_length == 9
    assert example_config.max_imap_connections == 10000
    assert example_config.max_smtp_connections == 1000
+    assert str(example_config.appversions_path) == (
+        "/usr/local/lib/chatmaild/appversions.json"
+    )
    assert example_config._unused_keys == []


@@ -7,6 +7,7 @@ import requests
 from chatmaild.metadata import (
    Metadata,
    MetadataDictProxy,
+    read_appversions,
 )
 from chatmaild.notifier import (
    Notifier,
@@ -369,6 +370,17 @@ def test_iroh_relay(dictproxy):
    assert wfile.getvalue() == b"Ohttps://example.org/\n"


+def test_read_appversions(tmp_path):
+    path = tmp_path.joinpath("appversions.json")
+    assert read_appversions(path) is None
+
+    path.write_text('{\n  "clients": []\n}')
+    assert read_appversions(path) == '{"clients":[]}'
+
+    path.write_text("bad json")
+    assert read_appversions(path) is None
+
+
 def test_legacy_token_migration(metadata, testaddr):
    with metadata.get_metadata_dict(testaddr).modify() as data:
        data[metadata.DEVICETOKEN_KEY] = ["oldtoken1", "oldtoken2"]
@@ -35,7 +35,7 @@ from .nginx.deployer import NginxDeployer
 from .opendkim.deployer import OpendkimDeployer
 from .postfix.deployer import PostfixDeployer
 from .selfsigned.deployer import SelfSignedTlsDeployer
-from .www import build_webpages, find_merge_conflict, get_paths
+from .www import build_webpages, find_merge_conflict, get_paths, get_reporoot


 class Port(FactBase):
@@ -98,23 +98,6 @@ def _install_remote_venv_with_chatmaild(deployer) -> None:
        dest=remote_dist_file,
    )

-    # Remove venv if its Python major.minor doesn't match the system Python
-    server.shell(
-        name="remove stale chatmaild venv if python version changed",
-        commands=[
-            "\n".join(
-                [
-                    r"re='[0-9]+\.[0-9]+'",  # major.minor out of 'Python X.Y.Z'
-                    'sys_version=$(python3 --version 2>/dev/null | grep -oE "$re")',
-                    f'venv_version=$({remote_venv_dir}/bin/python --version 2>/dev/null | grep -oE "$re")',
-                    # an empty sys_version means we could not tell: keep the venv
-                    f'[ -z "$sys_version" ] || [ "$sys_version" = "$venv_version" ] '
-                    f"|| rm -rf {remote_venv_dir}",
-                ]
-            )
-        ],
-    )
-
    pip.virtualenv(
        name=f"chatmaild virtualenv {remote_venv_dir}",
        path=remote_venv_dir,
@@ -143,6 +126,11 @@ def _configure_remote_venv_with_chatmaild(deployer, config) -> None:
        dest=remote_chatmail_inipath,
    )

+    deployer.put_file(
+        src=get_reporoot().joinpath("APPVERSIONS.json").open("rb"),
+        dest=str(config.appversions_path),
+    )
+
    deployer.remove_file("/etc/cron.d/chatmail-metrics")
    deployer.remove_file("/var/www/html/metrics")

@@ -423,12 +411,6 @@ class ChatmailDeployer(Deployer):
            src=BytesIO(b'APT::Install-Recommends "false";\n'),
            dest="/etc/apt/apt.conf.d/00InstallRecommends",
        )
-        # Pin dovecot-* to priority -1 before any apt operation, apt should
-        # never manage dovecot as our version might be lower than the distro's.
-        self.put_file(
-            src=StringIO("Package: dovecot-*\nPin: version *\nPin-Priority: -1\n"),
-            dest="/etc/apt/preferences.d/pin-dovecot",
-        )
        apt.update(name="apt update", cache_time=24 * 3600)
        apt.upgrade(name="upgrade apt packages", auto_remove=True)

@@ -1,10 +1,11 @@
+import io
 import urllib.request

 from chatmaild.config import Config
 from pyinfra import host
 from pyinfra.facts.deb import DebPackages
 from pyinfra.facts.server import Arch, Command, Sysctl
-from pyinfra.operations import files, server
+from pyinfra.operations import apt, files, server

 from cmdeploy.basedeploy import (
    Deployer,
@@ -14,31 +15,16 @@ from cmdeploy.basedeploy import (
    is_in_container,
 )

-# distro-neutral base version, as committed in chatmail/dovecot debian/changelog
-DOVECOT_ARCHIVE_VERSION = "2.3.21+dfsg1-3+chatmail2"
-
-VERSION_ID_CMD = "grep '^VERSION_ID=' /etc/os-release"
-
-
-def _stamped_version(deb_release: int) -> str:
-    """Version as built, including the per-distro suffix stamped by
-    chatmail/dovecot CI into package version and filename."""
-    return f"{DOVECOT_ARCHIVE_VERSION}+deb{deb_release}u1"
-
+DOVECOT_ARCHIVE_VERSION = "2.3.21+dfsg1-3"
+DOVECOT_PACKAGE_VERSION = f"1:{DOVECOT_ARCHIVE_VERSION}"

 DOVECOT_SHA256 = {
-    ("amd64", 12, "core"): "ac3977264d9b9a6fcec53fd3f5cdd2a79ca8aa0324de530c07e535008540826e",
-    ("arm64", 12, "core"): "21626c9c9b52cbdcf1a17b5c09e3c4043e69aa371bf83cc2fcb3b7ddaecdc109",
-    ("amd64", 13, "core"): "47c242ef23c17e700ac19d52d82c9fdb2ebd757d8beb3a7f6781d2de59f87bd0",
-    ("arm64", 13, "core"): "c14c53f112c875f698c4cb6e5870c605cd0a9dd98d35a66e94ceb1827f8020a3",
-    ("amd64", 12, "imapd"): "92a7ab5fc7dc32886a0c34404f919f1335d397b48c467e0c1ef77e56978f60ea",
-    ("arm64", 12, "imapd"): "9369fd566fec4df109ef23debf34ea0417ae85beb29cbe7de619d4d1f31b120c",
-    ("amd64", 13, "imapd"): "e38cc1266455f937ed62f971ea859c47e1a99247841ed0ad946963b524cfdbc5",
-    ("arm64", 13, "imapd"): "11d97dabf23171b37f8b1335dfdb81d408f8b95391aea6d4066aecc9fde01dfe",
-    ("amd64", 12, "lmtpd"): "dc3de473789969f7dd3504ac8783da5e42a446d2d7a305a4e9d7081a6dfe71ab",
-    ("arm64", 12, "lmtpd"): "ae2cbd6c5c43f6d8e2172997b055448f4c79238e2f99cd9ab9200a7d9f548908",
-    ("amd64", 13, "lmtpd"): "833b243e28c7baff141ecf37456e310f5d836e7944a3b9f2fe5074adf0d6a418",
-    ("arm64", 13, "lmtpd"): "55af47a121ba7e23966b20ddaab2dff7feba4b34677864e045e31a702afa180d",
+    ("core", "amd64"): "dd060706f52a306fa863d874717210b9fe10536c824afe1790eec247ded5b27d",
+    ("core", "arm64"): "e7548e8a82929722e973629ecc40fcfa886894cef3db88f23535149e7f730dc9",
+    ("imapd", "amd64"): "8d8dc6fc00bbb6cdb25d345844f41ce2f1c53f764b79a838eb2a03103eebfa86",
+    ("imapd", "arm64"): "178fa877ddd5df9930e8308b518f4b07df10e759050725f8217a0c1fb3fd707f",
+    ("lmtpd", "amd64"): "2f69ba5e35363de50962d42cccbfe4ed8495265044e244007d7ccddad77513ab",
+    ("lmtpd", "arm64"): "89f52fb36524f5877a177dff4a713ba771fd3f91f22ed0af7238d495e143b38f",
 }


@@ -52,30 +38,34 @@ class DovecotDeployer(Deployer):

    def install(self):
        arch = host.get_fact(Arch)
-        deb_release = _parse_version_id(host.get_fact(Command, VERSION_ID_CMD))
        with blocked_service_startup():
            debs = []
            for pkg in ("core", "imapd", "lmtpd"):
-                deb, changed = _download_dovecot_package(pkg, arch, deb_release)
+                deb, changed = _download_dovecot_package(pkg, arch)
                self.need_restart |= changed
                if deb:
                    debs.append(deb)
            if debs:
                deb_list = " ".join(debs)
-                # apt-get install with local .deb paths resolves depends
-                # against the configured repos (e.g. pulls libwrap0),
-                # The pin file written earlier by ChatmailDeployer prevents apt
-                # from installing a 'wrong' version
+                # First dpkg may fail on missing dependencies (stderr suppressed);
+                # apt-get --fix-broken pulls them in, then dpkg retries cleanly.
                server.shell(
                    name="Install dovecot packages",
                    commands=[
-                        "DEBIAN_FRONTEND=noninteractive apt-get install -y "
-                        '-o Dpkg::Options::="--force-confdef" '
-                        '-o Dpkg::Options::="--force-confold" '
-                        f"--allow-downgrades {deb_list}",
+                        f"dpkg --force-confdef --force-confold -i {deb_list} 2> /dev/null || true",
+                        "DEBIAN_FRONTEND=noninteractive apt-get -y --fix-broken install",
+                        f"dpkg --force-confdef --force-confold -i {deb_list}",
                    ],
                )
                self.need_restart = True
+        self.put_file(
+            src=io.StringIO(
+                "Package: dovecot-*\n"
+                "Pin: version *\n"
+                "Pin-Priority: -1\n"
+            ),
+            dest="/etc/apt/preferences.d/pin-dovecot",
+        )

    def configure(self):
        configure_remote_units(self, self.config.mail_domain_bare, self.units)
@@ -88,7 +78,7 @@ class DovecotDeployer(Deployer):
        if not self.disable_mail and not self.need_restart:
            stale = host.get_fact(
                Command,
-                "pid=$(systemctl show -p MainPID --value dovecot.service 2>/dev/null);"
+                'pid=$(systemctl show -p MainPID --value dovecot.service 2>/dev/null);'
                ' [ "${pid:-0}" != "0" ] && readlink "/proc/$pid/exe" 2>/dev/null | grep -q "(deleted)"'
                " && echo STALE || true",
            )
@@ -103,15 +93,6 @@ class DovecotDeployer(Deployer):
        )


-def _parse_version_id(version_line: str) -> int:
-    """Debian major release from an /etc/os-release VERSION_ID line."""
-    _, _, raw = (version_line or "").strip().partition("=")
-    try:
-        return int(raw.strip('"'))
-    except ValueError:
-        raise ValueError(f"cannot determine Debian release from {version_line!r}")
-
-
 def _pick_url(primary, fallback):
    try:
        req = urllib.request.Request(primary, method="HEAD")
@@ -121,36 +102,27 @@ def _pick_url(primary, fallback):
        return fallback


-def _download_dovecot_package(package: str, arch: str, deb_release: int) -> tuple[str | None, bool]:
+def _download_dovecot_package(package: str, arch: str) -> tuple[str | None, bool]:
    """Download a dovecot .deb if needed, return (path, changed)."""
    arch = "amd64" if arch == "x86_64" else arch
    arch = "arm64" if arch == "aarch64" else arch

    pkg_name = f"dovecot-{package}"
-    try:
-        # never fall back to the distro package: it is pinned to -1 and would
-        # in any case be a version we did not build and do not support
-        sha256 = DOVECOT_SHA256[(arch, deb_release, package)]
-    except KeyError:
-        raise ValueError(f"no dovecot build for {pkg_name} on deb{deb_release}/{arch}")
+    sha256 = DOVECOT_SHA256.get((package, arch))
+    if sha256 is None:
+        op = apt.packages(packages=[pkg_name])
+        return None, bool(getattr(op, "changed", False))

-    stamped_version = _stamped_version(deb_release)
    installed_versions = host.get_fact(DebPackages).get(pkg_name, [])
-    if f"1:{stamped_version}" in installed_versions:
+    if DOVECOT_PACKAGE_VERSION in installed_versions:
        return None, False

-    # Primary URL: flat structure with distro suffix in filename
-    primary_deb = f"{pkg_name}_{stamped_version}_{arch}.deb"
-    primary_url = f"https://download.delta.chat/dovecot/{primary_deb}"
-    # GitHub release files: escaped + in filename; the release tag stays
-    # distro-neutral, both distros ship in one combined release
-    tag_version = DOVECOT_ARCHIVE_VERSION.replace("+", "%2B")
-    fallback_deb = f"{pkg_name}_{stamped_version.replace('+', '%2B')}_{arch}.deb"
-    fallback_url = (
-        f"https://github.com/chatmail/dovecot/releases/download/upstream%2F{tag_version}/{fallback_deb}"
-    )
+    url_version = DOVECOT_ARCHIVE_VERSION.replace("+", "%2B")
+    deb_base = f"{pkg_name}_{url_version}_{arch}.deb"
+    primary_url = f"https://download.delta.chat/dovecot/{deb_base}"
+    fallback_url = f"https://github.com/chatmail/dovecot/releases/download/upstream%2F{url_version}/{deb_base}"
    url = _pick_url(primary_url, fallback_url)
-    deb_filename = f"/root/{primary_deb}"
+    deb_filename = f"/root/{deb_base}"

    files.download(
        name=f"Download {pkg_name}",
@@ -162,7 +134,6 @@ def _download_dovecot_package(package: str, arch: str, deb_release: int) -> tupl

    return deb_filename, True

-
 def _configure_dovecot(deployer, config: Config, debug: bool = False):
    """Configures Dovecot IMAP server."""
    deployer.put_template(
@@ -173,7 +144,9 @@ def _configure_dovecot(deployer, config: Config, debug: bool = False):
        disable_ipv6=config.disable_ipv6,
    )
    deployer.put_file("dovecot/auth.conf", "/etc/dovecot/auth.conf")
-    deployer.put_file("dovecot/push_notification.lua", "/etc/dovecot/push_notification.lua")
+    deployer.put_file(
+        "dovecot/push_notification.lua", "/etc/dovecot/push_notification.lua"
+    )

    # as per https://doc.dovecot.org/2.3/configuration_manual/os/
    # it is recommended to set the following inotify limits
@@ -51,6 +51,16 @@ class TestMetadataTokens:
        assert res == b"1111 2222"
        assert b"Getmetadata completed" in client.readline()

+    def test_get_appversions(self, imap_mailbox):
+        "get app version information shipped with the relay"
+        client = imap_mailbox.client
+        client.send(b'a01 GETMETADATA "" /shared/vendor/deltachat/appversions\n')
+        res = client.readline()
+        assert res[:1] == b"*"
+        res = client.readline().strip().rstrip(b")")
+        assert b'"clients":' in res
+        assert b"Getmetadata completed" in client.readline()
+

 class TestEndToEndDeltaChat:
    "Tests that use Delta Chat accounts on the chat mail instance."
@@ -0,0 +1,20 @@
+import json
+
+from cmdeploy.www import get_reporoot
+
+ALLOWED_URL_PREFIXES = (
+    "https://github.com/deltachat/",
+    "https://download.delta.chat/",
+)
+
+
+def test_appversions_schema():
+    data = json.loads(get_reporoot().joinpath("APPVERSIONS.json").read_text())
+    assert data["clients"]
+    for client in data["clients"]:
+        assert isinstance(client["clientId"], str)
+        for source in client["sources"]:
+            assert isinstance(source["sourceId"], str)
+            assert isinstance(source["versionInteger"], int)
+            assert isinstance(source["versionString"], str)
+            assert source["downloadUrl"].startswith(ALLOWED_URL_PREFIXES)
@@ -3,40 +3,29 @@ from types import SimpleNamespace

 import pytest
 from pyinfra.facts.deb import DebPackages
-from pyinfra.facts.server import Command

 from cmdeploy.dovecot import deployer as dovecot_deployer


-def _fact_name(key):
-    if isinstance(key, tuple):
-        return f"{key[0].__name__}{key[1:]!r}"
-    return key.__name__
-
-
 def make_host(*fact_pairs):
-    """Build a mock host; get_fact() dispatches to the provided facts mapping.
+    """Build a mock host; get_fact(cls) dispatches to the provided facts mapping.

    Args:
-        *fact_pairs: (fact_class, value) to match any call of that fact, or
-            ((fact_class, *args), value) to match one specific call. Needed
-            for Command, which install() and check_restart() invoke with
-            different scripts; a bare Command entry would serve both.
+        *fact_pairs: tuples of (fact_class, fact_value) to register

    Returns:
        SimpleNamespace with get_fact that raises a clear error if an
-        unregistered fact is requested.
+        unexpected fact type is requested.
    """
    facts = dict(fact_pairs)

-    def get_fact(cls, *args):
-        for key in ((cls, *args), cls):
-            if key in facts:
-                return facts[key]
-        registered = ", ".join(_fact_name(k) for k in facts)
-        raise LookupError(
-            f"unexpected get_fact({_fact_name((cls, *args))}); only registered: {registered}"
-        )
+    def get_fact(cls):
+        if cls not in facts:
+            registered = ", ".join(c.__name__ for c in facts)
+            raise LookupError(
+                f"unexpected get_fact({cls.__name__}); only registered: {registered}"
+            )
+        return facts[cls]

    return SimpleNamespace(get_fact=get_fact)

@@ -75,9 +64,7 @@ def track_shell(monkeypatch):


 def test_download_dovecot_package_skips_epoch_matched_install(monkeypatch):
-    # what dpkg reports after installing our deb: epoch + the +debNu1 suffix
-    # that chatmail/dovecot CI stamps via dch before building
-    epoch_version = f"1:{dovecot_deployer._stamped_version(12)}"
+    epoch_version = dovecot_deployer.DOVECOT_PACKAGE_VERSION
    downloads = []
    monkeypatch.setattr(
        dovecot_deployer,
@@ -95,17 +82,15 @@ def test_download_dovecot_package_skips_epoch_matched_install(monkeypatch):
        lambda **kwargs: downloads.append(kwargs),
    )

-    deb, changed = dovecot_deployer._download_dovecot_package("core", "amd64", deb_release=12)
+    deb, changed = dovecot_deployer._download_dovecot_package("core", "amd64")

    assert deb is None, f"expected no deb path when version matches, got {deb!r}"
    assert changed is False, "should not flag changed when version already installed"
    assert downloads == [], "should not download when version already installed"


-@pytest.mark.parametrize("deb_release", [12, 13])
-@pytest.mark.parametrize("arch", ["amd64", "arm64"])
 def test_download_dovecot_package_uses_archive_version_for_url_and_filename(
-    monkeypatch, deb_release, arch
+    monkeypatch,
 ):
    downloads = []
    monkeypatch.setattr(
@@ -124,26 +109,18 @@ def test_download_dovecot_package_uses_archive_version_for_url_and_filename(
        lambda **kwargs: downloads.append(kwargs),
    )

-    deb, changed = dovecot_deployer._download_dovecot_package(
-        "core", arch, deb_release=deb_release
-    )
+    deb, changed = dovecot_deployer._download_dovecot_package("core", "amd64")

-    stamped = dovecot_deployer._stamped_version(deb_release)
-    expected_deb = f"/root/dovecot-core_{stamped}_{arch}.deb"
+    archive_version = dovecot_deployer.DOVECOT_ARCHIVE_VERSION.replace("+", "%2B")
+    expected_deb = f"/root/dovecot-core_{archive_version}_amd64.deb"

-    # path uses the stamped version, and deb filenames never carry the epoch
+    # Verify the returned path uses archive version, not package version (with epoch)
    assert changed is True, "should flag changed when package not yet installed"
    assert deb == expected_deb, f"deb path mismatch: {deb!r} != {expected_deb!r}"
-    assert "1:" not in deb, f"deb filename must not contain the epoch, got {deb!r}"
-    assert len(downloads) == 1, "files.download should be called exactly once"
-    # the checksum is the security boundary: verify the right table row is used
-    assert (
-        downloads[0]["sha256sum"]
-        == dovecot_deployer.DOVECOT_SHA256[(arch, deb_release, "core")]
-    ), "must pass the sha256 matching (arch, release, package)"
-    assert f"deb{deb_release}u1" in downloads[0]["src"], (
-        f"download URL should carry the deb{deb_release} suffix, got {downloads[0]['src']!r}"
+    assert dovecot_deployer.DOVECOT_PACKAGE_VERSION not in deb, (
+        f"deb path should use archive version (no epoch), got {deb!r}"
    )
+    assert len(downloads) == 1, "files.download should be called exactly once"


 def test_install_skips_dpkg_path_when_epoch_matched_packages_present(
@@ -156,13 +133,12 @@ def test_install_skips_dpkg_path_when_epoch_matched_packages_present(
            (
                dovecot_deployer.DebPackages,
                {
-                    "dovecot-core": [f"1:{dovecot_deployer._stamped_version(12)}"],
-                    "dovecot-imapd": [f"1:{dovecot_deployer._stamped_version(12)}"],
-                    "dovecot-lmtpd": [f"1:{dovecot_deployer._stamped_version(12)}"],
+                    "dovecot-core": [dovecot_deployer.DOVECOT_PACKAGE_VERSION],
+                    "dovecot-imapd": [dovecot_deployer.DOVECOT_PACKAGE_VERSION],
+                    "dovecot-lmtpd": [dovecot_deployer.DOVECOT_PACKAGE_VERSION],
                },
            ),
            (dovecot_deployer.Arch, "x86_64"),
-            ((Command, dovecot_deployer.VERSION_ID_CMD), 'VERSION_ID="12"'),
        ),
    )
    downloads = []
@@ -176,26 +152,41 @@ def test_install_skips_dpkg_path_when_epoch_matched_packages_present(

    assert downloads == [], "should not download when all packages epoch-matched"
    assert track_shell == [], "should not run dpkg when all packages epoch-matched"
-    assert deployer.need_restart is False, "need_restart should be False when nothing changed"
+    assert deployer.need_restart is False, (
+        "need_restart should be False when nothing changed"
+    )


-def test_install_unsupported_arch_raises(
+def test_install_unsupported_arch_falls_back_to_apt(
    deployer, patch_blocked, mock_files_put, track_shell, monkeypatch
 ):
+    # For unsupported architectures, all fact lookups return the arch string.
    monkeypatch.setattr(
        dovecot_deployer,
        "host",
-        make_host(
-            (dovecot_deployer.Arch, "riscv64"),
-            ((Command, dovecot_deployer.VERSION_ID_CMD), 'VERSION_ID="12"'),
-        ),
+        SimpleNamespace(get_fact=lambda cls: "riscv64"),
    )
+    apt_calls = []

-    # we never fall back to the pinned distro package
-    with pytest.raises(ValueError, match="no dovecot build for dovecot-core"):
-        deployer.install()
+    # Mirrors apt.packages() return value: OperationMeta with .changed property.
+    # Only lmtpd triggers a change to verify |= accumulation of changed flags.
+    def fake_apt(**kwargs):
+        apt_calls.append(kwargs)
+        changed = "lmtpd" in kwargs["packages"][0]
+        return SimpleNamespace(changed=changed)

-    assert track_shell == [], "should not run apt-get for unsupported arch"
+    monkeypatch.setattr(dovecot_deployer.apt, "packages", fake_apt)
+
+    deployer.install()
+
+    actual_pkgs = [c["packages"] for c in apt_calls]
+    assert actual_pkgs == [["dovecot-core"], ["dovecot-imapd"], ["dovecot-lmtpd"]], (
+        f"expected apt install of core/imapd/lmtpd, got {actual_pkgs}"
+    )
+    assert track_shell == [], "should not run dpkg for unsupported arch"
+    assert deployer.need_restart is True, (
+        "need_restart should be True when apt installed a package"
+    )


 def test_install_runs_dpkg_when_packages_need_download(
@@ -207,7 +198,6 @@ def test_install_runs_dpkg_when_packages_need_download(
        make_host(
            (dovecot_deployer.DebPackages, {}),
            (dovecot_deployer.Arch, "x86_64"),
-            ((Command, dovecot_deployer.VERSION_ID_CMD), 'VERSION_ID="12"'),
        ),
    )
    monkeypatch.setattr(
@@ -223,15 +213,17 @@ def test_install_runs_dpkg_when_packages_need_download(

    deployer.install()

-    assert len(track_shell) == 1, f"expected one server.shell() call for dpkg install, got {len(track_shell)}"
+    assert len(track_shell) == 1, (
+        f"expected one server.shell() call for dpkg install, got {len(track_shell)}"
+    )
    cmds = track_shell[0]["commands"]
-    assert len(cmds) == 1, f"expected single apt-get install command, got: {cmds}"
-    assert "apt-get install -y" in cmds[0]
-    assert '-o Dpkg::Options::="--force-confdef"' in cmds[0]
-    assert '-o Dpkg::Options::="--force-confold"' in cmds[0]
-    assert "--allow-downgrades" in cmds[0]
-    assert ".deb" in cmds[0]
-    assert deployer.need_restart is True, "need_restart should be True after dpkg install"
+    assert len(cmds) == 3, f"expected 3 dpkg/apt commands, got: {cmds}"
+    assert cmds[0].startswith("dpkg --force-confdef --force-confold -i ")
+    assert "apt-get -y --fix-broken install" in cmds[1]
+    assert cmds[2].startswith("dpkg --force-confdef --force-confold -i ")
+    assert deployer.need_restart is True, (
+        "need_restart should be True after dpkg install"
+    )


 def test_pick_url_falls_back_on_primary_error(monkeypatch):
@@ -240,43 +232,6 @@ def test_pick_url_falls_back_on_primary_error(monkeypatch):

    monkeypatch.setattr(dovecot_deployer.urllib.request, "urlopen", raise_error)
    result = dovecot_deployer._pick_url("http://primary", "http://fallback")
-    assert result == "http://fallback", f"should fall back when primary fails, got {result!r}"
-
-
-def test_install_fails_on_unsupported_debian_version(deployer, patch_blocked, monkeypatch):
-    monkeypatch.setattr(
-        dovecot_deployer,
-        "host",
-        make_host(
-            (dovecot_deployer.Arch, "x86_64"),
-            ((Command, dovecot_deployer.VERSION_ID_CMD), 'VERSION_ID="99"'),
-        ),
+    assert result == "http://fallback", (
+        f"should fall back when primary fails, got {result!r}"
    )
-
-    with pytest.raises(ValueError, match="no dovecot build for dovecot-core on deb99"):
-        deployer.install()
-
-
-@pytest.mark.parametrize(
-    "version_line", ["", None, "ID=debian"], ids=["empty", "none", "no-version-id"]
-)
-def test_parse_version_id_raises_without_version_id(version_line):
-    with pytest.raises(ValueError, match="cannot determine Debian release"):
-        dovecot_deployer._parse_version_id(version_line)
-
-
-@pytest.mark.parametrize("deb_release", [12, 13])
-def test_parse_version_id(deb_release):
-    parsed = dovecot_deployer._parse_version_id(f'VERSION_ID="{deb_release}"\n')
-    assert parsed == deb_release
-
-
-def test_dovecot_sha256_covers_all_packages_per_release():
-    """Every release in the table needs all three packages on both arches."""
-    table = dovecot_deployer.DOVECOT_SHA256
-    expected = {
-        (arch, pkg) for arch in ("amd64", "arm64") for pkg in ("core", "imapd", "lmtpd")
-    }
-    for release in {r for _, r, _ in table}:
-        got = {(arch, pkg) for arch, r, pkg in table if r == release}
-        assert got == expected, f"deb{release} incomplete: {sorted(expected - got)}"
@@ -35,8 +35,12 @@ def prepare_template(source):
    return render_vars, page_layout


+def get_reporoot() -> Path:
+    return (Path(__file__).resolve() / "../../../../").resolve()
+
+
 def get_paths(config) -> (Path, Path, Path):
-    reporoot = (Path(__file__).resolve() / "../../../../").resolve()
+    reporoot = get_reporoot()
    www_path = Path(config.www_folder)
    # if www_folder was not set, use default directory
    if config.www_folder == "":
@@ -249,6 +249,28 @@ Fresh chatmail addresses have a mailbox directory that contains:
   directories will typically be empty unless the user of that address
   hasn’t been online for a while.

+App version information (experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A chatmail relay ships the repository's
+`APPVERSIONS.json <https://github.com/chatmail/relay/blob/main/APPVERSIONS.json>`_
+and serves its content under the IMAP METADATA key
+``/shared/vendor/deltachat/appversions``.
+Chat apps installed outside of app stores read this key
+to learn about updates and where to download them.
+The mechanism is experimental and may change.
+
+The file travels with the normal deploy:
+update the repository checkout and run ``cmdeploy run``.
+Local modifications of ``APPVERSIONS.json`` are deployed as-is,
+so you can serve your own app version information,
+including links to app downloads.
+
+Note that as of August 2026, only Delta Chat Android is beginning
+to support discovering app versions from relays.
+Consumers of relay-provided app version information
+need to verify themselves that downloaded app files are valid.
+
 Active ports
 ~~~~~~~~~~~~