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=8080 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 (used by 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
- Sync existing containers
- Start HTTP servers
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: Sends SIGUSR2 to the Gordon process with the specified domain.
Remote mode: Calls the remote Gordon Admin API to trigger deployment.
Both modes trigger:
- Fresh image pull (always pulls latest, ignoring cache)
- Container redeployment for the specified route
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.
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=8080 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 (used by `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. Sync existing containers
11010. Start HTTP servers
111
112### Shutdown Sequence
113
1141. Receive shutdown signal
1152. Stop accepting new requests
1163. Complete in-flight requests
1174. Stop managed containers (if configured)
1185. Remove PID file
1196. Exit
120
121---
122
123## gordon reload
124
125Reload configuration and sync containers to match.
126
127### Synopsis
128
129```bash
130gordon reload
131```
132
133### Description
134
135Sends `SIGUSR1` to the running Gordon process, triggering:
136
137- Configuration file reload
138- Route synchronization
139- Deployment of containers for routes missing containers
140- Attachment deployment
141
142### Example
143
144```bash
145# After editing gordon.toml, apply changes without restart
146vim ~/.config/gordon/gordon.toml
147gordon reload
148```
149
150---
151
152## gordon deploy
153
154Manually deploy or redeploy a specific route.
155
156### Synopsis
157
158```bash
159gordon deploy <domain> [options]
160```
161
162### Arguments
163
164| Argument | Description |
165|----------|-------------|
166| `<domain>` | The domain name of the route to deploy (required) |
167
168### Options
169
170| Option | Description |
171|--------|-------------|
172| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
173| `--token` | Authentication token for remote |
174
175Remote targeting uses client config or an active remote by default.
176Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
177
178### Description
179
180**Local mode:** Sends `SIGUSR2` to the Gordon process with the specified domain.
181
182**Remote mode:** Calls the remote Gordon Admin API to trigger deployment.
183
184Both modes trigger:
185
186- Fresh image pull (always pulls latest, ignoring cache)
187- Container redeployment for the specified route
188
189### Examples
190
191```bash
192# Local deployment
193gordon deploy myapp.example.com
194gordon deploy api.example.com
195
196# Remote deployment (override)
197gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
198```
199
200### Use Cases
201
202- Recover from a failed deployment
203- Force redeploy without pushing a new image
204- Manual deployment when automatic deploy didn't trigger
205- Trigger deployments on remote Gordon instances from CI/CD
206
207---
208
209## gordon logs
210
211Display Gordon process logs or container logs.
212
213### Synopsis
214
215```bash
216gordon logs [domain] [options]
217```
218
219### Arguments
220
221| Argument | Description |
222|----------|-------------|
223| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
224
225### Options
226
227| Option | Short | Default | Description |
228|--------|-------|---------|-------------|
229| `--config` | `-c` | Auto | Path to config file |
230| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
231| `--lines` | `-n` | 50 | Number of lines to show |
232| `--remote, -r` | | | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
233| `--token` | | | Authentication token for remote |
234
235Remote targeting uses client config or an active remote by default.
236Use `--remote` and `--token` to override. See [CLI Overview](./index.md).
237
238Remote log access requires an admin token with `admin:logs:read` (or `admin:*:*`). `admin:status:read` is not sufficient for logs.
239
240### Examples
241
242```bash
243# Gordon process logs
244gordon logs # Last 50 lines
245gordon logs -f # Follow logs
246gordon logs -n 100 # Last 100 lines
247gordon logs -f -n 200 # Follow, starting from last 200 lines
248
249# Container logs
250gordon logs myapp.example.com # Last 50 lines from container
251gordon logs myapp.example.com -f # Follow container logs
252gordon logs myapp.example.com -n 100 # Last 100 lines from container
253
254# Remote mode (override)
255gordon logs --remote https://gordon.mydomain.com --token $TOKEN
256gordon logs myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
257```
258
259### Log Locations
260
261```bash
262# Using gordon logs
263gordon logs -f
264
265# Direct file access
266tail -f ~/.gordon/logs/gordon.log
267
268# With systemd
269journalctl --user -u gordon -f
270
271# Container logs via docker (local alternative)
272docker logs --tail 50 myapp.example.com
273docker logs -f myapp.example.com
274```
275
276---
277
278## gordon version
279
280Print version information.
281
282### Synopsis
283
284```bash
285gordon version
286```
287
288### Output
289
290```
291Gordon v2.0.0
292Commit: abc1234
293Build Date: 2024-01-15
294```
295
296## Related
297
298- [CLI Overview](./index.md)
299- [Configuration Reference](../config/index.md)