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
• What it does
• Variables
• Tags
• Usage
• Requirements & compatibility
• Warning: Docker cleanup is destructive

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.