Skip to content

Utils

Jump to bottom
zotabee edited this page Jul 19, 2026 · 1 revision

Utils

Note

Unlike the other roles in this playbook, utils does not deploy a container or web app. It performs host-level maintenance (cleanup) tasks. Source: roles/utils/ in the SEEDbox repo.

Table of Contents

Overview

The utils role bundles three independent cleanup tasks that free up disk space and keep a SEEDbox host tidy: apt package cleanup, systemd journal vacuuming, and Docker prune. It's part of the Extras tag group and runs directly on the host as root (become: true) — it has no defaults/settings.yml entry pre-seeded, so it uses its own role defaults unless you override them.

What it does

System package cleanup (tasks/cleanup/system_cleanup.yml)

Task Command Runs when
Clean apt cache apt clean ansible_os_family == "Debian" and utils_apt_clean
Clean obsolete package files apt autoclean ansible_os_family == "Debian" and utils_apt_autoclean
Remove unused packages apt autoremove -y ansible_os_family == "Debian" and utils_apt_autoremove

Systemd journal cleanup (tasks/cleanup/logs_cleanup.yml)

Task Command
Vacuum systemd journal journalctl --vacuum-time={{ utils_journal_vacuum_time }}

Docker cleanup (tasks/cleanup/docker_cleanup.yml)

Task Command
Remove unused Docker data docker system prune -af
Remove unused Docker volumes docker volume prune -f

Variables

Defined in roles/utils/defaults/main.yml:

Variable Default Description
utils_journal_vacuum_time "7d" Age threshold passed to journalctl --vacuum-time; journal entries older than this are purged
utils_apt_clean true Whether to run apt clean (Debian-family hosts only)
utils_apt_autoclean true Whether to run apt autoclean (Debian-family hosts only)
utils_apt_autoremove true Whether to run apt autoremove -y (Debian-family hosts only)

Tip

These aren't pre-seeded in settings.yml.default. To override a default, either add the same variable name to your settings.yml, or pass it with -e on the command line (see Usage).

Tags

Tag Scope
extras, utils Whole role (all three cleanup tasks)
system_cleanup Apt clean/autoclean/autoremove only
logs_cleanup Systemd journal vacuum only
docker_cleanup Docker system/volume prune only

Usage

# Run the entire Utils role (all cleanup tasks)
ansible-playbook seedbox.yml --tags=utils

# Run just one cleanup task
ansible-playbook seedbox.yml --tags=docker_cleanup
ansible-playbook seedbox.yml --tags=logs_cleanup
ansible-playbook seedbox.yml --tags=system_cleanup

# Override a default for a single run, e.g. keep 30 days of journal logs instead of 7
ansible-playbook seedbox.yml --tags=utils -e "utils_journal_vacuum_time=30d"

Tip

utils only cleans up when you run the playbook — it isn't a background service. If you want regular cleanup, schedule the command above (e.g. via a weekly cron job on the host) rather than running it manually each time.

Requirements & compatibility

Important

  • The apt-related tasks only run on hosts where ansible_os_family == "Debian"; they're silently skipped on other OS families.
  • Every task runs with become: true and requires root/sudo privileges.
  • The Docker cleanup tasks require the docker CLI to be available on the host — already the case if the mandatory docker core role has been applied.

Warning: Docker cleanup is destructive

Warning

docker system prune -af removes all unused containers, networks, and images — not just dangling ones — and docker volume prune -f removes all unused volumes. Any stopped container, unreferenced image, or volume not attached to a running container is deleted permanently. Make sure that's what you want (e.g. you don't rely on stopped containers or unattached volumes for anything) before running the docker_cleanup tag.

Clone this wiki locally