Docker housekeeping

Updating a deployment leaves things behind: the previous app and web images, the helper container that ran the switchover, older database dumps. Docker housekeeping removes what no running container and no recovery need, so updates do not fill the disk. You manage it on Settings > Administration > Updates > Manage, in the Docker housekeeping card. You need the admin ability.

What is removed#

Housekeeping works from an allowlist. It considers only these objects:

Object	Removed when
Previous app and web images, tagged pre-update-<timestamp>	They are older than the Previous versions to keep setting, and no container uses them.
Untagged wi-server and wi-web images	No container uses them.
Workbench images (wi-workbench:<hash>)	They are older than the newest previous one and no Coworker workbench container uses them. The image the running version uses and the most recent previous one are kept.
The update's helper container (wi-prod-update-cutover-<id>)	Its update succeeded, or its update failed and a newer update exists.
A leftover -blue app container	Its update failed and a newer update exists. The container of the latest failed update stays so you can inspect it.
Database dumps pre-update-<timestamp>.dump in /data/backups	They are older than the 2 newest dumps.
Each deployed App's build leftovers	Dokku's own per-App cleanup runs for the App.

Before housekeeping removes a helper or -blue container, it stores the container's log on the update run and reads it back. If the log cannot be stored, the container stays. The log shows under Details in the Update history card. See When an update fails.

Everything is removed by exact name, never forced. Anything a running container uses is left alone, and a tag that is the only tag on an image a container uses is kept.

What is never touched#

• The postgres and dokku containers and their images, and every other compose service.
• Images that are not the deployment's own wi-server, wi-web and wi-workbench images: the pgvector and Dokku images, and anything else on the Docker host.
• Tags that only look like ours. A tag must match pre-update- followed by a UTC timestamp such as 20261003T141500Z.
• Volumes. No volume is ever removed.
• Docker's build cache. The card reports its size, labelled "reported only, never removed".
• Dokku apps that have no App record (orphans). Housekeeping lists them and leaves them alone. Only a deployed App that exists in the product, including a stopped one, gets Dokku's per-App cleanup, and an App that is building is skipped.

Previous versions to keep#

Previous versions to keep is the number of earlier versions whose app and web images stay on the box for recovery. The default is 2, and you can set a whole number from 1 to 10. Change it in the field and select Save. The setting applies to the next cleanup.

Dumps are a separate rule: the 2 newest are always kept, whatever this setting says.

When it runs#

• After a successful update. Once an update has succeeded and the new app has been running for 15 minutes, a cleanup runs once for that update.
• Weekly. A cleanup runs once each week if no automatic cleanup has run since the week began (weeks start on Monday, UTC). A box that never updates is still cleaned, and an install with a backlog of old images catches up on its first cleanup, with no manual step.
• On demand. Select Clean up now and confirm Clean up Docker images now? with Clean up.

A check runs hourly. If a scheduled cleanup fails or is skipped after an update, it is retried no more than every six hours and at most three times for that update; the weekly cleanup still runs. A cleanup never runs while an update is in progress, while a helper container is running, or while another cleanup is running. Clean up now is disabled with "An update is in progress." or "A cleanup is in progress." in those cases.

Clean up now is also disabled when the card cannot find the running app and web containers of the standard stack, for example on a development deployment where the app runs directly on the host. A line under the button says "This deployment isn't running the standard stack, so there is nothing to clean up here." The same line appears if Docker cannot be reached.

The automatic runs exist on production deployments only. WI_IMAGE_CLEANUP_SCHEDULER set to none turns off the automatic runs, so cleanups happen only when you select Clean up now. See Configuration reference.

What the card shows#

• Disk figures: Images (with how much is not used by a container), Containers, Build cache and Free space on the Docker host. If Docker cannot be read, the card says "Docker disk figures are unavailable" with the reason.
• App images: for each deployed App, how many images it has, their total size, how much is in use and how much is reclaimable. This is a report only.
• Last cleanup: its status (Complete, Skipped, Failed or Running), when it finished, how it started (Weekly, After an update or Manual) and a summary such as how much space was reclaimed and how many images, containers and backups were removed. A cleanup that refused to run shows a neutral Skipped badge with the reason, for example that a helper container was still running; only a cleanup that started and hit an error shows the red Failed badge.
• Details: each removed or kept item with its reason and the space it freed, the result for each App, and any Dokku apps with no App record, which are listed and never removed. A removal that failed is recorded, and the rest of the cleanup carries on.

The Update history card below it lists each update with its status (Installed, Failed or In progress). Details shows the failed step, the error message and the stored log of the helper and blue containers.

The low-disk warning#

Housekeeping warns you when free space on the Docker host drops below 15% of the disk or below 5 GB. The warning reads "Disk space on the Docker host is low", with the free space, and tells you to open Settings, then Updates. Only admins see it:

• a badge on Settings in the profile menu, which is also counted in the badge on your name;
• a banner at the top of Settings with an Open Updates link;
• a banner inside the Docker housekeeping card.

The reading is cached for a few minutes and refreshed about every five minutes. The warning clears when a cleanup has freed enough space.