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

Step 4: Login to registry (local machine)

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