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