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

1. Install Gordon

# Download the latest release (choose your architecture)
# For x86_64:
wget https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64.tar.gz
tar -xzf gordon_linux_amd64.tar.gz

# For ARM64 (Raspberry Pi 4, AWS Graviton, etc.):
# wget https://github.com/bnema/gordon/releases/latest/download/gordon_linux_arm64.tar.gz
# tar -xzf gordon_linux_arm64.tar.gz

chmod +x gordon
sudo mv gordon /usr/local/bin/

2. Start Gordon

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

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

3. Configure Your Registry Domain

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

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

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

4. 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.

5. 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 start

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now gordon
sudo loginctl enable-linger $USER

6. Deploy Your First App

On your local machine:

# 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!

7. 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
Registry 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
11## 1. Install Gordon
12
13```bash
14# Download the latest release (choose your architecture)
15# For x86_64:
16wget https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64.tar.gz
17tar -xzf gordon_linux_amd64.tar.gz
18
19# For ARM64 (Raspberry Pi 4, AWS Graviton, etc.):
20# wget https://github.com/bnema/gordon/releases/latest/download/gordon_linux_arm64.tar.gz
21# tar -xzf gordon_linux_arm64.tar.gz
22
23chmod +x gordon
24sudo mv gordon /usr/local/bin/
25```
26
27## 2. Start Gordon
28
29```bash
30# First run creates the default config
31gordon start
32# Press Ctrl+C to stop
33```
34
35Config is created at `~/.config/gordon/gordon.toml`.
36
37## 3. Configure Your Registry Domain
38
39Edit `~/.config/gordon/gordon.toml`:
40
41```toml
42[server]
43port = 8080                              # Proxy port (use with Cloudflare)
44registry_port = 5000                     # Registry port
45registry_domain = "registry.mydomain.com"  # Your registry domain
46
47[routes]
48"app.mydomain.com" = "myapp:latest"      # Domain → Image mapping
49```
50
51## 4. Set Up DNS
52
53In Cloudflare (or your DNS provider):
54
55| Type | Name | Content |
56|------|------|---------|
57| A | `app` | `YOUR_SERVER_IP` |
58| A | `registry` | `YOUR_SERVER_IP` |
59
60Enable Cloudflare proxy (orange cloud) for HTTPS.
61
62## 5. Start Gordon as a Service
63
64```bash
65# Create systemd user service
66mkdir -p ~/.config/systemd/user
67cat > ~/.config/systemd/user/gordon.service <<EOF
68[Unit]
69Description=Gordon Container Platform
70
71[Service]
72Type=simple
73Restart=always
74ExecStart=/usr/local/bin/gordon start
75
76[Install]
77WantedBy=default.target
78EOF
79
80# Enable and start
81systemctl --user daemon-reload
82systemctl --user enable --now gordon
83sudo loginctl enable-linger $USER
84```
85
86## 6. Deploy Your First App
87
88On your local machine:
89
90```bash
91# Build your app
92docker build -t myapp .
93
94# Tag for your registry
95docker tag myapp registry.mydomain.com/myapp:latest
96
97# Push to Gordon
98docker push registry.mydomain.com/myapp:latest
99```
100
101Your app is now live at `https://app.mydomain.com`!
102
103## 7. Update Your App
104
105Push a new image to deploy with zero downtime:
106
107```bash
108# Make changes, rebuild
109docker build -t myapp .
110docker tag myapp registry.mydomain.com/myapp:latest
111docker push registry.mydomain.com/myapp:latest
112```
113
114Gordon automatically:
1151. Starts the new container
1162. Waits for it to be ready
1173. Routes traffic to the new container
1184. Stops the old container
119
120## Next Steps
121
122- [Installation Guide](./installation.md) - Production setup with firewall and rootless containers
123- [Configuration Reference](./config/index.md) - All configuration options
124- [Registry Authentication](./config/registry-auth.md) - Secure your registry
125- [Environment Variables](./config/env.md) - Configure per-app settings
126
127## Related
128
129- [First Deploy Tutorial](/wiki/tutorials/first-deploy.md)
130- [Podman Rootless Setup](/wiki/guides/podman-rootless.md)

getting-started.md RawHistoryFolder