1# Deploy Configuration
2
3Controls how Gordon pulls images during deployment.
4
5## Example
6
7```toml
8[deploy]
9pull_policy = "if-tag-changed"
10readiness_mode = "auto"
11health_timeout = "90s"
12readiness_delay = "5s"
13drain_mode = "auto"
14drain_timeout = "30s"
15drain_delay = "2s"
16```
17
18## Settings
19
20### `deploy.pull_policy`
21
22How to decide when to pull an image:
23
24- `always`: always pull, even if the tag exists locally.
25- `if-not-present`: only pull when the tag is missing locally.
26- `if-tag-changed`: pull for tag references to check for updates; skip pulls for digest references (`@sha256:...`).
27
28Default: `if-tag-changed`
29
30### `deploy.readiness_delay`
31
32How long Gordon waits after a container first reports `running` before it is
33considered ready for traffic.
34
35- Uses Go duration format (examples: `"5s"`, `"15s"`, `"1m"`).
36- If the container briefly exits right after this delay, Gordon now waits up to
37  30 additional seconds for it to recover before failing the deploy.
38
39Default: `"5s"`
40
41### `deploy.readiness_mode`
42
43How Gordon determines that a newly started container is ready for traffic.
44
45- `auto`: use Docker health status if the container has a healthcheck; otherwise
46  fall back to `deploy.readiness_delay`.
47- `docker-health`: require a Docker healthcheck and wait for `healthy`.
48  Deploy fails with `no healthcheck detected` if absent.
49- `delay`: always use `deploy.readiness_delay`.
50
51Default: `"auto"`
52
53### `deploy.health_timeout`
54
55Maximum time Gordon waits for health-based readiness in `auto`/`docker-health`
56mode before failing the deploy.
57
58- Uses Go duration format (examples: `"30s"`, `"90s"`, `"2m"`).
59- Default `"90s"` balances typical app startup time with fast failure feedback.
60- Increase for slow cold-starts, migrations, or heavy warmup workloads.
61
62Default: `"90s"`
63
64### `deploy.drain_delay`
65
66How long Gordon waits after synchronous proxy cache invalidation before stopping
67the previous container during zero-downtime replacement.
68
69- Uses Go duration format (examples: `"2s"`, `"10s"`, `"1m"`).
70- Applied only when a previous container exists and cache invalidation was
71  triggered for the deployed domain.
72- If explicitly set to `"0s"` (or a negative duration), delay is disabled and
73  Gordon switches immediately after invalidation.
74
75Default: `"2s"`
76
77### `deploy.drain_mode`
78
79How Gordon decides when it is safe to stop the previous container after routing
80traffic to the new one.
81
82- `auto`: wait for in-flight proxy requests to drain when available; otherwise
83  fall back to `deploy.drain_delay`.
84- `inflight`: wait for in-flight proxy requests on the previous container to
85  reach zero (bounded by `deploy.drain_timeout`).
86- `delay`: always use `deploy.drain_delay`.
87
88Default: `"auto"`
89
90### `deploy.drain_timeout`
91
92Maximum time Gordon waits for in-flight request drain before continuing with old
93container shutdown.
94
95- Uses Go duration format (examples: `"10s"`, `"30s"`, `"1m"`).
96- Default `"30s"` is a practical upper bound for most HTTP workloads.
97- Increase for long-lived requests (large uploads, SSE, long polling).
98
99Default: `"30s"`
100
101## Notes
102
103- Changes to `deploy.pull_policy` require a restart to take effect.
104- Changes to `deploy.readiness_mode` require a restart to take effect.
105- Changes to `deploy.health_timeout` require a restart to take effect.
106- Changes to `deploy.readiness_delay` require a restart to take effect.
107- Changes to `deploy.drain_mode` require a restart to take effect.
108- Changes to `deploy.drain_timeout` require a restart to take effect.
109- Changes to `deploy.drain_delay` require a restart to take effect.