1# Gordon
2
3[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
4
5Self-hosted container deployment. Push an image, Gordon routes it to the web.
6
7- Website: https://bnema.dev/gordon
8- Documentation: [Docs](https://gordon.bnema.dev/docs) | [Wiki](https://gordon.bnema.dev/wiki)
9- Discuss: [GitHub Discussions](https://github.com/bnema/gordon/discussions)
10
11---
12
13## What is Gordon?
14
15Gordon is a private container registry and HTTP reverse proxy for your VPS. Push a container image that exposes a web port — Gordon deploys it with zero downtime.
16
17## Quick Start
18
19```bash
20# Install
21curl -fsSL https://gordon.bnema.dev/install.sh | sh
22
23# Start the server
24gordon serve
25```
26
27Config is created at `~/.config/gordon/gordon.toml`. See the [Getting Started guide](https://gordon.bnema.dev/docs/getting-started) for full setup.
28
29## Deploy with the CLI
30
31Build locally, push directly to your Gordon server:
32
33```bash
34# Push using an explicit domain override
35gordon push myapp:latest --domain app.example.com
36
37# Or add a route manually, then deploy
38gordon routes add app.example.com myapp:latest
39gordon routes deploy app.example.com
40
41# Check status
42gordon status
43```
44
45Roll back, restart, or manage secrets — all from the command line:
46
47```bash
48gordon pin app.example.com         # Pin to a specific image tag
49gordon restart app.example.com     # Restart the container
50gordon secrets set app.example.com DB_HOST=db.internal API_KEY=secret123
51```
52
53## Deploy from CI/CD
54
55Push to Gordon's registry from any CI pipeline. Gordon deploys automatically on image push.
56
57### GitHub Actions
58
59```yaml
60- uses: bnema/gordon/.github/actions/deploy@main
61  with:
62    registry: registry.mydomain.com
63    username: ${{ secrets.GORDON_USERNAME }}
64    password: ${{ secrets.GORDON_TOKEN }}
65```
66
67### Docker CLI
68
69```bash
70docker login registry.mydomain.com
71docker build -t registry.mydomain.com/myapp:v1.0.0 .
72docker push registry.mydomain.com/myapp:v1.0.0
73# -> Deployed automatically
74```
75
76See the [Deploy Action README](.github/actions/deploy/README.md) for multi-platform builds, monorepo support, and all available options.
77
78## CLI Commands
79
80### Server
81
82| Command | Description |
83|---------|-------------|
84| `gordon serve` | Start the Gordon server |
85| `gordon status` | Show server and route health |
86| `gordon config show` | Display server configuration |
87
88### Deployment
89
90| Command | Description |
91|---------|-------------|
92| `gordon push [image]` | Tag, push, and optionally deploy an image |
93| `gordon routes list` | List all routes |
94| `gordon routes add <domain> <image>` | Create or update a route |
95| `gordon routes remove <domain>` | Remove a route |
96| `gordon routes deploy <domain>` | Redeploy a route |
97| `gordon pin <domain>` | Pin a route to a specific image tag |
98| `gordon restart <domain>` | Restart a route container |
99
100### Images & Registry
101
102| Command | Description |
103|---------|-------------|
104| `gordon images list` | List runtime and registry images |
105| `gordon images prune` | Clean up dangling images and old tags |
106| `gordon images tags <repo>` | List registry tags for a repository |
107
108### Secrets & Config
109
110| Command | Description |
111|---------|-------------|
112| `gordon secrets list <domain>` | List secrets for a route |
113| `gordon secrets set <domain> KEY=VAL` | Set secrets |
114| `gordon secrets remove <domain> <key>` | Remove a secret |
115
116### Remotes & Auth
117
118| Command | Description |
119|---------|-------------|
120| `gordon remotes list` | List remote Gordon endpoints |
121| `gordon remotes add <name> <url>` | Add a remote |
122| `gordon remotes use <name>` | Set the active remote |
123| `gordon auth login` | Authenticate to a remote |
124| `gordon auth token generate` | Generate a JWT token |
125
126## Features
127
128- Private Docker registry on your VPS
129- Domain-to-container routing through a smart TCP edge reverse proxy
130- Automatic deployment on image push
131- Auto-routing from image labels
132- Remote CLI management
133- Zero downtime updates
134- Persistent volumes from Dockerfile VOLUME directives
135- Environment variable management with secrets support
136- Network isolation per application
137- Single binary, ~15MB RAM
138
139> [!NOTE]
140> Gordon exposes public traffic through entrypoints such as `[entrypoints.edge]` with `protocol = "smart_tcp"`. It can terminate TLS via static certificates, public ACME certificates, or its internal CA. Cloudflare and upstream reverse proxies are optional deployment choices, not requirements.
141
142## Documentation
143
144Full documentation at **[gordon.bnema.dev](https://bnema.dev/gordon)**
145
146- [Docs](https://bnema.dev/gordon/docs) — Installation, configuration, CLI reference
147- [Wiki](https://bnema.dev/gordon/wiki) — Tutorials, guides, and examples
148
149## Community
150
151- [Report bugs](https://github.com/bnema/gordon/issues)
152- [Discussions](https://github.com/bnema/gordon/discussions)
153- [Submit PRs](https://github.com/bnema/gordon/pulls)
154
155## License
156
157GPL-3.0 — Use freely, contribute back.