Getting Started

Deploy your first app with Gordon in under 5 minutes.

Prerequisites

A Linux VPS with Docker or Podman installed
A domain pointing to your VPS (DNS A record)
Cloudflare account (free tier) for HTTPS termination
pass (password manager) with GPG key initialized

1. Install Gordon

curl -fsSL https://gordon.bnema.dev/install | bash

This script automatically detects your OS and architecture, downloads the appropriate binary, and installs it to /usr/local/bin.

2. Initialize Configuration

# First run creates the default config
gordon serve
# Press Ctrl+C to stop

Config is created at ~/.config/gordon/gordon.toml.

3. Set Up Authentication

Gordon requires a token_secret for JWT authentication. We recommend using pass to store secrets securely.

Local development? If you just want to try Gordon locally, you can disable auth temporarily:
[auth]
enabled = false
Skip to Step 4. For production, continue below.

Initialize pass (if not already done):

# Generate a GPG key if you don't have one
gpg --gen-key

# Initialize pass with your GPG key ID
pass init <your-gpg-key-id>

Create the JWT token secret:

# Generate and store a random 32-character secret
openssl rand -base64 32 | pass insert -m gordon/auth/token_secret

Update your config (~/.config/gordon/gordon.toml):

[auth]
enabled = true
secrets_backend = "pass"
token_secret = "gordon/auth/token_secret"

4. Configure Your Registry Domain

Edit ~/.config/gordon/gordon.toml:

[server]
port = 8080                              # Proxy port (use with Cloudflare)
registry_port = 5000                     # Registry port
gordon_domain = "gordon.mydomain.com"    # Your Gordon domain

[routes]
"app.mydomain.com" = "myapp:latest"      # Domain → Image mapping

5. Set Up DNS

In Cloudflare (or your DNS provider):

Type	Name	Content
A	`app`	`YOUR_SERVER_IP`
A	`registry`	`YOUR_SERVER_IP`

Enable Cloudflare proxy (orange cloud) for HTTPS.

6. Start Gordon as a Service

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

7. Generate a Deploy Token

Create a token for pushing images to your registry (skip if auth is disabled):

gordon auth token generate --subject deploy --scopes push,pull --expiry 0

Save this token securely - you'll need it for Docker login.

8. Deploy Your First App

On your local machine:

# Log in to your Gordon registry (skip if auth is disabled)
docker login -u deploy -p <your-token> registry.mydomain.com

# Build your app
docker build -t myapp .

# Tag for your registry
docker tag myapp registry.mydomain.com/myapp:latest

# Push to Gordon
docker push registry.mydomain.com/myapp:latest

Your app is now live at https://app.mydomain.com!

9. Update Your App

Push a new image to deploy with zero downtime:

# Make changes, rebuild
docker build -t myapp .
docker tag myapp registry.mydomain.com/myapp:latest
docker push registry.mydomain.com/myapp:latest

Gordon automatically:

Starts the new container
Waits for it to be ready
Routes traffic to the new container
Stops the old container

Next Steps

Installation Guide - Production setup with firewall and rootless containers
Configuration Reference - All configuration options
Authentication - Secure your registry
Environment Variables - Configure per-app settings

source

