detached 4539f00

docs(images): add config and CLI cleanup documentation

commit
4539f00b41c08ef4faeac9c2eb78ab9e676e8184
author
brice · · 2026-02-08 06:58 UTC
committer
brice · · 2026-02-08 09:40 UTC
parent
b5442e4
signature
GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email
5 files · +140 -0
Unified
UnifiedSplit
A docs/cli/images.md +70 -0
@@ -0,0 +1,70 @@
1+# Images Command
2+
3+List and prune runtime/registry images.
4+
5+## gordon images
6+
7+```bash
8+gordon images <subcommand>
9+```
10+
11+Subcommands:
12+
13+- `list` - List runtime images.
14+- `prune` - Prune dangling runtime images and optionally registry data.
15+
16+> **Note:** Images commands require remote mode (`--remote` + `--token`, or configured remotes).
17+
18+## gordon images list
19+
20+```bash
21+gordon images list
22+```
23+
24+Shows image rows with repository, tag, size, creation time, image id, and dangling status.
25+
26+## gordon images prune
27+
28+```bash
29+gordon images prune [--dry-run] [--keep <n>] [--runtime-only]
30+```
31+
32+Flags:
33+
34+| Flag | Default | Description |
35+|------|---------|-------------|
36+| `--dry-run` | `false` | Show prune behavior without applying changes |
37+| `--keep` | `0` | Number of latest tags to keep per repository (`0` disables registry cleanup) |
38+| `--runtime-only` | `false` | Prune dangling runtime images only; forces registry cleanup off |
39+
40+Behavior notes:
41+
42+- `--runtime-only` forces `keep_last = 0`.
43+- `--keep` must be `>= 0`.
44+- `--dry-run` reports what would be pruned.
45+
46+## Examples
47+
48+```bash
49+# List images
50+gordon images list
51+
52+# Prune dangling runtime images only
53+gordon images prune --runtime-only
54+
55+# Prune runtime images and keep 3 newest tags per repository
56+gordon images prune --keep 3
57+
58+# Preview cleanup without applying
59+gordon images prune --dry-run --keep 5
60+```
61+
62+## Required Permissions
63+
64+- `list` requires `admin:status:read`.
65+- `prune` requires `admin:config:write`.
66+
67+## Related
68+
69+- [CLI Commands](./index.md)
70+- [Images Configuration](../config/images.md)
@@ -0,0 +1,70 @@
1+# Images Command
2+
3+List and prune runtime/registry images.
4+
5+## gordon images
6+
7+```bash
8+gordon images <subcommand>
9+```
10+
11+Subcommands:
12+
13+- `list` - List runtime images.
14+- `prune` - Prune dangling runtime images and optionally registry data.
15+
16+> **Note:** Images commands require remote mode (`--remote` + `--token`, or configured remotes).
17+
18+## gordon images list
19+
20+```bash
21+gordon images list
22+```
23+
24+Shows image rows with repository, tag, size, creation time, image id, and dangling status.
25+
26+## gordon images prune
27+
28+```bash
29+gordon images prune [--dry-run] [--keep <n>] [--runtime-only]
30+```
31+
32+Flags:
33+
34+| Flag | Default | Description |
35+|------|---------|-------------|
36+| `--dry-run` | `false` | Show prune behavior without applying changes |
37+| `--keep` | `0` | Number of latest tags to keep per repository (`0` disables registry cleanup) |
38+| `--runtime-only` | `false` | Prune dangling runtime images only; forces registry cleanup off |
39+
40+Behavior notes:
41+
42+- `--runtime-only` forces `keep_last = 0`.
43+- `--keep` must be `>= 0`.
44+- `--dry-run` reports what would be pruned.
45+
46+## Examples
47+
48+```bash
49+# List images
50+gordon images list
51+
52+# Prune dangling runtime images only
53+gordon images prune --runtime-only
54+
55+# Prune runtime images and keep 3 newest tags per repository
56+gordon images prune --keep 3
57+
58+# Preview cleanup without applying
59+gordon images prune --dry-run --keep 5
60+```
61+
62+## Required Permissions
63+
64+- `list` requires `admin:status:read`.
65+- `prune` requires `admin:config:write`.
66+
67+## Related
68+
69+- [CLI Commands](./index.md)
70+- [Images Configuration](../config/images.md)
M docs/cli/index.md +6 -0
@@ -30,6 +30,7 @@ Commands are organized by where they run:
3030 | `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |
3131 | `gordon status` | Show Gordon server status | [status](./status.md) |
3232 | `gordon backup` | Manage database backups | [backup](./backup.md) |
33+| `gordon images` | List and prune images | [images](./images.md) |
3334
3435 ## Client Commands
3536
@@ -80,6 +81,11 @@ gordon backup run app.example.com
8081 gordon backup detect app.example.com
8182 gordon backup status
8283
84+# Images
85+gordon images list
86+gordon images prune --runtime-only
87+gordon images prune --keep 3
88+
8389 # Authentication
8490 gordon auth token generate --subject ci-bot --expiry 0
8591 gordon auth token list
@@ -30,6 +30,7 @@ Commands are organized by where they run:
30 | `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |30 | `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) |
31 | `gordon status` | Show Gordon server status | [status](./status.md) |31 | `gordon status` | Show Gordon server status | [status](./status.md) |
32 | `gordon backup` | Manage database backups | [backup](./backup.md) |32 | `gordon backup` | Manage database backups | [backup](./backup.md) |
33+| `gordon images` | List and prune images | [images](./images.md) |
33 34
34 ## Client Commands35 ## Client Commands
35 36
@@ -80,6 +81,11 @@ gordon backup run app.example.com
80 gordon backup detect app.example.com81 gordon backup detect app.example.com
81 gordon backup status82 gordon backup status
82 83
84+# Images
85+gordon images list
86+gordon images prune --runtime-only
87+gordon images prune --keep 3
88+
83 # Authentication89 # Authentication
84 gordon auth token generate --subject ci-bot --expiry 090 gordon auth token generate --subject ci-bot --expiry 0
85 gordon auth token list91 gordon auth token list
A docs/config/images.md +41 -0
@@ -0,0 +1,41 @@
1+# Images Configuration
2+
3+Configure automatic image cleanup for Docker runtime images and local registry storage.
4+
5+## Overview
6+
7+When enabled, Gordon runs a scheduled image prune job that:
8+
9+- Prunes dangling runtime images.
10+- Applies tag retention to registry repositories.
11+- Preserves the `latest` tag.
12+- Removes unreferenced blobs after tag cleanup.
13+
14+## Configuration
15+
16+```toml
17+[images.prune]
18+enabled = false
19+schedule = "daily"
20+keep_last = 3
21+```
22+
23+## Settings
24+
25+| Key | Type | Default | Description |
26+|-----|------|---------|-------------|
27+| `images.prune.enabled` | bool | `false` | Enables scheduled image cleanup |
28+| `images.prune.schedule` | string | `"daily"` | Schedule preset: `hourly`, `daily`, `weekly`, `monthly` |
29+| `images.prune.keep_last` | int | `3` | Number of newest tags kept per repository during registry cleanup |
30+
31+## Retention Behavior
32+
33+- `latest` is always preserved.
34+- `keep_last` applies per repository.
35+- `keep_last = 0` skips registry tag/blob cleanup (runtime dangling prune still runs).
36+- Negative `keep_last` values are invalid.
37+
38+## Related
39+
40+- [CLI Images Command](../cli/images.md)
41+- [Configuration Reference](./reference.md)
@@ -0,0 +1,41 @@
1+# Images Configuration
2+
3+Configure automatic image cleanup for Docker runtime images and local registry storage.
4+
5+## Overview
6+
7+When enabled, Gordon runs a scheduled image prune job that:
8+
9+- Prunes dangling runtime images.
10+- Applies tag retention to registry repositories.
11+- Preserves the `latest` tag.
12+- Removes unreferenced blobs after tag cleanup.
13+
14+## Configuration
15+
16+```toml
17+[images.prune]
18+enabled = false
19+schedule = "daily"
20+keep_last = 3
21+```
22+
23+## Settings
24+
25+| Key | Type | Default | Description |
26+|-----|------|---------|-------------|
27+| `images.prune.enabled` | bool | `false` | Enables scheduled image cleanup |
28+| `images.prune.schedule` | string | `"daily"` | Schedule preset: `hourly`, `daily`, `weekly`, `monthly` |
29+| `images.prune.keep_last` | int | `3` | Number of newest tags kept per repository during registry cleanup |
30+
31+## Retention Behavior
32+
33+- `latest` is always preserved.
34+- `keep_last` applies per repository.
35+- `keep_last = 0` skips registry tag/blob cleanup (runtime dangling prune still runs).
36+- Negative `keep_last` values are invalid.
37+
38+## Related
39+
40+- [CLI Images Command](../cli/images.md)
41+- [Configuration Reference](./reference.md)
M docs/config/index.md +11 -0
@@ -126,6 +126,12 @@ hourly = 24
126126 daily = 7
127127 weekly = 4
128128 monthly = 12
129+
130+# Images
131+[images.prune]
132+enabled = false
133+schedule = "daily"
134+keep_last = 3
129135 ```
130136
131137 ## Configuration Sections
@@ -146,6 +152,7 @@ monthly = 12
146152 | `[network_groups]` | Shared service networks | [Network Groups](./network-groups.md) |
147153 | `[attachments]` | Service dependencies | [Attachments](./attachments.md) |
148154 | `[backups]` | Database backups | [Backups](./backups.md) |
155+| `[images.prune]` | Scheduled image cleanup | [Images](./images.md) |
149156
150157 ## Default Values
151158
@@ -182,6 +189,9 @@ monthly = 12
182189 | `network_isolation.enabled` | `false` |
183190 | `auto_route.enabled` | `false` |
184191 | `backups.enabled` | `false` |
192+| `images.prune.enabled` | `false` |
193+| `images.prune.schedule` | `"daily"` |
194+| `images.prune.keep_last` | `3` |
185195
186196 ## Hot Reload
187197
@@ -223,3 +233,4 @@ Pattern: `GORDON_SECTION_KEY` (uppercase, underscores instead of dots)
223233 - [External Routes](./external-routes.md)
224234 - [Authentication](./auth.md)
225235 - [Backups](./backups.md)
236+- [Images](./images.md)
@@ -126,6 +126,12 @@ hourly = 24
126 daily = 7126 daily = 7
127 weekly = 4127 weekly = 4
128 monthly = 12128 monthly = 12
129+
130+# Images
131+[images.prune]
132+enabled = false
133+schedule = "daily"
134+keep_last = 3
129 ```135 ```
130 136
131 ## Configuration Sections137 ## Configuration Sections
@@ -146,6 +152,7 @@ monthly = 12
146 | `[network_groups]` | Shared service networks | [Network Groups](./network-groups.md) |152 | `[network_groups]` | Shared service networks | [Network Groups](./network-groups.md) |
147 | `[attachments]` | Service dependencies | [Attachments](./attachments.md) |153 | `[attachments]` | Service dependencies | [Attachments](./attachments.md) |
148 | `[backups]` | Database backups | [Backups](./backups.md) |154 | `[backups]` | Database backups | [Backups](./backups.md) |
155+| `[images.prune]` | Scheduled image cleanup | [Images](./images.md) |
149 156
150 ## Default Values157 ## Default Values
151 158
@@ -182,6 +189,9 @@ monthly = 12
182 | `network_isolation.enabled` | `false` |189 | `network_isolation.enabled` | `false` |
183 | `auto_route.enabled` | `false` |190 | `auto_route.enabled` | `false` |
184 | `backups.enabled` | `false` |191 | `backups.enabled` | `false` |
192+| `images.prune.enabled` | `false` |
193+| `images.prune.schedule` | `"daily"` |
194+| `images.prune.keep_last` | `3` |
185 195
186 ## Hot Reload196 ## Hot Reload
187 197
@@ -223,3 +233,4 @@ Pattern: `GORDON_SECTION_KEY` (uppercase, underscores instead of dots)
223 - [External Routes](./external-routes.md)233 - [External Routes](./external-routes.md)
224 - [Authentication](./auth.md)234 - [Authentication](./auth.md)
225 - [Backups](./backups.md)235 - [Backups](./backups.md)
236+- [Images](./images.md)
M docs/config/reference.md +12 -0
@@ -141,6 +141,14 @@ daily = 0 # Keep N daily backups per DB
141141 weekly = 0 # Keep N weekly backups per DB
142142 monthly = 0 # Keep N monthly backups per DB
143143
144+# =============================================================================
145+# IMAGES
146+# =============================================================================
147+[images.prune]
148+enabled = false # Enable scheduled image cleanup
149+schedule = "daily" # "hourly", "daily", "weekly", "monthly"
150+keep_last = 3 # Keep N newest tags per repository
151+
144152 # Note: retention values set to 0 keep no backups for that tier.
145153 # For practical defaults, consider setting daily = 7.
146154 ```
@@ -197,6 +205,9 @@ monthly = 0 # Keep N monthly backups per DB
197205 | `backups.retention.daily` | `0` | Keep no daily backups by default (recommend `7`) |
198206 | `backups.retention.weekly` | `0` | Keep no weekly backups by default |
199207 | `backups.retention.monthly` | `0` | Keep no monthly backups by default |
208+| `images.prune.enabled` | `false` | Scheduled image cleanup disabled |
209+| `images.prune.schedule` | `"daily"` | Cleanup schedule preset |
210+| `images.prune.keep_last` | `3` | Number of recent tags kept per repository |
200211
201212 Note: for all `backups.retention.*` keys, `0` means keep no backups for that retention tier.
202213
@@ -269,3 +280,4 @@ gordon serve
269280 - [Authentication](./auth.md)
270281 - [Network Isolation](./network-isolation.md)
271282 - [Volumes](./volumes.md)
283+- [Images](./images.md)
@@ -141,6 +141,14 @@ daily = 0 # Keep N daily backups per DB
141 weekly = 0 # Keep N weekly backups per DB141 weekly = 0 # Keep N weekly backups per DB
142 monthly = 0 # Keep N monthly backups per DB142 monthly = 0 # Keep N monthly backups per DB
143 143
144+# =============================================================================
145+# IMAGES
146+# =============================================================================
147+[images.prune]
148+enabled = false # Enable scheduled image cleanup
149+schedule = "daily" # "hourly", "daily", "weekly", "monthly"
150+keep_last = 3 # Keep N newest tags per repository
151+
144 # Note: retention values set to 0 keep no backups for that tier.152 # Note: retention values set to 0 keep no backups for that tier.
145 # For practical defaults, consider setting daily = 7.153 # For practical defaults, consider setting daily = 7.
146 ```154 ```
@@ -197,6 +205,9 @@ monthly = 0 # Keep N monthly backups per DB
197 | `backups.retention.daily` | `0` | Keep no daily backups by default (recommend `7`) |205 | `backups.retention.daily` | `0` | Keep no daily backups by default (recommend `7`) |
198 | `backups.retention.weekly` | `0` | Keep no weekly backups by default |206 | `backups.retention.weekly` | `0` | Keep no weekly backups by default |
199 | `backups.retention.monthly` | `0` | Keep no monthly backups by default |207 | `backups.retention.monthly` | `0` | Keep no monthly backups by default |
208+| `images.prune.enabled` | `false` | Scheduled image cleanup disabled |
209+| `images.prune.schedule` | `"daily"` | Cleanup schedule preset |
210+| `images.prune.keep_last` | `3` | Number of recent tags kept per repository |
200 211
201 Note: for all `backups.retention.*` keys, `0` means keep no backups for that retention tier.212 Note: for all `backups.retention.*` keys, `0` means keep no backups for that retention tier.
202 213
@@ -269,3 +280,4 @@ gordon serve
269 - [Authentication](./auth.md)280 - [Authentication](./auth.md)
270 - [Network Isolation](./network-isolation.md)281 - [Network Isolation](./network-isolation.md)
271 - [Volumes](./volumes.md)282 - [Volumes](./volumes.md)
283+- [Images](./images.md)

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 7

Tags 106

↑↓ moveenter openesc close