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
- Reverse Proxy - Routes app hosts to recorded loopback backends
- Event Bus - Coordinates runtime notifications
- 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 installation configuration |
SIGUSR2 |
Reserved; no app deployment action |
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 (reconcile apps intended to run from active state)
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.
- Reconcile app boot state - Gordon ensures apps intended to run are running from active state (stopped-intent apps stay stopped, pending desired revisions are never activated).
- Start the background monitor - Ongoing crash recovery resumes after the startup pass.
Reload and startup recovery never activate pending desired app state, re-resolve images, or flip intent. They touch installation settings and runtime reconciliation only.
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 installation configuration.
Synopsis
gordon reload
Description
Sends SIGUSR1 to the running Gordon process, triggering:
- Installation settings reload (live keys apply, restart-required keys are reported)
- Traffic/proxy state refresh from ACTIVE app projection
Reload never activates pending desired app state, re-resolves images, or flips intent. Obsolete application keys (routes, attachments, services, auto, previews, …) are rejected with a config-retired diagnostic before any mutation.
Example
# After editing gordon.toml, apply changes without restart
vim ~/.config/gordon/gordon.toml
gordon reload
gordon logs
Display Gordon daemon process logs. Application workload output is read with
gordon apps logs APP --service SVC, which resolves the app's active container
through the daemon.
Synopsis
gordon logs [options]
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. 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
# App service logs
gordon apps logs blog --service web
gordon apps logs blog --service web --follow --remote prod
# Remote process logs (override)
gordon logs --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
# App service logs through Gordon
gordon apps logs blog --service web --tail 50
gordon apps logs blog --service web --follow
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- **Reverse Proxy** - Routes app hosts to recorded loopback backends
27- **Event Bus** - Coordinates runtime notifications
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 installation configuration |
72| `SIGUSR2` | Reserved; no app deployment action |
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 (reconcile apps intended to run from active state)
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. **Reconcile app boot state** - Gordon ensures apps intended to run are running from active state (stopped-intent apps stay stopped, pending desired revisions are never activated).
1164. **Start the background monitor** - Ongoing crash recovery resumes after the startup pass.
117
118Reload and startup recovery never activate pending desired app state, re-resolve images, or flip intent. They touch installation settings and runtime reconciliation only.
119
120### Shutdown Sequence
121
1221. Receive shutdown signal
1232. Stop accepting new requests
1243. Complete in-flight requests
1254. Stop managed containers (if configured)
1265. Remove PID file
1276. Exit
128
129---
130
131## gordon reload
132
133Reload installation configuration.
134
135### Synopsis
136
137```bash
138gordon reload
139```
140
141### Description
142
143Sends `SIGUSR1` to the running Gordon process, triggering:
144
145- Installation settings reload (live keys apply, restart-required keys are reported)
146- Traffic/proxy state refresh from ACTIVE app projection
147
148Reload never activates pending desired app state, re-resolves images, or flips intent. Obsolete application keys (`routes`, `attachments`, `services`, `auto`, previews, …) are rejected with a `config-retired` diagnostic before any mutation.
149
150### Example
151
152```bash
153# After editing gordon.toml, apply changes without restart
154vim ~/.config/gordon/gordon.toml
155gordon reload
156```
157
158---
159
160## gordon logs
161
162Display Gordon daemon process logs. Application workload output is read with
163`gordon apps logs APP --service SVC`, which resolves the app's active container
164through the daemon.
165
166### Synopsis
167
168```bash
169gordon logs [options]
170```
171
172### Options
173
174| Option | Short | Default | Description |
175|--------|-------|---------|-------------|
176| `--config` | `-c` | Auto | Path to config file |
177| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
178| `--lines` | `-n` | 50 | Number of lines to show |
179| `--remote, -r` | | | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
180| `--token` | | | Authentication token for remote |
181
182Remote targeting uses client config or an active remote by default. Use
183`--remote` and `--token` to override. See [CLI Overview](./index.md).
184
185Remote log access requires an admin token with `admin:logs:read` (or `admin:*:*`). `admin:status:read` is not sufficient for logs.
186
187### Examples
188
189```bash
190# Gordon process logs
191gordon logs # Last 50 lines
192gordon logs -f # Follow logs
193gordon logs -n 100 # Last 100 lines
194gordon logs -f -n 200 # Follow, starting from last 200 lines
195
196# App service logs
197gordon apps logs blog --service web
198gordon apps logs blog --service web --follow --remote prod
199
200# Remote process logs (override)
201gordon logs --remote https://gordon.mydomain.com --token $TOKEN
202```
203
204### Log Locations
205
206```bash
207# Using gordon logs
208gordon logs -f
209
210# Direct file access
211tail -f ~/.gordon/logs/gordon.log
212
213# With systemd
214journalctl --user -u gordon -f
215
216# App service logs through Gordon
217gordon apps logs blog --service web --tail 50
218gordon apps logs blog --service web --follow
219```
220
221---
222
223## gordon version
224
225Print version information.
226
227### Synopsis
228
229```bash
230gordon version
231```
232
233### Output
234
235```
236Gordon v2.0.0
237Commit: abc1234
238Build Date: 2024-01-15
239```
240
241## Related
242
243- [CLI Overview](./index.md)
244- [Configuration Reference](../config/index.md)