1# Getting Started
2
3Deploy your first app with Gordon in under 5 minutes.
4
5## Prerequisites
6
7- A Linux VPS with Docker or Podman installed
8- A domain pointing to your VPS (DNS A record)
9- Cloudflare account (free tier) for HTTPS termination
10- [pass](https://www.passwordstore.org/) (password manager) with GPG key initialized
11
12## 1. Install Gordon
13
14```bash
15curl -fsSL https://gordon.bnema.dev/install | bash
16```
17
18This script automatically detects your OS and architecture, downloads the appropriate binary, and installs it to `/usr/local/bin`.
19
20## 2. Initialize Configuration
21
22```bash
23# First run creates the default config
24gordon serve
25# Press Ctrl+C to stop
26```
27
28Config is created at `~/.config/gordon/gordon.toml`.
29
30## 3. Set Up Authentication
31
32Gordon requires a `token_secret` for JWT authentication. We recommend using `pass` to store secrets securely.
33
34> **Local development?** If you just want to try Gordon locally, you can disable auth temporarily:
35> ```toml
36> [auth]
37> enabled = false
38> ```
39> Skip to [Step 4](#4-configure-your-registry-domain). For production, continue below.
40
41**Initialize pass (if not already done):**
42```bash
43# Generate a GPG key if you don't have one
44gpg --gen-key
45
46# Initialize pass with your GPG key ID
47pass init <your-gpg-key-id>
48```
49
50**Create the JWT token secret:**
51```bash
52# Generate and store a random 32-character secret
53openssl rand -base64 32 | pass insert -m gordon/auth/token_secret
54```
55
56**Update your config** (`~/.config/gordon/gordon.toml`):
57```toml
58[auth]
59enabled = true
60secrets_backend = "pass"
61token_secret = "gordon/auth/token_secret"
62```
63
64## 4. Configure Your Registry Domain
65
66Edit `~/.config/gordon/gordon.toml`:
67
68```toml
69[server]
70port = 8080                              # Proxy port (use with Cloudflare)
71registry_port = 5000                     # Registry port
72gordon_domain = "gordon.mydomain.com"    # Your Gordon domain
73
74[routes]
75"app.mydomain.com" = "myapp:latest"      # Domain → Image mapping
76```
77
78## 5. Set Up DNS
79
80In Cloudflare (or your DNS provider):
81
82| Type | Name | Content |
83|------|------|---------|
84| A | `app` | `YOUR_SERVER_IP` |
85| A | `registry` | `YOUR_SERVER_IP` |
86
87Enable Cloudflare proxy (orange cloud) for HTTPS.
88
89## 6. Start Gordon as a Service
90
91```bash
92# Create systemd user service
93mkdir -p ~/.config/systemd/user
94cat > ~/.config/systemd/user/gordon.service <<EOF
95[Unit]
96Description=Gordon Container Platform
97
98[Service]
99Type=simple
100Restart=always
101ExecStart=/usr/local/bin/gordon serve
102
103[Install]
104WantedBy=default.target
105EOF
106
107# Enable and start
108systemctl --user daemon-reload
109systemctl --user enable --now gordon
110sudo loginctl enable-linger $USER
111```
112
113## 7. Generate a Deploy Token
114
115Create a token for pushing images to your registry (skip if auth is disabled):
116
117```bash
118gordon auth token generate --subject deploy --scopes push,pull --expiry 0
119```
120
121Save this token securely - you'll need it for Docker login.
122
123## 8. Deploy Your First App
124
125On your local machine:
126
127```bash
128# Log in to your Gordon registry (skip if auth is disabled)
129docker login -u deploy -p <your-token> registry.mydomain.com
130
131# Build your app
132docker build -t myapp .
133
134# Tag for your registry
135docker tag myapp registry.mydomain.com/myapp:latest
136
137# Push to Gordon
138docker push registry.mydomain.com/myapp:latest
139```
140
141Your app is now live at `https://app.mydomain.com`!
142
143## 9. Update Your App
144
145Push a new image to deploy with zero downtime:
146
147```bash
148# Make changes, rebuild
149docker build -t myapp .
150docker tag myapp registry.mydomain.com/myapp:latest
151docker push registry.mydomain.com/myapp:latest
152```
153
154Gordon automatically:
1551. Starts the new container
1562. Waits for it to be ready
1573. Routes traffic to the new container
1584. Stops the old container
159
160## Next Steps
161
162- [Installation Guide](./installation.md) - Production setup with firewall and rootless containers
163- [Configuration Reference](./config/index.md) - All configuration options
164- [Authentication](./config/auth.md) - Secure your registry
165- [Environment Variables](./config/env.md) - Configure per-app settings
166
167## Related
168
169- [First Deploy Tutorial](/wiki/tutorials/first-deploy.md)
170- [Podman Rootless Setup](/wiki/guides/podman-rootless.md)

getting-started.md RawHistoryFolder