detached f9c97fb

docs(wiki): add AI agents deployment guide

Structured workflow for AI coding assistants to deploy with Gordon.
commit
f9c97fbde2e0dfb11d1dcfb9812d4164ba9b34d3
author
brice · · 2026-01-15 06:25 UTC
parent
9e1b73a
signature
unsigned
2 files · +107 -0
Unified
UnifiedSplit
A wiki/agents/deploy.md +101 -0
@@ -0,0 +1,101 @@
1+# AI Agent Deployment Guide
2+
3+This guide provides a structured workflow for AI coding assistants to help users deploy applications with Gordon.
4+
5+## Deployment Workflow
6+
7+### Key Paths (VPS)
8+
9+```
10+~/.config/gordon/gordon.toml # Main config (routes, registry)
11+~/.gordon/env/ # Env files per domain
12+~/.gordon/logs/containers/ # Container logs
13+```
14+
15+### Step 1: Add route in gordon.toml
16+
17+```toml
18+[routes]
19+"app.example.com" = "my-app:latest"
20+```
21+
22+### Step 2: Create env file
23+
24+Naming convention: domain with dots replaced by underscores.
25+
26+Example: `app.example.com` → `~/.gordon/env/app_example_com.env`
27+
28+```bash
29+cat > ~/.gordon/env/app_example_com.env << 'EOF'
30+NODE_ENV=production
31+PUBLIC_API_URL=https://api.example.com
32+EOF
33+```
34+
35+### Step 3: Generate registry token (on VPS)
36+
37+```bash
38+gordon auth token generate --subject username --expiry 720h
39+```
40+
41+### Step 4: Login to registry (local machine)
42+
43+```bash
44+echo "TOKEN" | docker login -u username --password-stdin reg.example.com:5000
45+```
46+
47+### Step 5: Build and push
48+
49+Tag images to match git tags + latest for bleeding edge:
50+
51+```bash
52+# Get current git tag (falls back to "latest" if no tag)
53+TAG=$(git describe --tags --exact-match 2>/dev/null || echo "latest")
54+
55+# Build with version tag and latest
56+docker buildx build --platform linux/amd64 \
57+ -t reg.example.com:5000/my-app:$TAG \
58+ -t reg.example.com:5000/my-app:latest \
59+ --push .
60+```
61+
62+Gordon auto-deploys when it receives the pushed image.
63+
64+### Step 6: Verify
65+
66+```bash
67+curl -I https://app.example.com
68+ssh user@vps "cat ~/.gordon/logs/containers/app_example_com.log"
69+```
70+
71+## Framework Notes
72+
73+### SvelteKit / Next.js
74+
75+Static env vars (`$env/static/public`, `NEXT_PUBLIC_*`) must be available at build time:
76+
77+```dockerfile
78+ARG PUBLIC_API_URL
79+ENV PUBLIC_API_URL=$PUBLIC_API_URL
80+```
81+
82+Build with:
83+```bash
84+docker buildx build --build-arg PUBLIC_API_URL=https://api.example.com --push .
85+```
86+
87+## Secrets with pass
88+
89+Use pass integration for sensitive values:
90+
91+```bash
92+DATABASE_PASSWORD=${pass:gordon/app/db_password}
93+```
94+
95+## Troubleshooting
96+
97+| Issue | Solution |
98+|-------|----------|
99+| HTTPS error on push | Add registry to `insecure-registries` in daemon.json |
100+| Container not starting | Check env file name matches domain pattern |
101+| Env vars not working | SvelteKit static env = build args, not runtime env |
@@ -0,0 +1,101 @@
1+# AI Agent Deployment Guide
2+
3+This guide provides a structured workflow for AI coding assistants to help users deploy applications with Gordon.
4+
5+## Deployment Workflow
6+
7+### Key Paths (VPS)
8+
9+```
10+~/.config/gordon/gordon.toml # Main config (routes, registry)
11+~/.gordon/env/ # Env files per domain
12+~/.gordon/logs/containers/ # Container logs
13+```
14+
15+### Step 1: Add route in gordon.toml
16+
17+```toml
18+[routes]
19+"app.example.com" = "my-app:latest"
20+```
21+
22+### Step 2: Create env file
23+
24+Naming convention: domain with dots replaced by underscores.
25+
26+Example: `app.example.com` → `~/.gordon/env/app_example_com.env`
27+
28+```bash
29+cat > ~/.gordon/env/app_example_com.env << 'EOF'
30+NODE_ENV=production
31+PUBLIC_API_URL=https://api.example.com
32+EOF
33+```
34+
35+### Step 3: Generate registry token (on VPS)
36+
37+```bash
38+gordon auth token generate --subject username --expiry 720h
39+```
40+
41+### Step 4: Login to registry (local machine)
42+
43+```bash
44+echo "TOKEN" | docker login -u username --password-stdin reg.example.com:5000
45+```
46+
47+### Step 5: Build and push
48+
49+Tag images to match git tags + latest for bleeding edge:
50+
51+```bash
52+# Get current git tag (falls back to "latest" if no tag)
53+TAG=$(git describe --tags --exact-match 2>/dev/null || echo "latest")
54+
55+# Build with version tag and latest
56+docker buildx build --platform linux/amd64 \
57+ -t reg.example.com:5000/my-app:$TAG \
58+ -t reg.example.com:5000/my-app:latest \
59+ --push .
60+```
61+
62+Gordon auto-deploys when it receives the pushed image.
63+
64+### Step 6: Verify
65+
66+```bash
67+curl -I https://app.example.com
68+ssh user@vps "cat ~/.gordon/logs/containers/app_example_com.log"
69+```
70+
71+## Framework Notes
72+
73+### SvelteKit / Next.js
74+
75+Static env vars (`$env/static/public`, `NEXT_PUBLIC_*`) must be available at build time:
76+
77+```dockerfile
78+ARG PUBLIC_API_URL
79+ENV PUBLIC_API_URL=$PUBLIC_API_URL
80+```
81+
82+Build with:
83+```bash
84+docker buildx build --build-arg PUBLIC_API_URL=https://api.example.com --push .
85+```
86+
87+## Secrets with pass
88+
89+Use pass integration for sensitive values:
90+
91+```bash
92+DATABASE_PASSWORD=${pass:gordon/app/db_password}
93+```
94+
95+## Troubleshooting
96+
97+| Issue | Solution |
98+|-------|----------|
99+| HTTPS error on push | Add registry to `insecure-registries` in daemon.json |
100+| Container not starting | Check env file name matches domain pattern |
101+| Env vars not working | SvelteKit static env = build args, not runtime env |
M wiki/index.md +6 -0
@@ -20,6 +20,12 @@ In-depth guides for specific setups:
2020 - [Using Pass for Secrets](./guides/secrets-pass.md) - Unix password manager integration
2121 - [Using SOPS for Secrets](./guides/secrets-sops.md) - Encrypted secrets with SOPS
2222
23+## Agents
24+
25+Guides for AI coding assistants:
26+
27+- [Deployment Workflow](./agents/deploy.md) - Structured deployment guide for AI agents
28+
2329 ## Examples
2430
2531 Configuration examples explained:
@@ -20,6 +20,12 @@ In-depth guides for specific setups:
20 - [Using Pass for Secrets](./guides/secrets-pass.md) - Unix password manager integration20 - [Using Pass for Secrets](./guides/secrets-pass.md) - Unix password manager integration
21 - [Using SOPS for Secrets](./guides/secrets-sops.md) - Encrypted secrets with SOPS21 - [Using SOPS for Secrets](./guides/secrets-sops.md) - Encrypted secrets with SOPS
22 22
23+## Agents
24+
25+Guides for AI coding assistants:
26+
27+- [Deployment Workflow](./agents/deploy.md) - Structured deployment guide for AI agents
28+
23 ## Examples29 ## Examples
24 30
25 Configuration examples explained:31 Configuration examples explained:

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 7

Tags 106

↑↓ moveenter openesc close