Server Commands
Commands for running and managing the Gordon server process.
gordon serve
Start the Gordon server with registry and proxy components.
Synopsis
gordon serve [options]
Options
| Option |
Short |
Default |
Description |
--config |
-c |
Auto-detected |
Path to configuration file |
Description
Starts the Gordon server, which includes:
- Container Registry - Receives image pushes on the registry port
- HTTP Proxy - Routes traffic to containers on the proxy port
- Event Bus - Coordinates deployments and updates
- Config Watcher - Monitors configuration file for changes
Configuration File Detection
Gordon looks for configuration in this order:
- Path specified with
--config
/etc/gordon/gordon.toml~/.config/gordon/gordon.toml./gordon.toml
First Run
On first run without a config file, Gordon creates a default configuration at ~/.config/gordon/gordon.toml.
# First run - creates default config
gordon serve
# Edit the config, then restart
Examples
# Basic start
gordon serve
# With custom config
gordon serve --config /path/to/gordon.toml
gordon serve -c ./my-config.toml
# With environment override
GORDON_SERVER_PORT=8088 gordon serve
GORDON_LOGGING_LEVEL=debug gordon serve
Signals
Gordon responds to these signals:
| Signal |
Action |
SIGTERM |
Graceful shutdown |
SIGINT |
Graceful shutdown (Ctrl+C) |
SIGUSR1 |
Reload configuration |
SIGUSR2 |
Manual deploy request (used by local gordon deploy) |
Running with systemd
# Create user service
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gordon.service <<EOF
[Unit]
Description=Gordon Container Platform
[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/gordon serve
[Install]
WantedBy=default.target
EOF
# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now gordon
sudo loginctl enable-linger $USER
Startup Sequence
- Load configuration
- Initialize logger
- Create PID file
- Connect to Docker/Podman runtime
- Create storage directories
- Initialize services (registry, proxy, auth)
- Register event handlers
- Start config file watcher
- Start HTTP servers
- Run best-effort startup recovery (sync existing containers, then recover configured routes)
Startup Recovery
After Gordon starts, including after a host reboot, it runs a best-effort recovery pass once the listeners are bound. Errors are logged, but Gordon keeps starting.
- Sync existing containers - Gordon reconciles runtime state with configured routes.
- Recover configured routes - Gordon runs
AutoStart for any configured route that has no running container.
- Start the background monitor - Ongoing crash recovery resumes after the startup pass.
This recovery runs even when [auto_route].enabled = false. auto_route only controls whether new image pushes create routes automatically; it does not disable restart recovery for routes already in the config.
Recovery stays inside Gordon's own control flow instead of relying on Docker or Podman restart policies. That keeps the behavior consistent across both runtimes.
Startup recovery is intentionally narrower than a manual deploy. It only starts routes that are missing a running container, skips readiness checks during boot, and does not perform drain/replacement logic for routes that are already running.
Shutdown Sequence
- Receive shutdown signal
- Stop accepting new requests
- Complete in-flight requests
- Stop managed containers (if configured)
- Remove PID file
- Exit
gordon reload
Reload configuration and sync containers to match.
Synopsis
gordon reload
Description
Sends SIGUSR1 to the running Gordon process, triggering:
- Configuration file reload
- Route synchronization
- Deployment of containers for routes missing containers
- Attachment deployment
Example
# After editing gordon.toml, apply changes without restart
vim ~/.config/gordon/gordon.toml
gordon reload
gordon deploy
Manually deploy or redeploy a specific route.
Synopsis
gordon deploy <domain> [options]
Arguments
| Argument |
Description |
<domain> |
The domain name of the route to deploy (required) |
Options
Remote targeting uses client config or an active remote by default.
Use --remote and --token to override. See CLI Overview.
Description
Local mode: On the Gordon host, Gordon uses the explicit deploy path for the selected route. When the CLI cannot execute that path directly, it falls back to queueing the request with SIGUSR2 for the running server. This is different from startup recovery: startup recovery uses AutoStart, while a manual deploy performs an explicit redeploy for the selected route.
Remote mode: Calls the remote Gordon Admin API to trigger deployment. The remote Gordon instance still performs the actual deploy internally; the CLI only submits the request.
Both local and remote manual deploys use Gordon's explicit deploy path:
- Fresh image content is pulled for the route
- The specified route is redeployed
- Configured readiness checks and drain behavior apply when needed
Examples
# Local deployment
gordon deploy myapp.example.com
gordon deploy api.example.com
# Remote deployment (override)
gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
Use Cases
- Recover from a failed deployment
- Force redeploy without pushing a new image
- Manual deployment when automatic deploy didn't trigger
- Trigger deployments on remote Gordon instances from CI/CD
gordon logs
Display Gordon process logs or container logs.
Synopsis
gordon logs [domain] [options]
Arguments
| Argument |
Description |
[domain] |
Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
Options
| Option |
Short |
Default |
Description |
--config |
-c |
Auto |
Path to config file |
--follow |
-f |
false |
Follow log output (like tail -f) |
--lines |
-n |
50 |
Number of lines to show |
--remote, -r |
|
|
Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
--token |
|
|
Authentication token for remote |
Remote targeting uses client config or an active remote by default.
When you provide a concrete domain and no remote is selected, Gordon can also
auto-infer a saved remote when exactly one match is found.
Use --remote and --token to override. See CLI Overview.
Remote log access requires an admin token with admin:logs:read (or admin:*:*). admin:status:read is not sufficient for logs.
Examples
# Gordon process logs
gordon logs # Last 50 lines
gordon logs -f # Follow logs
gordon logs -n 100 # Last 100 lines
gordon logs -f -n 200 # Follow, starting from last 200 lines
# Container logs
gordon logs myapp.example.com # Last 50 lines from container
gordon logs myapp.example.com -f # Follow container logs
gordon logs myapp.example.com -n 100 # Last 100 lines from container
# Remote mode (override)
gordon logs --remote https://gordon.mydomain.com --token $TOKEN
gordon logs myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
Log Locations
# Using gordon logs
gordon logs -f
# Direct file access
tail -f ~/.gordon/logs/gordon.log
# With systemd
journalctl --user -u gordon -f
# Container logs via docker (local alternative)
docker logs --tail 50 myapp.example.com
docker logs -f myapp.example.com
gordon version
Print version information.
Synopsis
gordon version
Output
Gordon v2.0.0
Commit: abc1234
Build Date: 2024-01-15
source
1# Server Commands
2
3Commands for running and managing the Gordon server process.
4
5## gordon serve
6
7Start the Gordon server with registry and proxy components.
8
9### Synopsis
10
11```bash
12gordon serve [options]
13```
14
15### Options
16
17| Option | Short | Default | Description |
18|--------|-------|---------|-------------|
19| `--config` | `-c` | Auto-detected | Path to configuration file |
20
21### Description
22
23Starts the Gordon server, which includes:
24
25- **Container Registry** - Receives image pushes on the registry port
26- **HTTP Proxy** - Routes traffic to containers on the proxy port
27- **Event Bus** - Coordinates deployments and updates
28- **Config Watcher** - Monitors configuration file for changes
29
30### Configuration File Detection
31
32Gordon looks for configuration in this order:
33
341. Path specified with `--config`
352. `/etc/gordon/gordon.toml`
363. `~/.config/gordon/gordon.toml`
374. `./gordon.toml`
38
39### First Run
40
41On first run without a config file, Gordon creates a default configuration at `~/.config/gordon/gordon.toml`.
42
43```bash
44# First run - creates default config
45gordon serve
46# Edit the config, then restart
47```
48
49### Examples
50
51```bash
52# Basic start
53gordon serve
54
55# With custom config
56gordon serve --config /path/to/gordon.toml
57gordon serve -c ./my-config.toml
58
59# With environment override
60GORDON_SERVER_PORT=8088 gordon serve
61GORDON_LOGGING_LEVEL=debug gordon serve
62```
63
64### Signals
65
66Gordon responds to these signals:
67
68| Signal | Action |
69|--------|--------|
70| `SIGTERM` | Graceful shutdown |
71| `SIGINT` | Graceful shutdown (Ctrl+C) |
72| `SIGUSR1` | Reload configuration |
73| `SIGUSR2` | Manual deploy request (used by local `gordon deploy`) |
74
75### Running with systemd
76
77```bash
78# Create user service
79mkdir -p ~/.config/systemd/user
80cat > ~/.config/systemd/user/gordon.service <<EOF
81[Unit]
82Description=Gordon Container Platform
83
84[Service]
85Type=simple
86Restart=always
87ExecStart=/usr/local/bin/gordon serve
88
89[Install]
90WantedBy=default.target
91EOF
92
93# Enable and start
94systemctl --user daemon-reload
95systemctl --user enable --now gordon
96sudo loginctl enable-linger $USER
97```
98
99### Startup Sequence
100
1011. Load configuration
1022. Initialize logger
1033. Create PID file
1044. Connect to Docker/Podman runtime
1055. Create storage directories
1066. Initialize services (registry, proxy, auth)
1077. Register event handlers
1088. Start config file watcher
1099. Start HTTP servers
11010. Run best-effort startup recovery (sync existing containers, then recover configured routes)
111
112### Startup Recovery
113
114After Gordon starts, including after a host reboot, it runs a best-effort recovery pass once the listeners are bound. Errors are logged, but Gordon keeps starting.
115
1161. **Sync existing containers** - Gordon reconciles runtime state with configured routes.
1172. **Recover configured routes** - Gordon runs `AutoStart` for any configured route that has no running container.
1183. **Start the background monitor** - Ongoing crash recovery resumes after the startup pass.
119
120This recovery runs even when `[auto_route].enabled = false`. `auto_route` only controls whether new image pushes create routes automatically; it does not disable restart recovery for routes already in the config.
121
122Recovery stays inside Gordon's own control flow instead of relying on Docker or Podman restart policies. That keeps the behavior consistent across both runtimes.
123
124Startup recovery is intentionally narrower than a manual deploy. It only starts routes that are missing a running container, skips readiness checks during boot, and does not perform drain/replacement logic for routes that are already running.
125
126### Shutdown Sequence
127
1281. Receive shutdown signal
1292. Stop accepting new requests
1303. Complete in-flight requests
1314. Stop managed containers (if configured)
1325. Remove PID file
1336. Exit
134
135---
136
137## gordon reload
138
139Reload configuration and sync containers to match.
140
141### Synopsis
142
143```bash
144gordon reload
145```
146
147### Description
148
149Sends `SIGUSR1` to the running Gordon process, triggering:
150
151- Configuration file reload
152- Route synchronization
153- Deployment of containers for routes missing containers
154- Attachment deployment
155
156### Example
157
158```bash
159# After editing gordon.toml, apply changes without restart
160vim ~/.config/gordon/gordon.toml
161gordon reload
162```
163
164---
165
166## gordon deploy
167
168Manually deploy or redeploy a specific route.
169
170### Synopsis
171
172```bash
173gordon deploy <domain> [options]
174```
175
176### Arguments
177
178| Argument | Description |
179|----------|-------------|
180| `<domain>` | The domain name of the route to deploy (required) |
181
182### Options
183
184| Option | Description |
185|--------|-------------|
186| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
187| `--token` | Authentication token for remote |
188
189Remote targeting uses client config or an active remote by default.
190Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
191
192### Description
193
194**Local mode:** On the Gordon host, Gordon uses the explicit deploy path for the selected route. When the CLI cannot execute that path directly, it falls back to queueing the request with `SIGUSR2` for the running server. This is different from startup recovery: startup recovery uses `AutoStart`, while a manual deploy performs an explicit redeploy for the selected route.
195
196**Remote mode:** Calls the remote Gordon Admin API to trigger deployment. The remote Gordon instance still performs the actual deploy internally; the CLI only submits the request.
197
198Both local and remote manual deploys use Gordon's explicit deploy path:
199
200- Fresh image content is pulled for the route
201- The specified route is redeployed
202- Configured readiness checks and drain behavior apply when needed
203
204### Examples
205
206```bash
207# Local deployment
208gordon deploy myapp.example.com
209gordon deploy api.example.com
210
211# Remote deployment (override)
212gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
213```
214
215### Use Cases
216
217- Recover from a failed deployment
218- Force redeploy without pushing a new image
219- Manual deployment when automatic deploy didn't trigger
220- Trigger deployments on remote Gordon instances from CI/CD
221
222---
223
224## gordon logs
225
226Display Gordon process logs or container logs.
227
228### Synopsis
229
230```bash
231gordon logs [domain] [options]
232```
233
234### Arguments
235
236| Argument | Description |
237|----------|-------------|
238| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
239
240### Options
241
242| Option | Short | Default | Description |
243|--------|-------|---------|-------------|
244| `--config` | `-c` | Auto | Path to config file |
245| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
246| `--lines` | `-n` | 50 | Number of lines to show |
247| `--remote, -r` | | | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
248| `--token` | | | Authentication token for remote |
249
250Remote targeting uses client config or an active remote by default.
251When you provide a concrete domain and no remote is selected, Gordon can also
252auto-infer a saved remote when exactly one match is found.
253Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
254
255Remote log access requires an admin token with `admin:logs:read` (or `admin:*:*`). `admin:status:read` is not sufficient for logs.
256
257### Examples
258
259```bash
260# Gordon process logs
261gordon logs # Last 50 lines
262gordon logs -f # Follow logs
263gordon logs -n 100 # Last 100 lines
264gordon logs -f -n 200 # Follow, starting from last 200 lines
265
266# Container logs
267gordon logs myapp.example.com # Last 50 lines from container
268gordon logs myapp.example.com -f # Follow container logs
269gordon logs myapp.example.com -n 100 # Last 100 lines from container
270
271# Remote mode (override)
272gordon logs --remote https://gordon.mydomain.com --token $TOKEN
273gordon logs myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
274```
275
276### Log Locations
277
278```bash
279# Using gordon logs
280gordon logs -f
281
282# Direct file access
283tail -f ~/.gordon/logs/gordon.log
284
285# With systemd
286journalctl --user -u gordon -f
287
288# Container logs via docker (local alternative)
289docker logs --tail 50 myapp.example.com
290docker logs -f myapp.example.com
291```
292
293---
294
295## gordon version
296
297Print version information.
298
299### Synopsis
300
301```bash
302gordon version
303```
304
305### Output
306
307```
308Gordon v2.0.0
309Commit: abc1234
310Build Date: 2024-01-15
311```
312
313## Related
314
315- [CLI Overview](./index.md)
316- [Configuration Reference](../config/index.md)