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 version
132
133Print version information.
134
135### Synopsis
136
137```bash
138gordon version
139```
140
141### Output
142
143```
144Gordon v2.0.0
145Commit: abc1234
146Build Date: 2024-01-15
147```
148
149## Related
150
151- [CLI Overview](./index.md)
152- [Configuration Reference](../config/index.md)