bnema.dev

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:

  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.

# 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

  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 (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.

  1. 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).
  2. 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

  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 version

Print version information.

Synopsis

gordon version

Output

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