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

curl -fsSL https://gordon.bnema.dev/install | bash

This script automatically detects your OS and architecture, downloads the appropriate binary, and installs it to /usr/local/bin.

2. Start Gordon

# First run creates the default config
gordon serve
# 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
gordon_domain = "gordon.mydomain.com"      # Your Gordon 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 serve

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

getting-started.md RawHistoryFolder