CLI Commands
Gordon provides a command-line interface for server management, deployment, and authentication.
Commands Overview
| Command | Description |
|---|---|
gordon start |
Start the Gordon server |
gordon reload |
Reload configuration and sync containers |
gordon deploy |
Manually deploy or redeploy a specific route |
gordon logs |
Display Gordon process logs |
gordon version |
Print version information |
gordon auth |
Manage registry authentication |
Quick Reference
# Start Gordon
gordon start
gordon start --config /path/to/config.toml
# Reload configuration
gordon reload
# Deploy a specific route
gordon deploy myapp.example.com
# View logs
gordon logs
gordon logs -f
gordon logs -n 100
# Check version
gordon version
# Authentication
gordon auth token generate --subject ci-bot --expiry 0
gordon auth token list
gordon auth token revoke <token-id>
gordon auth password hash
gordon auth internal
Global Options
| Option | Description |
|---|---|
-c, --config |
Path to configuration file |
gordon start
Start the Gordon server with registry and proxy components.
Synopsis
gordon start [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 start
# Edit the config, then restart
Examples
# Basic start
gordon start
# With custom config
gordon start --config /path/to/gordon.toml
gordon start -c ./my-config.toml
# With environment override
GORDON_SERVER_PORT=8080 gordon start
GORDON_LOGGING_LEVEL=debug gordon start
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 start
[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>
Arguments
| Argument | Description |
|---|---|
<domain> |
The domain name of the route to deploy (required) |
Description
Sends SIGUSR2 to the Gordon process with the specified domain, triggering:
- Fresh image pull (always pulls latest, ignoring cache)
- Container redeployment for the specified route
Examples
gordon deploy myapp.example.com
gordon deploy api.example.com
Use Cases
- Recover from a failed deployment
- Force redeploy without pushing a new image
- Manual deployment when automatic deploy didn't trigger
gordon logs
Display Gordon process logs.
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 |
Examples
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
Log Locations
# Using gordon logs
gordon logs -f
# Direct file access
tail -f ~/.gordon/logs/gordon.log
# With systemd
journalctl --user -u gordon -f
gordon version
Print version information.
Synopsis
gordon version
Output
Gordon v2.0.0
Commit: abc1234
Build Date: 2024-01-15
gordon auth
Manage registry authentication tokens and passwords.
Subcommands
| Subcommand | Description |
|---|---|
token generate |
Generate a new JWT token |
token list |
List all stored tokens |
token revoke |
Revoke a token by ID |
password hash |
Generate bcrypt password hash |
internal |
Show internal registry credentials |
gordon auth token generate
Generate a new JWT authentication token for registry access.
gordon auth token generate --subject <name> [options]
Options:
| Option | Default | Description |
|---|---|---|
--subject |
(required) | Username/subject for the token |
--scopes |
push,pull |
Comma-separated scopes |
--expiry |
720h |
Duration until expiry (0 = never) |
-c, --config |
Auto | Path to config file |
Examples:
# CI token that never expires
gordon auth token generate --subject github-actions --expiry 0
# Read-only token
gordon auth token generate --subject reader --scopes pull --expiry 720h
# Push-only token for build system
gordon auth token generate --subject builder --scopes push --expiry 0
# Temporary token (24 hours)
gordon auth token generate --subject temp --expiry 24h
Output:
Token generated successfully!
Subject: github-actions
Scopes: push, pull
Expiry: never
Token (use as password with docker login):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Usage: docker login -u github-actions -p <token> <registry>
gordon auth token list
List all stored authentication tokens.
gordon auth token list [options]
Output:
ID Subject Expires Revoked
------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-7890-abcd-ef1234567890 github-actions never no
b2c3d4e5-f6a7-8901-bcde-f12345678901 deploy-bot 2024-02-15 10:30 no
c3d4e5f6-a7b8-9012-cdef-123456789012 old-token 2024-01-01 00:00 yes
gordon auth token revoke
Revoke a token by its ID.
gordon auth token revoke <token-id> [options]
Example:
gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
Output:
Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
gordon auth password hash
Generate a bcrypt hash for password authentication.
gordon auth password hash
Interactively prompts for a password and outputs the bcrypt hash.
Output:
Enter password: ********
Bcrypt hash (store in your secrets backend):
$2a$10$N9qo8uLOickgx2ZMRZoMye...
Then reference the path in your config:
[registry_auth]
type = "password"
password_hash = "gordon/registry/password_hash"
gordon auth internal
Display the auto-generated internal registry credentials.
gordon auth internal
Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
Output:
Internal Registry Credentials
==============================
Username: gordon-internal
Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
Usage:
docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
Notes:
- Credentials are regenerated each time Gordon starts
- Only available while Gordon is running
- Used for manual
docker pullfrom the local registry during debugging
Use cases:
- Debugging image pull failures
- Manual recovery after deployment issues
- Inspecting images in the local registry
Token Scopes
| Scope | Permission |
|---|---|
push |
Push images to registry |
pull |
Pull images from registry |
push,pull |
Both push and pull (default) |
Token Expiry Formats
| Format | Duration |
|---|---|
0 |
Never expires |
24h |
24 hours |
720h |
30 days |
8760h |
1 year |
Workflow Examples
CI/CD Setup
# Generate token for CI
gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
# Save token as CI secret
# GitHub: Settings → Secrets → New repository secret
# GitLab: Settings → CI/CD → Variables
Docker Login
# Using generated token
docker login -u ci-bot -p <token> registry.mydomain.com
# In CI/CD
echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
Token Rotation
# Generate new token
gordon auth token generate --subject ci-bot --expiry 0
# Update CI secrets with new token
# Revoke old token
gordon auth token revoke <old-token-id>
Password Setup
# Generate hash
gordon auth password hash
# Enter: mypassword
# Store in pass
pass insert gordon/registry/password_hash
# Paste: $2a$10$...
# Configure gordon.toml
[registry_auth]
enabled = true
type = "password"
username = "deploy"
password_hash = "gordon/registry/password_hash"
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Configuration error |
Environment Variables
Gordon reads configuration from environment variables:
GORDON_SERVER_PORT=8080 gordon start
GORDON_LOGGING_LEVEL=debug gordon start
Pattern: GORDON_SECTION_KEY (uppercase, underscores)