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- HTTPS setup: Cloudflare proxy, Tailscale, or Gordon's internal CA (`server.tls_port = 8443`)
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. You can store it in `pass` or provide it via the `GORDON_AUTH_TOKEN_SECRET` environment variable. 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-gordon-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**Or set it via environment variable:**
57
58```bash
59export GORDON_AUTH_TOKEN_SECRET="your-32-character-secret-here"
60```
61
62**Update your config** (`~/.config/gordon/gordon.toml`):
63```toml
64[auth]
65enabled = true
66secrets_backend = "pass"
67token_secret = "gordon/auth/token_secret"
68```
69
70## 4. Configure Your Gordon Domain
71
72Edit `~/.config/gordon/gordon.toml`:
73
74```toml
75[server]
76port = 8080                              # Proxy port (use with Cloudflare/rootless)
77registry_port = 5000                     # Registry port
78gordon_domain = "gordon.mydomain.com"    # Registry + Admin API domain
79
80[routes]
81"app.mydomain.com" = "myapp:latest"      # Domain → Image mapping
82```
83
84## 5. Set Up DNS (Including Wildcard)
85
86`gordon_domain` is the single domain used by both the registry and admin API.
87
88In Cloudflare (or your DNS provider), create:
89
90| Type | Name | Content | Proxy |
91|------|------|---------|-------|
92| A | `gordon` | `YOUR_SERVER_IP` | Yes |
93| A/CNAME | `*` | `YOUR_SERVER_IP` or `gordon.mydomain.com` | Yes |
94
95Why wildcard (`*`)?
96- It automatically covers app routes like `app.mydomain.com`, `api.mydomain.com`, `demo.mydomain.com`, etc.
97- You can add new domains in `[routes]` without creating DNS records one by one.
98
99If your DNS provider supports wildcard CNAME flattening (Cloudflare does), `* -> gordon.mydomain.com` is usually the cleanest option.
100
101## 6. Start Gordon as a Service
102
103```bash
104# Create systemd user service
105mkdir -p ~/.config/systemd/user
106cat > ~/.config/systemd/user/gordon.service <<EOF
107[Unit]
108Description=Gordon Container Platform
109
110[Service]
111Type=simple
112Restart=always
113ExecStart=/usr/local/bin/gordon serve
114
115[Install]
116WantedBy=default.target
117EOF
118
119# Enable and start
120systemctl --user daemon-reload
121systemctl --user enable --now gordon
122sudo loginctl enable-linger $USER
123```
124
125## 7. Generate a Deploy Token
126
127Create a token for remote CLI deploys (skip if auth is disabled):
128
129```bash
130gordon auth token generate --subject deploy --scopes push,pull --expiry 0
131```
132
133`--expiry 0` creates a non-expiring token. Prefer a finite expiry and a rotation policy unless you explicitly need a long-lived deploy token.
134
135Save this token securely -- you will use it to authenticate with your Gordon server from CI/CD pipelines and remote CLI sessions.
136
137## 8. Deploy Your First App
138
139On your local machine:
140
141```bash
142# Save and select your Gordon remote (one-time)
143gordon remotes add prod https://gordon.mydomain.com --token <your-token>
144gordon remotes use prod
145
146# Recommended first-time setup
147gordon bootstrap app.example.com myapp:latest --attachment postgres:18 --env APP_ENV=production
148
149# Then build, push, and deploy
150gordon push myapp:latest --domain app.example.com --build --no-confirm
151```
152
153What this command does:
154
155- `gordon bootstrap` creates or updates the route, applies requested attachments,
156  and stores environment variables.
157- This is the recommended path for first deploys because it does not require the
158  route to exist ahead of time.
159- Run `gordon push` separately after bootstrap to build, upload, and deploy the image.
160
161If the route already exists and you only need to push a new image version, use:
162
163```bash
164gordon push myapp --build --no-confirm
165```
166
167`gordon push` still requires the route to already exist so it can resolve the
168deploy target.
169
170Your app is now live at `https://app.mydomain.com`!
171
172## 9. Update Your App
173
174Push a new image to deploy with zero downtime:
175
176```bash
177# Make changes, then build + push + deploy
178gordon push myapp --build --no-confirm
179```
180
181Gordon automatically:
1821. Starts the new container
1832. Waits for it to be ready
1843. Routes traffic to the new container
1854. Stops the old container
186
187## Next Steps
188
189- [Installation Guide](./installation.md) - Production setup with firewall and rootless containers
190- [Configuration Reference](./config/index.md) - All configuration options
191- [Authentication](./config/auth.md) - Secure your registry
192- [Environment Variables](./config/env.md) - Configure per-app settings
193
194## Related
195
196- [First Deploy Tutorial](/wiki/tutorials/first-deploy.md)
197- [Podman Rootless Setup](/wiki/guides/podman-rootless.md)