commands.md Raw History Folder

CLI Commands

Gordon provides a command-line interface for server management, deployment, and authentication.

Commands Overview

Command	Description
`gordon serve`	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 or container logs
`gordon version`	Print version information
`gordon auth`	Manage registry authentication
`gordon routes`	Manage routes (local or remote)
`gordon secrets`	Manage secrets (local or remote)
`gordon remotes`	Manage saved remote Gordon instances

Quick Reference

# Start Gordon
gordon serve
gordon serve --config /path/to/config.toml

# Reload configuration
gordon reload

# Deploy a specific route
gordon deploy myapp.example.com

# View logs
gordon logs                          # Gordon process logs
gordon logs -f                       # Follow process logs
gordon logs -n 100                   # Last 100 lines
gordon logs myapp.local              # Container logs for myapp.local
gordon logs myapp.local -f           # Follow container logs

# 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
`--remote`	Remote Gordon URL (e.g., `https://gordon.mydomain.com`)
`--token`	Authentication token for remote

Remote Targeting

The CLI can target remote Gordon instances using the --remote flag or GORDON_REMOTE environment variable.

Important: The remote URL must be the gordon_domain configured on the remote Gordon instance. This is the domain that serves both the container registry and the Admin API.

# Using flags (use the gordon_domain from remote Gordon config)
gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

# Using environment variables
export GORDON_REMOTE=https://gordon.mydomain.com
export GORDON_TOKEN=$TOKEN
gordon routes list

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

