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_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_LOGGING_LEVEL=debug gordon serve
61```
62
63### Signals
64
65Gordon responds to these signals:
66
67| Signal | Action |
68|--------|--------|
69| `SIGTERM` | Graceful shutdown |
70| `SIGINT` | Graceful shutdown (Ctrl+C) |
71| `SIGUSR1` | Reload configuration |
72| `SIGUSR2` | Manual deploy request (used by local `gordon deploy`) |
73
74### Running with systemd
75
76```bash
77# Create user service
78mkdir -p ~/.config/systemd/user
79cat > ~/.config/systemd/user/gordon.service <<EOF
80[Unit]
81Description=Gordon Container Platform
82
83[Service]
84Type=simple
85Restart=always
86ExecStart=/usr/local/bin/gordon serve
87
88[Install]
89WantedBy=default.target
90EOF
91
92# Enable and start
93systemctl --user daemon-reload
94systemctl --user enable --now gordon
95sudo loginctl enable-linger $USER
96```
97
98### Startup Sequence
99
1001. Load configuration
1012. Initialize logger
1023. Create PID file
1034. Connect to Docker/Podman runtime
1045. Create storage directories
1056. Initialize services (registry, proxy, auth)
1067. Register event handlers
1078. Start config file watcher
1089. Start HTTP servers
10910. Run best-effort startup recovery (sync existing containers, then recover configured routes)
110
111### Startup Recovery
112
113After 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.
114
1151. **Sync existing containers** - Gordon reconciles runtime state with configured routes.
1162. **Recover configured routes** - Gordon runs `AutoStart` for any configured route that has no running container.
1173. **Start the background monitor** - Ongoing crash recovery resumes after the startup pass.
118
119This 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.
120
121Recovery stays inside Gordon's own control flow instead of relying on Docker or Podman restart policies. That keeps the behavior consistent across both runtimes.
122
123Startup 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.
124
125### Shutdown Sequence
126
1271. Receive shutdown signal
1282. Stop accepting new requests
1293. Complete in-flight requests
1304. Stop managed containers (if configured)
1315. Remove PID file
1326. Exit
133
134---
135
136## gordon reload
137
138Reload configuration and sync containers to match.
139
140### Synopsis
141
142```bash
143gordon reload
144```
145
146### Description
147
148Sends `SIGUSR1` to the running Gordon process, triggering:
149
150- Configuration file reload
151- Route synchronization
152- Deployment of containers for routes missing containers
153- Attachment deployment
154
155### Example
156
157```bash
158# After editing gordon.toml, apply changes without restart
159vim ~/.config/gordon/gordon.toml
160gordon reload
161```
162
163---
164
165## gordon deploy
166
167Manually deploy or redeploy a specific route.
168
169### Synopsis
170
171```bash
172gordon deploy <domain> [options]
173```
174
175### Arguments
176
177| Argument | Description |
178|----------|-------------|
179| `<domain>` | The domain name of the route to deploy (required) |
180
181### Options
182
183| Option | Description |
184|--------|-------------|
185| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
186| `--token` | Authentication token for remote |
187
188Remote targeting uses client config or an active remote by default.
189Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
190
191### Description
192
193**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.
194
195**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.
196
197Both local and remote manual deploys use Gordon's explicit deploy path:
198
199- Fresh image content is pulled for the route
200- The specified route is redeployed
201- Configured readiness checks and drain behavior apply when needed
202
203### Examples
204
205```bash
206# Local deployment
207gordon deploy myapp.example.com
208gordon deploy api.example.com
209
210# Remote deployment (override)
211gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
212```
213
214### Use Cases
215
216- Recover from a failed deployment
217- Force redeploy without pushing a new image
218- Manual deployment when automatic deploy didn't trigger
219- Trigger deployments on remote Gordon instances from CI/CD
220
221---
222
223## gordon logs
224
225Display Gordon process logs or container logs.
226
227### Synopsis
228
229```bash
230gordon logs [domain] [options]
231```
232
233### Arguments
234
235| Argument | Description |
236|----------|-------------|
237| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
238
239### Options
240
241| Option | Short | Default | Description |
242|--------|-------|---------|-------------|
243| `--config` | `-c` | Auto | Path to config file |
244| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
245| `--lines` | `-n` | 50 | Number of lines to show |
246| `--remote, -r` | | | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
247| `--token` | | | Authentication token for remote |
248
249Remote targeting uses client config or an active remote by default.
250When you provide a concrete domain and no remote is selected, Gordon can also
251auto-infer a saved remote when exactly one match is found.
252Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
253
254Remote log access requires an admin token with `admin:logs:read` (or `admin:*:*`). `admin:status:read` is not sufficient for logs.
255
256### Examples
257
258```bash
259# Gordon process logs
260gordon logs # Last 50 lines
261gordon logs -f # Follow logs
262gordon logs -n 100 # Last 100 lines
263gordon logs -f -n 200 # Follow, starting from last 200 lines
264
265# Container logs
266gordon logs myapp.example.com # Last 50 lines from container
267gordon logs myapp.example.com -f # Follow container logs
268gordon logs myapp.example.com -n 100 # Last 100 lines from container
269
270# Remote mode (override)
271gordon logs --remote https://gordon.mydomain.com --token $TOKEN
272gordon logs myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
273```
274
275### Log Locations
276
277```bash
278# Using gordon logs
279gordon logs -f
280
281# Direct file access
282tail -f ~/.gordon/logs/gordon.log
283
284# With systemd
285journalctl --user -u gordon -f
286
287# Container logs via docker (local alternative)
288docker logs --tail 50 myapp.example.com
289docker logs -f myapp.example.com
290```
291
292---
293
294## gordon version
295
296Print version information.
297
298### Synopsis
299
300```bash
301gordon version
302```
303
304### Output
305
306```
307Gordon v2.0.0
308Commit: abc1234
309Build Date: 2024-01-15
310```
311
312## Related
313
314- [CLI Overview](./index.md)
315- [Configuration Reference](../config/index.md)