docs: rewrite README to highlight CLI commands and CI/CD registry deployment

commit: d1b6a9153198a1e74118d9f7341440f2e58db275
author: brice · 7mo ago · 2026-03-14 10:02 UTC
parent: 924ea04
signature: unsigned

1 file · +113 -24

M README.md +113 -24


@@ -3,7 +3,7 @@
3	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	4		[![Go Report Card](https://goreportcard.com/badge/github.com/bnema/gordon)](https://goreportcard.com/report/github.com/bnema/gordon)
5	5
6		-	Self-hosted web app deployments. Push to your registry, Gordon does the rest.
	6	+	Self-hosted container deployment. Push an image, Gordon routes it to the web.
7	7
8	8		- Website: https://gordon.bnema.dev
9	9		- Documentation: [Docs](https://gordon.bnema.dev/docs) \| [Wiki](https://gordon.bnema.dev/wiki)

@@ -13,17 +13,119 @@ Self-hosted web app deployments. Push to your registry, Gordon does the rest.
13	13
14	14		## What is Gordon?
15	15
16		-	Gordon is a private container registry + HTTP reverse proxy for your VPS. Push a container image exposing a web port, it deploys automatically with zero downtime.
	16	+	Gordon 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
	22	+	curl -fsSL https://gordon.bnema.dev/install.sh \| sh
	23	+
	24	+	# Start the server
	25	+	gordon serve
	26	+	```
	27	+
	28	+	Config 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	+
	32	+	Build locally, push directly to your Gordon server:
	33	+
	34	+	```bash
	35	+	# Push an image and deploy it to a domain
	36	+	gordon push app.example.com --image myapp:latest
	37	+
	38	+	# Or add a route manually, then deploy
	39	+	gordon routes add app.example.com myapp:latest
	40	+	gordon routes deploy app.example.com
	41	+
	42	+	# Check status
	43	+	gordon status
	44	+	```
	45	+
	46	+	Roll back, restart, or manage secrets — all from the command line:
17	47
18	48		```bash
19		-	docker build -t myapp .
20		-	docker push registry.your-server.com/myapp:latest
21		-	# → Live at https://app.your-server.com
	49	+	gordon rollback app.example.com # Revert to a previous image tag
	50	+	gordon restart app.example.com # Restart the container
	51	+	gordon secrets set app.example.com DB_HOST=db.internal API_KEY=secret123
	52	+	```
	53	+
	54	+	## Deploy from CI/CD
	55	+
	56	+	Push 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 }}
22	66		```
23	67
24		-	Build on your machine, push to deploy. Works from your laptop or CI.
	68	+	### Docker CLI
	69	+
	70	+	```bash
	71	+	docker login registry.mydomain.com
	72	+	docker build -t registry.mydomain.com/myapp:v1.0.0 .
	73	+	docker push registry.mydomain.com/myapp:v1.0.0
	74	+	# -> Deployed automatically
	75	+	```
	76	+
	77	+	See 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 <domain>` \| Tag and push an image to deploy \|
	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 rollback <domain>` \| Roll back to a previous image \|
	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
25	128
26		-	Features:
27	129		- Private Docker registry on your VPS
28	130		- Domain-to-container routing via HTTP reverse proxy
29	131		- Automatic deployment on image push

@@ -37,23 +139,10 @@ Build on your machine, push to deploy. Works from your laptop or CI.
37	139
38	140		## Documentation
39	141
40		-	Full documentation is available at [gordon.bnema.dev](https://gordon.bnema.dev)
41		-
42		-	- [Documentation](https://gordon.bnema.dev/docs) - Installation, configuration, CLI reference
43		-	- [Wiki](https://gordon.bnema.dev/wiki) - Tutorials, guides, and examples
44		-
45		-	## Quick Start
46		-
47		-	```bash
48		-	# Install Gordon
49		-	curl -fsSL https://gordon.bnema.dev/install.sh \| sh
50		-	# Or: curl -fsSL https://raw.githubusercontent.com/bnema/gordon/main/install.sh \| sh
51		-
52		-	# Start Gordon (generates config on first run)
53		-	gordon serve
54		-	```
	142	+	Full documentation at [gordon.bnema.dev](https://gordon.bnema.dev)
55	143
56		-	Config is created at `~/.config/gordon/gordon.toml`. See the [Getting Started guide](https://gordon.bnema.dev/docs/getting-started) for complete setup instructions.
	144	+	- [Docs](https://gordon.bnema.dev/docs) — Installation, configuration, CLI reference
	145	+	- [Wiki](https://gordon.bnema.dev/wiki) — Tutorials, guides, and examples
57	146
58	147		## Community
59	148

@@ -63,4 +152,4 @@ Config is created at `~/.config/gordon/gordon.toml`. See the [Getting Started gu
63	152
64	153		## License
65	154
66		-	GPL-3.0 - Use freely, contribute back.
	155	+	GPL-3.0 — Use freely, contribute back.


@@ -3,7 +3,7 @@
3		[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)	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)	4		[![Go Report Card](https://goreportcard.com/badge/github.com/bnema/gordon)](https://goreportcard.com/report/github.com/bnema/gordon)
5			5
6	-	Self-hosted web app deployments. Push to your registry, Gordon does the rest.	6	+	Self-hosted container deployment. Push an image, Gordon routes it to the web.
7			7
8		- Website: https://gordon.bnema.dev	8		- Website: https://gordon.bnema.dev
9		- Documentation: [Docs](https://gordon.bnema.dev/docs) \| [Wiki](https://gordon.bnema.dev/wiki)	9		- Documentation: [Docs](https://gordon.bnema.dev/docs) \| [Wiki](https://gordon.bnema.dev/wiki)

@@ -13,17 +13,119 @@ Self-hosted web app deployments. Push to your registry, Gordon does the rest.
13			13
14		## What is Gordon?	14		## What is Gordon?
15			15
16	-	Gordon is a private container registry + HTTP reverse proxy for your VPS. Push a container image exposing a web port, it deploys automatically with zero downtime.	16	+	Gordon 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
			22	+	curl -fsSL https://gordon.bnema.dev/install.sh \| sh
			23	+
			24	+	# Start the server
			25	+	gordon serve
			26	+	```
			27	+
			28	+	Config 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	+
			32	+	Build locally, push directly to your Gordon server:
			33	+
			34	+	```bash
			35	+	# Push an image and deploy it to a domain
			36	+	gordon push app.example.com --image myapp:latest
			37	+
			38	+	# Or add a route manually, then deploy
			39	+	gordon routes add app.example.com myapp:latest
			40	+	gordon routes deploy app.example.com
			41	+
			42	+	# Check status
			43	+	gordon status
			44	+	```
			45	+
			46	+	Roll back, restart, or manage secrets — all from the command line:
17			47
18		```bash	48		```bash
19	-	docker build -t myapp .	49	+	gordon rollback app.example.com # Revert to a previous image tag
20	-	docker push registry.your-server.com/myapp:latest	50	+	gordon restart app.example.com # Restart the container
21	-	# → Live at https://app.your-server.com	51	+	gordon secrets set app.example.com DB_HOST=db.internal API_KEY=secret123
			52	+	```
			53	+
			54	+	## Deploy from CI/CD
			55	+
			56	+	Push 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 }}
22		```	66		```
23			67
24	-	Build on your machine, push to deploy. Works from your laptop or CI.	68	+	### Docker CLI
			69	+
			70	+	```bash
			71	+	docker login registry.mydomain.com
			72	+	docker build -t registry.mydomain.com/myapp:v1.0.0 .
			73	+	docker push registry.mydomain.com/myapp:v1.0.0
			74	+	# -> Deployed automatically
			75	+	```
			76	+
			77	+	See 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 <domain>` \| Tag and push an image to deploy \|
			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 rollback <domain>` \| Roll back to a previous image \|
			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
25			128
26	-	Features:
27		- Private Docker registry on your VPS	129		- Private Docker registry on your VPS
28		- Domain-to-container routing via HTTP reverse proxy	130		- Domain-to-container routing via HTTP reverse proxy
29		- Automatic deployment on image push	131		- Automatic deployment on image push

@@ -37,23 +139,10 @@ Build on your machine, push to deploy. Works from your laptop or CI.
37			139
38		## Documentation	140		## Documentation
39			141
40	-	Full documentation is available at [gordon.bnema.dev](https://gordon.bnema.dev)	142	+	Full documentation at [gordon.bnema.dev](https://gordon.bnema.dev)
41	-
42	-	- [Documentation](https://gordon.bnema.dev/docs) - Installation, configuration, CLI reference
43	-	- [Wiki](https://gordon.bnema.dev/wiki) - Tutorials, guides, and examples
44	-
45	-	## Quick Start
46	-
47	-	```bash
48	-	# Install Gordon
49	-	curl -fsSL https://gordon.bnema.dev/install.sh \| sh
50	-	# Or: curl -fsSL https://raw.githubusercontent.com/bnema/gordon/main/install.sh \| sh
51	-
52	-	# Start Gordon (generates config on first run)
53	-	gordon serve
54	-	```
55			143
56	-	Config is created at `~/.config/gordon/gordon.toml`. See the [Getting Started guide](https://gordon.bnema.dev/docs/getting-started) for complete setup instructions.	144	+	- [Docs](https://gordon.bnema.dev/docs) — Installation, configuration, CLI reference
			145	+	- [Wiki](https://gordon.bnema.dev/wiki) — Tutorials, guides, and examples
57			146
58		## Community	147		## Community
59			148

@@ -63,4 +152,4 @@ Config is created at `~/.config/gordon/gordon.toml`. See the [Getting Started gu
63			152
64		## License	153		## License
65			154
66	-	GPL-3.0 - Use freely, contribute back.	155	+	GPL-3.0 — Use freely, contribute back.