AI Agent Deployment Guide

This guide provides a structured workflow for AI coding assistants to help users deploy applications with Gordon.

Deployment Workflow

Key Paths (VPS)

~/.config/gordon/gordon.toml    # Main config (routes, registry)
~/.gordon/env/                  # Env files per domain
~/.gordon/logs/containers/      # Container logs

Step 1: Add route in gordon.toml

[routes]
"app.example.com" = "my-app:latest"

Step 2: Create env file

Naming convention: domain with dots replaced by underscores.

Example: app.example.com → ~/.gordon/env/app_example_com.env

cat > ~/.gordon/env/app_example_com.env << 'EOF'
NODE_ENV=production
PUBLIC_API_URL=https://api.example.com
EOF

Step 3: Generate registry token (on VPS)

gordon auth token generate --subject username --expiry 720h

echo "TOKEN" | docker login -u username --password-stdin reg.example.com:5000

Step 5: Build and push

Tag images to match git tags + latest for bleeding edge:

# Get current git tag (falls back to "latest" if no tag)
TAG=$(git describe --tags --exact-match 2>/dev/null || echo "latest")

# Build with version tag and latest
docker buildx build --platform linux/amd64 \
  -t reg.example.com:5000/my-app:$TAG \
  -t reg.example.com:5000/my-app:latest \
  --push .

Gordon auto-deploys when it receives the pushed image.

Step 6: Verify

curl -I https://app.example.com
ssh user@vps "cat ~/.gordon/logs/containers/app_example_com.log"

Framework Notes

SvelteKit / Next.js

Static env vars ($env/static/public, NEXT_PUBLIC_*) must be available at build time:

ARG PUBLIC_API_URL
ENV PUBLIC_API_URL=$PUBLIC_API_URL

Build with:

docker buildx build --build-arg PUBLIC_API_URL=https://api.example.com --push .

Secrets with pass

Use pass integration for sensitive values:

DATABASE_PASSWORD=${pass:gordon/app/db_password}

Troubleshooting

Issue	Solution
HTTPS error on push	Add registry to `insecure-registries` in daemon.json
Container not starting	Check env file name matches domain pattern
Env vars not working	SvelteKit static env = build args, not runtime env

source

1# AI Agent Deployment Guide
2
3This 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
24Naming convention: domain with dots replaced by underscores.
25
26Example: `app.example.com` → `~/.gordon/env/app_example_com.env`
27
28```bash
29cat > ~/.gordon/env/app_example_com.env << 'EOF'
30NODE_ENV=production
31PUBLIC_API_URL=https://api.example.com
32EOF
33```
34
35### Step 3: Generate registry token (on VPS)
36
37```bash
38gordon auth token generate --subject username --expiry 720h
39```
40
41### Step 4: Login to registry (local machine)
42
43```bash
44echo "TOKEN" | docker login -u username --password-stdin reg.example.com:5000
45```
46
47### Step 5: Build and push
48
49Tag images to match git tags + latest for bleeding edge:
50
51```bash
52# Get current git tag (falls back to "latest" if no tag)
53TAG=$(git describe --tags --exact-match 2>/dev/null || echo "latest")
54
55# Build with version tag and latest
56docker 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
62Gordon auto-deploys when it receives the pushed image.
63
64### Step 6: Verify
65
66```bash
67curl -I https://app.example.com
68ssh user@vps "cat ~/.gordon/logs/containers/app_example_com.log"
69```
70
71## Framework Notes
72
73### SvelteKit / Next.js
74
75Static env vars (`$env/static/public`, `NEXT_PUBLIC_*`) must be available at build time:
76
77```dockerfile
78ARG PUBLIC_API_URL
79ENV PUBLIC_API_URL=$PUBLIC_API_URL
80```
81
82Build with:
83```bash
84docker buildx build --build-arg PUBLIC_API_URL=https://api.example.com --push .
85```
86
87## Secrets with pass
88
89Use pass integration for sensitive values:
90
91```bash
92DATABASE_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 |

deploy.md RawHistoryFolder