Problem/Justification
TrueNAS SCALE does not currently provide a built-in automatic cleanup or retention policy for unused Docker images.
When applications are updated, new images are downloaded, while older images can remain stored even after they are no longer referenced by any container. Over time, these unused images can consume a significant amount of space in the applications pool.
In my case, manually running a full Docker cleanup released more than 150 GB of storage. Although that cleanup also included other unused Docker resources, it demonstrates how much space can accumulate without an automatic retention policy.
A safe example of the type of image cleanup that could be scheduled automatically is:
docker image prune -a -f --filter “until=720h”
This command removes images that are not referenced by any existing container and that were created more than 30 days ago. It does not remove images currently referenced by running or stopped containers.
This can become a serious issue for users who install and frequently update many applications. A less experienced user may not notice the gradual increase in storage usage until the applications pool is nearly full. This could lead to failed application updates, applications being unable to start, databases being unable to write data, or other service interruptions.
Keeping one or two previous versions for rollback can be useful, but allowing unused images to remain indefinitely does not appear to be a reasonable default behaviour.
TrueNAS should provide a supported and configurable cleanup mechanism in the WebUI instead of requiring users to create custom Cron Jobs or manually run Docker commands.
Impact
This feature would benefit all TrueNAS SCALE users who use Apps by:
-
Reducing storage consumption caused by obsolete Docker images.
-
Lowering the risk of the applications pool unexpectedly becoming full.
-
Preventing failed updates and application outages caused by insufficient storage.
-
Providing a supported WebUI solution instead of requiring custom shell commands.
Possible configurable options could include:
-
Enable or disable automatic image cleanup.
-
Remove unused images older than a specified number of days.
-
Keep the last one, two, or three previous versions of each application.
-
Run the cleanup weekly or monthly.
-
Protect selected images from automatic deletion.
-
Display the amount of reclaimable space before cleanup.
A possible disadvantage is that deleted images might need to be downloaded again for a future rollback. This could be addressed by allowing administrators to keep a configurable number of previous versions.
Docker volumes should not be included in the automatic cleanup by default because they may contain persistent application data.
User Story
As a TrueNAS SCALE administrator, I want unused Docker images to be cleaned up automatically so that application updates do not gradually fill the applications pool.
The user would follow these steps:
-
Open Apps in the TrueNAS WebUI.
-
Open Configuration or Advanced Settings.
-
Enable Automatic cleanup of unused container images.
-
Select a cleanup schedule, such as weekly or monthly.
-
Choose a retention policy, for example:
-
Keep the last two previous versions; or
-
Remove unused images older than 30 days.
-
-
Optionally configure a storage threshold or notification.
-
Save the configuration.
TrueNAS would then periodically perform the equivalent of a safe image cleanup, for example:
docker image prune -a -f --filter “until=720h”
Alternatively, TrueNAS could use an internal implementation providing equivalent behaviour.
TrueNAS would identify images that are no longer referenced by any container, apply the selected retention policy, remove eligible images, and report the amount of storage reclaimed.