# Server Commands

Commands for running and managing the Gordon server process.

## gordon serve

Start the Gordon server with registry and proxy components.

### Synopsis

```bash
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:

1. Path specified with `--config`
2. `/etc/gordon/gordon.toml`
3. `~/.config/gordon/gordon.toml`
4. `./gordon.toml`

### First Run

On first run without a config file, Gordon creates a default configuration at `~/.config/gordon/gordon.toml`.

```bash
# First run - creates default config
gordon serve
# Edit the config, then restart
```

### Examples

```bash
# 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

```bash
# 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

1. Load configuration
2. Initialize logger
3. Create PID file
4. Connect to Docker/Podman runtime
5. Create storage directories
6. Initialize services (registry, proxy, auth)
7. Register event handlers
8. Start config file watcher
9. Start HTTP servers
10. 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.

1. **Sync existing containers** - Gordon reconciles runtime state with configured routes.
2. **Recover configured routes** - Gordon runs `AutoStart` for any configured route that has no running container.
3. **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

1. Receive shutdown signal
2. Stop accepting new requests
3. Complete in-flight requests
4. Stop managed containers (if configured)
5. Remove PID file
6. Exit

---

## gordon reload

Reload configuration and sync containers to match.

### Synopsis

```bash
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

```bash
# 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

```bash
gordon deploy <domain> [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<domain>` | The domain name of the route to deploy (required) |

### Options

| Option | Description |
|--------|-------------|
| `--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](./index.md).

### 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

```bash
# 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

```bash
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](./index.md).

Remote log access requires an admin token with `admin:logs:read` (or `admin:*:*`). `admin:status:read` is not sufficient for logs.

### Examples

```bash
# 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

```bash
# 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

```bash
gordon version
```

### Output

```
Gordon v2.0.0
Commit: abc1234
Build Date: 2024-01-15
```

## Related

- [CLI Overview](./index.md)
- [Configuration Reference](../config/index.md)