docs(getting-started): update wildcard DNS and clarify remote auth workflow

commit: 70662424c86aab6f8e67fee91879e487f8a6f55d
author: bnema · 8mo ago · 2026-02-11 03:28 UTC
parent: c00708a
signature: unsigned

2 files · +24 -18

M docs/getting-started.md +23 -17


@@ -6,7 +6,7 @@ Deploy your first app with Gordon in under 5 minutes.
6	6
7	7		- A Linux VPS with Docker or Podman installed
8	8		- A domain pointing to your VPS (DNS A record)
9		-	- Cloudflare account (free tier) for HTTPS termination
	9	+	- HTTPS setup: Cloudflare proxy or native TLS in Gordon (`server.tls_enabled = true`)
10	10		- [pass](https://www.passwordstore.org/) (password manager) with GPG key initialized
11	11
12	12		## 1. Install Gordon

@@ -36,7 +36,7 @@ Gordon requires a `token_secret` for JWT authentication. You can store it in `pa
36	36		> [auth]
37	37		> enabled = false
38	38		> ```
39		-	> Skip to [Step 4](#4-configure-your-registry-domain). For production, continue below.
	39	+	> Skip to [Step 4](#4-configure-your-gordon-domain). For production, continue below.
40	40
41	41		Initialize pass (if not already done):
42	42		```bash

@@ -67,30 +67,36 @@ secrets_backend = "pass"
67	67		token_secret = "gordon/auth/token_secret"
68	68		```
69	69
70		-	## 4. Configure Your Registry Domain
	70	+	## 4. Configure Your Gordon Domain
71	71
72	72		Edit `~/.config/gordon/gordon.toml`:
73	73
74	74		```toml
75	75		[server]
76		-	port = 8080 # Proxy port (use with Cloudflare)
	76	+	port = 8080 # Proxy port (use with Cloudflare/rootless)
77	77		registry_port = 5000 # Registry port
78		-	gordon_domain = "gordon.mydomain.com" # Your Gordon domain
	78	+	gordon_domain = "gordon.mydomain.com" # Registry + Admin API domain
79	79
80	80		[routes]
81	81		"app.mydomain.com" = "myapp:latest" # Domain → Image mapping
82	82		```
83	83
84		-	## 5. Set Up DNS
	84	+	## 5. Set Up DNS (Including Wildcard)
85	85
86		-	In Cloudflare (or your DNS provider):
	86	+	`gordon_domain` is the single domain used by both the registry and admin API.
87	87
88		-	\| Type \| Name \| Content \|
89		-	\|------\|------\|---------\|
90		-	\| A \| `app` \| `YOUR_SERVER_IP` \|
91		-	\| A \| `registry` \| `YOUR_SERVER_IP` \|
	88	+	In Cloudflare (or your DNS provider), create:
92	89
93		-	Enable Cloudflare proxy (orange cloud) for HTTPS.
	90	+	\| Type \| Name \| Content \| Proxy \|
	91	+	\|------\|------\|---------\|-------\|
	92	+	\| A \| `gordon` \| `YOUR_SERVER_IP` \| Yes \|
	93	+	\| A/CNAME \| `*` \| `YOUR_SERVER_IP` or `gordon.mydomain.com` \| Yes \|
	94	+
	95	+	Why wildcard (`*`)?
	96	+	- It automatically covers app routes like `app.mydomain.com`, `api.mydomain.com`, `demo.mydomain.com`, etc.
	97	+	- You can add new domains in `[routes]` without creating DNS records one by one.
	98	+
	99	+	If your DNS provider supports wildcard CNAME flattening (Cloudflare does), `* -> gordon.mydomain.com` is usually the cleanest option.
94	100
95	101		## 6. Start Gordon as a Service
96	102

@@ -132,16 +138,16 @@ On your local machine:
132	138
133	139		```bash
134	140		# Log in to your Gordon registry (skip if auth is disabled)
135		-	docker login -u deploy -p <your-token> registry.mydomain.com
	141	+	docker login -u deploy -p <your-token> gordon.mydomain.com
136	142
137	143		# Build your app
138	144		docker build -t myapp .
139	145
140	146		# Tag for your registry
141		-	docker tag myapp registry.mydomain.com/myapp:latest
	147	+	docker tag myapp gordon.mydomain.com/myapp:latest
142	148
143	149		# Push to Gordon
144		-	docker push registry.mydomain.com/myapp:latest
	150	+	docker push gordon.mydomain.com/myapp:latest
145	151		```
146	152
147	153		Your app is now live at `https://app.mydomain.com`!

@@ -153,8 +159,8 @@ Push a new image to deploy with zero downtime:
153	159		```bash
154	160		# Make changes, rebuild
155	161		docker build -t myapp .
156		-	docker tag myapp registry.mydomain.com/myapp:latest
157		-	docker push registry.mydomain.com/myapp:latest
	162	+	docker tag myapp gordon.mydomain.com/myapp:latest
	163	+	docker push gordon.mydomain.com/myapp:latest
158	164		```
159	165
160	166		Gordon automatically:

 - A Linux VPS with Docker or Podman installed
 - A domain pointing to your VPS (DNS A record)
-- Cloudflare account (free tier) for HTTPS termination
+- HTTPS setup: Cloudflare proxy **or** native TLS in Gordon (`server.tls_enabled = true`)
 - [pass](https://www.passwordstore.org/) (password manager) with GPG key initialized
 ## 1. Install Gordon
 > [auth]
 > enabled = false
 > ```
-> Skip to [Step 4](#4-configure-your-registry-domain). For production, continue below.
+> Skip to [Step 4](#4-configure-your-gordon-domain). For production, continue below.
 **Initialize pass (if not already done):**
 ```bash
 token_secret = "gordon/auth/token_secret"
 ```
-## 4. Configure Your Registry Domain
+## 4. Configure Your Gordon Domain
 Edit `~/.config/gordon/gordon.toml`:
 ```toml
 [server]
-port = 8080                              # Proxy port (use with Cloudflare)
+port = 8080                              # Proxy port (use with Cloudflare/rootless)
 registry_port = 5000                     # Registry port
-gordon_domain = "gordon.mydomain.com"    # Your Gordon domain
+gordon_domain = "gordon.mydomain.com"    # Registry + Admin API domain
 [routes]
 "app.mydomain.com" = "myapp:latest"      # Domain → Image mapping
 ```
-## 5. Set Up DNS
+## 5. Set Up DNS (Including Wildcard)
-In Cloudflare (or your DNS provider):
+`gordon_domain` is the single domain used by both the registry and admin API.
-| Type | Name | Content |
+In Cloudflare (or your DNS provider), create:
-|------|------|---------|
-| A | `app` | `YOUR_SERVER_IP` |
-| A | `registry` | `YOUR_SERVER_IP` |
-Enable Cloudflare proxy (orange cloud) for HTTPS.
+| Type | Name | Content | Proxy |
+|------|------|---------|-------|
+| A | `gordon` | `YOUR_SERVER_IP` | Yes |
+| A/CNAME | `*` | `YOUR_SERVER_IP` or `gordon.mydomain.com` | Yes |
+Why wildcard (`*`)?
+- It automatically covers app routes like `app.mydomain.com`, `api.mydomain.com`, `demo.mydomain.com`, etc.
+- You can add new domains in `[routes]` without creating DNS records one by one.
+If your DNS provider supports wildcard CNAME flattening (Cloudflare does), `* -> gordon.mydomain.com` is usually the cleanest option.
 ## 6. Start Gordon as a Service
 ```bash
 # Log in to your Gordon registry (skip if auth is disabled)
-docker login -u deploy -p <your-token> registry.mydomain.com
+docker login -u deploy -p <your-token> gordon.mydomain.com
 # Build your app
 docker build -t myapp .
 # Tag for your registry
-docker tag myapp registry.mydomain.com/myapp:latest
+docker tag myapp gordon.mydomain.com/myapp:latest
 # Push to Gordon
-docker push registry.mydomain.com/myapp:latest
+docker push gordon.mydomain.com/myapp:latest
 ```
 Your app is now live at `https://app.mydomain.com`!
 ```bash
 # Make changes, rebuild
 docker build -t myapp .
-docker tag myapp registry.mydomain.com/myapp:latest
+docker tag myapp gordon.mydomain.com/myapp:latest
-docker push registry.mydomain.com/myapp:latest
+docker push gordon.mydomain.com/myapp:latest
 ```
 Gordon automatically:

M docs/index.md +1 -1


@@ -47,7 +47,7 @@ Gordon runs on your VPS and provides:
47	47		- [Configuration Overview](./config/index.md) - All configuration options
48	48		- [Server Settings](./config/server.md) - Ports, domains, and runtime
49	49		- [Routes](./config/routes.md) - Domain to container mapping
50		-	- [Authentication](./config/auth.md) - Password and token authentication
	50	+	- [Authentication](./config/auth.md) - Registry auth plus remote CLI login/token workflows
51	51		- [Secrets](./config/secrets.md) - Secure credential storage
52	52		- [Network Isolation](./config/network-isolation.md) - Per-app network isolation
53	53		- [Attachments](./config/attachments.md) - Service dependencies


@@ -47,7 +47,7 @@ Gordon runs on your VPS and provides:
47		- [Configuration Overview](./config/index.md) - All configuration options	47		- [Configuration Overview](./config/index.md) - All configuration options
48		- [Server Settings](./config/server.md) - Ports, domains, and runtime	48		- [Server Settings](./config/server.md) - Ports, domains, and runtime
49		- [Routes](./config/routes.md) - Domain to container mapping	49		- [Routes](./config/routes.md) - Domain to container mapping
50	-	- [Authentication](./config/auth.md) - Password and token authentication	50	+	- [Authentication](./config/auth.md) - Registry auth plus remote CLI login/token workflows
51		- [Secrets](./config/secrets.md) - Secure credential storage	51		- [Secrets](./config/secrets.md) - Secure credential storage
52		- [Network Isolation](./config/network-isolation.md) - Per-app network isolation	52		- [Network Isolation](./config/network-isolation.md) - Per-app network isolation
53		- [Attachments](./config/attachments.md) - Service dependencies	53		- [Attachments](./config/attachments.md) - Service dependencies