Installation
Detailed installation guide for production environments.
System Requirements
- OS: Linux (Ubuntu 24.04 LTS, Debian 13 recommended) or macOS
- Architecture: x86_64 (amd64) or ARM64
- Memory: 512MB minimum, 1GB recommended
- Disk: 10GB minimum for registry storage
- Runtime: Docker or Podman
Download Gordon
Quick Install (Recommended)
curl -fsSL https://gordon.bnema.dev/install | bash
This script automatically detects your OS (Linux/macOS) and architecture (amd64/arm64), downloads the appropriate binary from GitHub releases, and installs it to /usr/local/bin.
Manual Installation
Linux (x86_64)
wget https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64.tar.gz
tar -xzf gordon_linux_amd64.tar.gz
chmod +x gordon
sudo mv gordon /usr/local/bin/
Linux (ARM64) - for Raspberry Pi 4, AWS Graviton, Oracle Ampere, 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/
macOS (Apple Silicon)
curl -LO https://github.com/bnema/gordon/releases/latest/download/gordon_darwin_arm64.tar.gz
tar -xzf gordon_darwin_arm64.tar.gz
chmod +x gordon
sudo mv gordon /usr/local/bin/
macOS (Intel)
curl -LO https://github.com/bnema/gordon/releases/latest/download/gordon_darwin_amd64.tar.gz
tar -xzf gordon_darwin_amd64.tar.gz
chmod +x gordon
sudo mv gordon /usr/local/bin/
Verify installation:
gordon version
From Source
# Requires Go 1.21+
git clone https://github.com/bnema/gordon.git
cd gordon
make build
sudo mv gordon /usr/local/bin/
Container Runtime Setup
Docker
# Install Docker
curl -fsSL https://get.docker.com | sh
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
# Verify
docker run hello-world
Podman (Rootless)
Podman rootless mode provides enhanced security by running containers without root privileges.
# Install Podman
sudo apt update
sudo apt install -y podman
# Enable user namespaces
echo 'user.max_user_namespaces=28633' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
# Setup subuid/subgid
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER
# Enable Podman socket
systemctl --user enable --now podman.socket
# Configure insecure localhost registry (required — Podman blocks HTTP registries by default)
mkdir -p ~/.config/containers/registries.conf.d
cat > ~/.config/containers/registries.conf.d/gordon.conf <<EOF
[[registry]]
location = "localhost:5000"
insecure = true
EOF
Firewall Configuration
Gordon needs ports accessible for the registry and proxy.
Using firewalld
# Install and enable firewalld
sudo apt install -y firewalld
sudo systemctl enable --now firewalld
# Allow HTTP/HTTPS
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
# For rootless containers, redirect privileged ports
sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8088
sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=8443
# Apply changes
sudo firewall-cmd --reload
# Verify
sudo firewall-cmd --list-all
Using ufw
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 5000/tcp # Registry port (if accessing directly)
sudo ufw enable
Configuration
Gordon creates a default configuration on first run:
# Run once to generate config, then stop
gordon serve
# Press Ctrl+C
# Edit configuration
nano ~/.config/gordon/gordon.toml
Minimum required configuration:
[server]
port = 8088
registry_port = 5000
gordon_domain = "gordon.yourdomain.com"
[routes]
"app.yourdomain.com" = "myapp:latest"
See Configuration Reference for all options.
Systemd Service
User Service (Recommended for Rootless)
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gordon.service <<EOF
[Unit]
Description=Gordon Container Platform
After=podman.socket
[Service]
Type=simple
Restart=always
RestartSec=5
# Required for Podman rootless — tells Gordon where to find the Podman socket
Environment=XDG_RUNTIME_DIR=/run/user/%U
Environment=DOCKER_HOST=unix:///run/user/%U/podman/podman.sock
ExecStart=/usr/local/bin/gordon serve
[Install]
WantedBy=default.target
EOF
> **Docker users:** Omit the two `Environment=` lines above — Docker's socket path is set automatically.
# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now gordon
# Enable linger (keep service running after logout)
sudo loginctl enable-linger $USER
# Check status
systemctl --user status gordon
System Service (Root Mode)
sudo cat > /etc/systemd/system/gordon.service <<EOF
[Unit]
Description=Gordon Container Platform
After=docker.service
Requires=docker.service
[Service]
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/gordon serve
User=root
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now gordon
DNS Configuration
Point your domains to your server:
| Type | Name | Content | Proxy |
|---|---|---|---|
| A | app |
SERVER_IP |
Yes (Cloudflare) |
| A | registry |
SERVER_IP |
Yes (Cloudflare) |
Note: Enable Cloudflare proxy (orange cloud) for automatic HTTPS. Gordon receives HTTP traffic from Cloudflare.
Cloudflare SSL Mode
Gordon serves HTTP by default. Cloudflare must connect to your origin over HTTP unless you explicitly enable TLS.
| Mode | How it works | Use when |
|---|---|---|
| Flexible | Cloudflare terminates TLS; connects to Gordon on HTTP | Gordon has no TLS cert (default setup) |
| Full (Strict) | Cloudflare connects to Gordon over HTTPS with a valid cert | Set server.tls_port (default 8443) and provide a Cloudflare Origin CA cert via server.tls_cert_file and server.tls_key_file |
Wrong mode causes: 521 (Cloudflare can't connect) or 525 (TLS handshake failed).
Rootless note: Unprivileged users can't bind port 80. Forward port 80→8088 (or your configured port) via firewall — see the firewall section above.
Verify Installation
# Check Gordon is running
systemctl --user status gordon
# View logs
journalctl --user -u gordon -f
# Test registry (from local machine)
docker login registry.yourdomain.com
docker pull alpine
docker tag alpine registry.yourdomain.com/test:latest
docker push registry.yourdomain.com/test:latest
Data Directories
Gordon stores data in the following locations:
| Path | Purpose |
|---|---|
~/.config/gordon/gordon.toml |
Configuration file |
~/.gordon/ |
Default data directory |
~/.gordon/registry/ |
Container images |
~/.gordon/env/ |
Environment files |
~/.gordon/logs/ |
Application logs |
~/.gordon/secrets/ |
Secrets (unsafe backend only) |