Option	Description
`--remote`	Remote Gordon URL
`--token`	Authentication token for remote

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
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`			Remote Gordon URL
`--token`			Authentication token for remote

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.local           # Last 50 lines from container
gordon logs myapp.local -f        # Follow container logs
gordon logs myapp.local -n 100    # Last 100 lines from container

# Remote mode
gordon logs --remote https://gordon.mydomain.com --token $TOKEN
gordon logs myapp.local --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.local
docker logs -f myapp.local

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 pull from 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

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

gordon routes

Manage routes on local or remote Gordon instances.

Subcommands

Subcommand	Description
`list`	List all routes
`add`	Add a new route
`remove`	Remove a route
`deploy`	Deploy a specific route

gordon routes list

List all configured routes.

gordon routes list
gordon routes list --remote https://gordon.mydomain.com --token $TOKEN

gordon routes add

Add a new route.

gordon routes add <domain> <image>
gordon routes add myapp.example.com myapp:latest

gordon routes remove

Remove a route.

gordon routes remove <domain>
gordon routes remove myapp.example.com

gordon routes deploy

Deploy or redeploy a specific route.

gordon routes deploy <domain>
gordon routes deploy myapp.example.com

gordon secrets

Manage secrets on local or remote Gordon instances.

Subcommands

Subcommand	Description
`list`	List all secrets for a domain
`set`	Set a secret value
`remove`	Remove a secret

Examples

# Local mode (reads/writes secrets directly)
gordon secrets list myapp.local
gordon secrets set myapp.local DATABASE_URL "postgres://..."
gordon secrets remove myapp.local DATABASE_URL

# Remote mode
gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote ... --token ...
gordon secrets remove myapp.local DATABASE_URL --remote ... --token ...

gordon remotes

Manage saved remote Gordon instances for easier CLI usage.

Subcommands

Subcommand	Description
`list`	List saved remotes
`add`	Add a new remote
`remove`	Remove a saved remote
`use`	Set active remote

Examples

# Add a remote
gordon remotes add prod https://gordon.mydomain.com --token $TOKEN

# List saved remotes
gordon remotes list

# Set active remote
gordon remotes use prod

# Now use without --remote flag
gordon routes list

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 serve
GORDON_LOGGING_LEVEL=debug gordon serve

Pattern: GORDON_SECTION_KEY (uppercase, underscores)

source

1# CLI Commands
2
3Gordon provides a command-line interface for server management, deployment, and authentication.
4
5## Commands Overview
6
7| Command | Description |
8|---------|-------------|
9| `gordon serve` | Start the Gordon server |
10| `gordon reload` | Reload configuration and sync containers |
11| `gordon deploy` | Manually deploy or redeploy a specific route |
12| `gordon logs` | Display Gordon process or container logs |
13| `gordon version` | Print version information |
14| `gordon auth` | Manage registry authentication |
15| `gordon routes` | Manage routes (local or remote) |
16| `gordon secrets` | Manage secrets (local or remote) |
17| `gordon remotes` | Manage saved remote Gordon instances |
18
19## Quick Reference
20
21```bash
22# Start Gordon
23gordon serve
24gordon serve --config /path/to/config.toml
25
26# Reload configuration
27gordon reload
28
29# Deploy a specific route
30gordon deploy myapp.example.com
31
32# View logs
33gordon logs                          # Gordon process logs
34gordon logs -f                       # Follow process logs
35gordon logs -n 100                   # Last 100 lines
36gordon logs myapp.local              # Container logs for myapp.local
37gordon logs myapp.local -f           # Follow container logs
38
39# Check version
40gordon version
41
42# Authentication
43gordon auth token generate --subject ci-bot --expiry 0
44gordon auth token list
45gordon auth token revoke <token-id>
46gordon auth password hash
47gordon auth internal
48```
49
50## Global Options
51
52| Option | Description |
53|--------|-------------|
54| `-c, --config` | Path to configuration file |
55| `--remote` | Remote Gordon URL (e.g., `https://gordon.mydomain.com`) |
56| `--token` | Authentication token for remote |
57
58### Remote Targeting
59
60The CLI can target remote Gordon instances using the `--remote` flag or `GORDON_REMOTE` environment variable.
61
62**Important:** The remote URL must be the `gordon_domain` configured on the remote Gordon instance. This is the domain that serves both the container registry and the Admin API.
63
64```bash
65# Using flags (use the gordon_domain from remote Gordon config)
66gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
67
68# Using environment variables
69export GORDON_REMOTE=https://gordon.mydomain.com
70export GORDON_TOKEN=$TOKEN
71gordon routes list
72```
73
74---
75
76## gordon serve
77
78Start the Gordon server with registry and proxy components.
79
80### Synopsis
81
82```bash
83gordon serve [options]
84```
85
86### Options
87
88| Option | Short | Default | Description |
89|--------|-------|---------|-------------|
90| `--config` | `-c` | Auto-detected | Path to configuration file |
91
92### Description
93
94Starts the Gordon server, which includes:
95
96- **Container Registry** - Receives image pushes on the registry port
97- **HTTP Proxy** - Routes traffic to containers on the proxy port
98- **Event Bus** - Coordinates deployments and updates
99- **Config Watcher** - Monitors configuration file for changes
100
101### Configuration File Detection
102
103Gordon looks for configuration in this order:
104
1051. Path specified with `--config`
1062. `/etc/gordon/gordon.toml`
1073. `~/.config/gordon/gordon.toml`
1084. `./gordon.toml`
109
110### First Run
111
112On first run without a config file, Gordon creates a default configuration at `~/.config/gordon/gordon.toml`.
113
114```bash
115# First run - creates default config
116gordon serve
117# Edit the config, then restart
118```
119
120### Examples
121
122```bash
123# Basic start
124gordon serve
125
126# With custom config
127gordon serve --config /path/to/gordon.toml
128gordon serve -c ./my-config.toml
129
130# With environment override
131GORDON_SERVER_PORT=8080 gordon serve
132GORDON_LOGGING_LEVEL=debug gordon serve
133```
134
135### Signals
136
137Gordon responds to these signals:
138
139| Signal | Action |
140|--------|--------|
141| `SIGTERM` | Graceful shutdown |
142| `SIGINT` | Graceful shutdown (Ctrl+C) |
143| `SIGUSR1` | Reload configuration |
144| `SIGUSR2` | Manual deploy (used by `gordon deploy`) |
145
146### Running with systemd
147
148```bash
149# Create user service
150mkdir -p ~/.config/systemd/user
151cat > ~/.config/systemd/user/gordon.service <<EOF
152[Unit]
153Description=Gordon Container Platform
154
155[Service]
156Type=simple
157Restart=always
158ExecStart=/usr/local/bin/gordon serve
159
160[Install]
161WantedBy=default.target
162EOF
163
164# Enable and start
165systemctl --user daemon-reload
166systemctl --user enable --now gordon
167sudo loginctl enable-linger $USER
168```
169
170### Startup Sequence
171
1721. Load configuration
1732. Initialize logger
1743. Create PID file
1754. Connect to Docker/Podman runtime
1765. Create storage directories
1776. Initialize services (registry, proxy, auth)
1787. Register event handlers
1798. Start config file watcher
1809. Sync existing containers
18110. Start HTTP servers
182
183### Shutdown Sequence
184
1851. Receive shutdown signal
1862. Stop accepting new requests
1873. Complete in-flight requests
1884. Stop managed containers (if configured)
1895. Remove PID file
1906. Exit
191
192---
193
194## gordon reload
195
196Reload configuration and sync containers to match.
197
198### Synopsis
199
200```bash
201gordon reload
202```
203
204### Description
205
206Sends `SIGUSR1` to the running Gordon process, triggering:
207
208- Configuration file reload
209- Route synchronization
210- Deployment of containers for routes missing containers
211- Attachment deployment
212
213### Example
214
215```bash
216# After editing gordon.toml, apply changes without restart
217vim ~/.config/gordon/gordon.toml
218gordon reload
219```
220
221---
222
223## gordon deploy
224
225Manually deploy or redeploy a specific route.
226
227### Synopsis
228
229```bash
230gordon deploy <domain> [options]
231```
232
233### Arguments
234
235| Argument | Description |
236|----------|-------------|
237| `<domain>` | The domain name of the route to deploy (required) |
238
239### Options
240
241| Option | Description |
242|--------|-------------|
243| `--remote` | Remote Gordon URL |
244| `--token` | Authentication token for remote |
245
246### Description
247
248**Local mode:** Sends `SIGUSR2` to the Gordon process with the specified domain.
249
250**Remote mode:** Calls the remote Gordon Admin API to trigger deployment.
251
252Both modes trigger:
253
254- Fresh image pull (always pulls latest, ignoring cache)
255- Container redeployment for the specified route
256
257### Examples
258
259```bash
260# Local deployment
261gordon deploy myapp.example.com
262gordon deploy api.example.com
263
264# Remote deployment
265gordon deploy myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
266```
267
268### Use Cases
269
270- Recover from a failed deployment
271- Force redeploy without pushing a new image
272- Manual deployment when automatic deploy didn't trigger
273- Trigger deployments on remote Gordon instances from CI/CD
274
275---
276
277## gordon logs
278
279Display Gordon process logs or container logs.
280
281### Synopsis
282
283```bash
284gordon logs [domain] [options]
285```
286
287### Arguments
288
289| Argument | Description |
290|----------|-------------|
291| `[domain]` | Optional. Container domain to view logs for. Without this, shows Gordon process logs. |
292
293### Options
294
295| Option | Short | Default | Description |
296|--------|-------|---------|-------------|
297| `--config` | `-c` | Auto | Path to config file |
298| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
299| `--lines` | `-n` | 50 | Number of lines to show |
300| `--remote` | | | Remote Gordon URL |
301| `--token` | | | Authentication token for remote |
302
303### Examples
304
305```bash
306# Gordon process logs
307gordon logs              # Last 50 lines
308gordon logs -f           # Follow logs
309gordon logs -n 100       # Last 100 lines
310gordon logs -f -n 200    # Follow, starting from last 200 lines
311
312# Container logs
313gordon logs myapp.local           # Last 50 lines from container
314gordon logs myapp.local -f        # Follow container logs
315gordon logs myapp.local -n 100    # Last 100 lines from container
316
317# Remote mode
318gordon logs --remote https://gordon.mydomain.com --token $TOKEN
319gordon logs myapp.local --remote https://gordon.mydomain.com --token $TOKEN
320```
321
322### Log Locations
323
324```bash
325# Using gordon logs
326gordon logs -f
327
328# Direct file access
329tail -f ~/.gordon/logs/gordon.log
330
331# With systemd
332journalctl --user -u gordon -f
333
334# Container logs via docker (local alternative)
335docker logs --tail 50 myapp.local
336docker logs -f myapp.local
337```
338
339---
340
341## gordon version
342
343Print version information.
344
345### Synopsis
346
347```bash
348gordon version
349```
350
351### Output
352
353```
354Gordon v2.0.0
355Commit: abc1234
356Build Date: 2024-01-15
357```
358
359---
360
361## gordon auth
362
363Manage registry authentication tokens and passwords.
364
365### Subcommands
366
367| Subcommand | Description |
368|------------|-------------|
369| `token generate` | Generate a new JWT token |
370| `token list` | List all stored tokens |
371| `token revoke` | Revoke a token by ID |
372| `password hash` | Generate bcrypt password hash |
373| `internal` | Show internal registry credentials |
374
375### gordon auth token generate
376
377Generate a new JWT authentication token for registry access.
378
379```bash
380gordon auth token generate --subject <name> [options]
381```
382
383**Options:**
384
385| Option | Default | Description |
386|--------|---------|-------------|
387| `--subject` | (required) | Username/subject for the token |
388| `--scopes` | `push,pull` | Comma-separated scopes |
389| `--expiry` | `720h` | Duration until expiry (0 = never) |
390| `-c, --config` | Auto | Path to config file |
391
392**Examples:**
393
394```bash
395# CI token that never expires
396gordon auth token generate --subject github-actions --expiry 0
397
398# Read-only token
399gordon auth token generate --subject reader --scopes pull --expiry 720h
400
401# Push-only token for build system
402gordon auth token generate --subject builder --scopes push --expiry 0
403
404# Temporary token (24 hours)
405gordon auth token generate --subject temp --expiry 24h
406```
407
408**Output:**
409
410```
411Token generated successfully!
412Subject: github-actions
413Scopes: push, pull
414Expiry: never
415
416Token (use as password with docker login):
417eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
418
419Usage: docker login -u github-actions -p <token> <registry>
420```
421
422### gordon auth token list
423
424List all stored authentication tokens.
425
426```bash
427gordon auth token list [options]
428```
429
430**Output:**
431
432```
433ID                                    Subject               Expires               Revoked
434------------------------------------------------------------------------------------------
435a1b2c3d4-e5f6-7890-abcd-ef1234567890  github-actions        never                 no
436b2c3d4e5-f6a7-8901-bcde-f12345678901  deploy-bot            2024-02-15 10:30      no
437c3d4e5f6-a7b8-9012-cdef-123456789012  old-token             2024-01-01 00:00      yes
438```
439
440### gordon auth token revoke
441
442Revoke a token by its ID.
443
444```bash
445gordon auth token revoke <token-id> [options]
446```
447
448**Example:**
449
450```bash
451gordon auth token revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
452```
453
454**Output:**
455
456```
457Token a1b2c3d4-e5f6-7890-abcd-ef1234567890 has been revoked.
458```
459
460### gordon auth password hash
461
462Generate a bcrypt hash for password authentication.
463
464```bash
465gordon auth password hash
466```
467
468Interactively prompts for a password and outputs the bcrypt hash.
469
470**Output:**
471
472```
473Enter password: ********
474
475Bcrypt hash (store in your secrets backend):
476$2a$10$N9qo8uLOickgx2ZMRZoMye...
477
478Then reference the path in your config:
479  [registry_auth]
480  type = "password"
481  password_hash = "gordon/registry/password_hash"
482```
483
484### gordon auth internal
485
486Display the auto-generated internal registry credentials.
487
488```bash
489gordon auth internal
490```
491
492Gordon generates temporary credentials for internal communication with its local registry. These credentials are useful for manual recovery when debugging deployment issues.
493
494**Output:**
495
496```
497Internal Registry Credentials
498==============================
499Username: gordon-internal
500Password: 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
501
502Usage:
503  docker login localhost:5000 -u gordon-internal -p 8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c...
504```
505
506**Notes:**
507- Credentials are regenerated each time Gordon starts
508- Only available while Gordon is running
509- Used for manual `docker pull` from the local registry during debugging
510
511**Use cases:**
512- Debugging image pull failures
513- Manual recovery after deployment issues
514- Inspecting images in the local registry
515
516---
517
518## Token Scopes
519
520| Scope | Permission |
521|-------|------------|
522| `push` | Push images to registry |
523| `pull` | Pull images from registry |
524| `push,pull` | Both push and pull (default) |
525
526## Token Expiry Formats
527
528| Format | Duration |
529|--------|----------|
530| `0` | Never expires |
531| `24h` | 24 hours |
532| `720h` | 30 days |
533| `8760h` | 1 year |
534
535---
536
537## Workflow Examples
538
539### CI/CD Setup
540
541```bash
542# Generate token for CI
543gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
544
545# Save token as CI secret
546# GitHub: Settings → Secrets → New repository secret
547# GitLab: Settings → CI/CD → Variables
548```
549
550### Docker Login
551
552```bash
553# Using generated token
554docker login -u ci-bot -p <token> registry.mydomain.com
555
556# In CI/CD
557echo "$GORDON_TOKEN" | docker login -u ci-bot --password-stdin registry.mydomain.com
558```
559
560### Token Rotation
561
562```bash
563# Generate new token
564gordon auth token generate --subject ci-bot --expiry 0
565
566# Update CI secrets with new token
567
568# Revoke old token
569gordon auth token revoke <old-token-id>
570```
571
572### Password Setup
573
574```bash
575# Generate hash
576gordon auth password hash
577# Enter: mypassword
578
579# Store in pass
580pass insert gordon/registry/password_hash
581# Paste: $2a$10$...
582
583# Configure gordon.toml
584[registry_auth]
585enabled = true
586type = "password"
587username = "deploy"
588password_hash = "gordon/registry/password_hash"
589```
590
591---
592
593## gordon routes
594
595Manage routes on local or remote Gordon instances.
596
597### Subcommands
598
599| Subcommand | Description |
600|------------|-------------|
601| `list` | List all routes |
602| `add` | Add a new route |
603| `remove` | Remove a route |
604| `deploy` | Deploy a specific route |
605
606### gordon routes list
607
608List all configured routes.
609
610```bash
611gordon routes list
612gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
613```
614
615### gordon routes add
616
617Add a new route.
618
619```bash
620gordon routes add <domain> <image>
621gordon routes add myapp.example.com myapp:latest
622```
623
624### gordon routes remove
625
626Remove a route.
627
628```bash
629gordon routes remove <domain>
630gordon routes remove myapp.example.com
631```
632
633### gordon routes deploy
634
635Deploy or redeploy a specific route.
636
637```bash
638gordon routes deploy <domain>
639gordon routes deploy myapp.example.com
640```
641
642---
643
644## gordon secrets
645
646Manage secrets on local or remote Gordon instances.
647
648### Subcommands
649
650| Subcommand | Description |
651|------------|-------------|
652| `list` | List all secrets for a domain |
653| `set` | Set a secret value |
654| `remove` | Remove a secret |
655
656### Examples
657
658```bash
659# Local mode (reads/writes secrets directly)
660gordon secrets list myapp.local
661gordon secrets set myapp.local DATABASE_URL "postgres://..."
662gordon secrets remove myapp.local DATABASE_URL
663
664# Remote mode
665gordon secrets list myapp.local --remote https://gordon.mydomain.com --token $TOKEN
666gordon secrets set myapp.local DATABASE_URL "postgres://..." --remote ... --token ...
667gordon secrets remove myapp.local DATABASE_URL --remote ... --token ...
668```
669
670---
671
672## gordon remotes
673
674Manage saved remote Gordon instances for easier CLI usage.
675
676### Subcommands
677
678| Subcommand | Description |
679|------------|-------------|
680| `list` | List saved remotes |
681| `add` | Add a new remote |
682| `remove` | Remove a saved remote |
683| `use` | Set active remote |
684
685### Examples
686
687```bash
688# Add a remote
689gordon remotes add prod https://gordon.mydomain.com --token $TOKEN
690
691# List saved remotes
692gordon remotes list
693
694# Set active remote
695gordon remotes use prod
696
697# Now use without --remote flag
698gordon routes list
699```
700
701---
702
703## Exit Codes
704
705| Code | Meaning |
706|------|---------|
707| 0 | Success |
708| 1 | General error |
709| 2 | Configuration error |
710
711## Environment Variables
712
713Gordon reads configuration from environment variables:
714
715```bash
716GORDON_SERVER_PORT=8080 gordon serve
717GORDON_LOGGING_LEVEL=debug gordon serve
718```
719
720Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)
721
722## Related
723
724- [Core Concepts](../concepts.md)
725- [Configuration Reference](../config/index.md)

commands.md RawHistoryFolder

CLI Commands

Commands Overview

Quick Reference

Global Options

Remote Targeting

gordon serve

Synopsis

Options

Description

Configuration File Detection

First Run

Examples

Signals

Running with systemd

Startup Sequence

Shutdown Sequence

gordon reload

Synopsis

Description

Example

gordon deploy

Synopsis

Arguments

Options

Description

Examples

Use Cases

gordon logs

Synopsis

Arguments

Options

Examples

Log Locations

gordon version

Synopsis

Output

gordon auth

Subcommands

gordon auth token generate

gordon auth token list

gordon auth token revoke

gordon auth password hash

gordon auth internal

Token Scopes

Token Expiry Formats

Workflow Examples

CI/CD Setup

Docker Login

Token Rotation

Password Setup

gordon routes

Subcommands

gordon routes list

gordon routes add

gordon routes remove

gordon routes deploy

gordon secrets

Subcommands

Examples

gordon remotes

Subcommands

Examples

Exit Codes

Environment Variables

Related

commands.md Raw History Folder