Add the system cleanup role

Adds ansible-role-cleanup from the MASH project. It can remove superseded
Docker images and stopped containers on every playbook run (unlike
`docker image prune -a`, keeping the images of stopped services), vacuum
old logs, remove paths and, on Debian-based distributions, upgrade
packages and purge old kernels. Everything is off by default.

The role runs after systemd_service_manager, once every service is
running, so the Docker cleanup can tell which images are still needed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/configuring-playbook-system-cleanup.md

@@ -0,0 +1,58 @@
+<!--
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up system cleanup (optional)
+
+The playbook can do some housekeeping on the server: removing Docker leftovers, old logs and arbitrary paths, and (on Debian-based distributions) upgrading packages and purging old kernels. Everything is off by default.
+
+The [Ansible role for system cleanup](https://github.com/mother-of-all-self-hosting/ansible-role-cleanup) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For all options, see the role's [`defaults/main.yml`](https://github.com/mother-of-all-self-hosting/ansible-role-cleanup/blob/main/defaults/main.yml).
+
+## Adjusting the playbook configuration
+
+To enable the cleanup tasks you'd like, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+# Removes stopped containers and Docker images which a newer image of the same repository superseded
+# at least 3 days ago (and which no container uses). Unlike `docker image prune -a`, unused images
+# without a newer version (e.g. of services you have stopped) are kept.
+system_cleanup_docker: true
+
+# Installs a systemd timer which runs `journalctl --vacuum-time=7d` daily.
+# journald already limits the space logs take up on its own, so this is only needed for keeping logs for a shorter time.
+system_cleanup_logs: true
+
+# Absolute paths to remove on each run
+system_cleanup_paths: []
+
+# The following options only have an effect on Debian-based distributions.
+
+# Runs a safe upgrade, `apt-get autoremove`, `apt-get clean`, etc.
+system_cleanup_apt: true
+
+# WARNING: very dangerous! Purges old Linux kernels, and their modules
+system_cleanup_kernels: false
+```
+
+The Docker cleanup runs when the playbook is run with the `start` tag (e.g. `just install-all` or `just setup-all`), after all services have been started. To also run it daily via a systemd timer (useful for removing superseded images without re-running the playbook), add `system_cleanup_docker_timer_enabled: true`.
+
+## Installing
+
+After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just setup-all`
+
+## Usage
+
+The Docker cleanup is done by a script, which you can also run by hand on the server. Pass `--dry-run` to only see what it would remove:
+
+```sh
+/matrix/system-cleanup/bin/cleanup-docker --dry-run
+```

docs/configuring-playbook.md

@@ -224,6 +224,8 @@ Services that help you in administrating and monitoring your Matrix installation
 
 - [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)
 
+- [Setting up system cleanup](configuring-playbook-system-cleanup.md) — removing superseded Docker images, old logs, etc.
+
 - Backups:
   - [Setting up BorgBackup](configuring-playbook-backup-borg.md) — a full Matrix server backup solution, including the Postgres database
 

docs/maintenance-and-troubleshooting.md

@@ -38,6 +38,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=run-docker-prune
 
 The shortcut command with `just` program is also available: `just run-tags run-docker-prune`
 
+Note that this also removes the images of services you have stopped, which then need to be pulled again. To have the playbook remove only the Docker images which newer ones have superseded, on every run, see [Setting up system cleanup](configuring-playbook-system-cleanup.md).
+
 ### Postgres
 
 See the dedicated [PostgreSQL maintenance](maintenance-postgres.md) documentation page.