detached a8276fa

docs(cli): use gordon.example.com baseline and tailscale cert guidance

commit
a8276fabc16d2ff616fe04c7928c14f7ad851181
author
brice · · 2026-02-06 19:45 UTC
committer
brice · · 2026-02-06 19:46 UTC
parent
091af1a
signature
unsigned
2 files · +29 -19
Unified
UnifiedSplit
M docs/cli/index.md +5 -5
@@ -122,18 +122,18 @@ when you want to bypass your saved configuration.
122122 Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.
123123 You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`
124124 or in a specific entry in `~/.config/gordon/remotes.toml`.
125-This is useful when admin/API access goes through a private network (for example Tailscale),
126-while your public app domains still use wildcard DNS and normal reverse-proxy routing.
125+For Tailscale setups, you can also avoid `--insecure` by using the machine `*.ts.net` name with Tailscale-issued TLS certs in Gordon server config.
126+Your public app domains can still use wildcard DNS and normal reverse-proxy routing.
127127
128128 ```bash
129129 # Using flags (use the gordon_domain from remote Gordon config)
130-gordon routes list --remote https://gordon.mydomain.com --token $TOKEN
130+gordon routes list --remote https://gordon.example.com --token $TOKEN
131131
132132 # Against self-signed/private CA endpoint
133-gordon --remote https://gordon.mydomain.com --token $TOKEN --insecure status
133+gordon --remote https://gordon.example.com --token $TOKEN --insecure status
134134
135135 # Using environment variables
136-export GORDON_REMOTE=https://gordon.mydomain.com
136+export GORDON_REMOTE=https://gordon.example.com
137137 export GORDON_TOKEN=$TOKEN
138138 export GORDON_INSECURE=true
139139 gordon routes list
@@ -122,18 +122,18 @@ when you want to bypass your saved configuration.
122 Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.122 Use `--insecure` when the remote endpoint uses a self-signed or otherwise untrusted TLS certificate.
123 You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`123 You can make this persistent with `insecure_tls = true` in `[client]` of `~/.config/gordon/gordon.toml`
124 or in a specific entry in `~/.config/gordon/remotes.toml`.124 or in a specific entry in `~/.config/gordon/remotes.toml`.
125-This is useful when admin/API access goes through a private network (for example Tailscale),125+For Tailscale setups, you can also avoid `--insecure` by using the machine `*.ts.net` name with Tailscale-issued TLS certs in Gordon server config.
126-while your public app domains still use wildcard DNS and normal reverse-proxy routing.126+Your public app domains can still use wildcard DNS and normal reverse-proxy routing.
127 127
128 ```bash128 ```bash
129 # Using flags (use the gordon_domain from remote Gordon config)129 # Using flags (use the gordon_domain from remote Gordon config)
130-gordon routes list --remote https://gordon.mydomain.com --token $TOKEN130+gordon routes list --remote https://gordon.example.com --token $TOKEN
131 131
132 # Against self-signed/private CA endpoint132 # Against self-signed/private CA endpoint
133-gordon --remote https://gordon.mydomain.com --token $TOKEN --insecure status133+gordon --remote https://gordon.example.com --token $TOKEN --insecure status
134 134
135 # Using environment variables135 # Using environment variables
136-export GORDON_REMOTE=https://gordon.mydomain.com136+export GORDON_REMOTE=https://gordon.example.com
137 export GORDON_TOKEN=$TOKEN137 export GORDON_TOKEN=$TOKEN
138 export GORDON_INSECURE=true138 export GORDON_INSECURE=true
139 gordon routes list139 gordon routes list
M docs/cli/remotes.md +24 -14
@@ -304,31 +304,41 @@ gordon remotes use prod && gordon routes list
304304 gordon remotes use staging && gordon routes list
305305 ```
306306
307-### Tailscale Admin + Wildcard App Domains
307+### Private Admin + Wildcard App Domains
308308
309-Use this pattern when Gordon admin/API is reachable only on a Tailscale path (self-signed or private cert),
310-while app traffic still uses your public wildcard DNS and reverse-proxy routing.
309+Recommended default: use your normal Gordon admin domain with a valid public certificate.
311310
312311 ```toml
313312 # ~/.config/gordon/remotes.toml
314-active = "prod-ts"
313+active = "prod"
315314
316-[remotes.prod-ts]
317-url = "https://gordon-backend.tailnet.ts.net"
315+[remotes.prod]
316+url = "https://gordon.example.com"
318317 token_env = "GORDON_TOKEN"
319-insecure_tls = true
320318 ```
321319
320+If your admin/API path is private over Tailscale, you have two options:
321+
322+1. Use `insecure_tls = true` for that remote.
323+2. Prefer a Tailscale-issued cert on the machine's `*.ts.net` name and keep verification enabled.
324+
325+Tailscale certificates are issued for tailnet MagicDNS names (for example `host-name.tailnet.ts.net`), not your custom domain. Enable HTTPS certificates in the Tailscale admin DNS settings, then generate files on the host:
326+
322327 ```bash
323-# CLI calls Gordon admin API over Tailscale with insecure TLS allowed
324-gordon status
325-gordon routes list
326-gordon deploy app.bnema.dev
328+sudo tailscale cert --cert-file /etc/gordon/tls/cert.pem --key-file /etc/gordon/tls/key.pem host-name.tailnet.ts.net
329+```
330+
331+Configure Gordon to use them:
332+
333+```toml
334+[server]
335+tls_enabled = true
336+tls_port = 443
337+tls_cert_file = "/etc/gordon/tls/cert.pem"
338+tls_key_file = "/etc/gordon/tls/key.pem"
327339 ```
328340
329-`insecure_tls` only affects CLI -> Gordon admin HTTPS verification. It does not change
330-your runtime routing: the Gordon reverse proxy and container routes can still serve
331-`*.bnema.dev` behind your normal wildcard DNS setup.
341+`insecure_tls` only affects CLI -> Gordon admin HTTPS verification. It does not change runtime routing: Gordon reverse proxy and container routes can still serve wildcard app domains like `*.example.com`.
332342
333343 ## Related
334344
@@ -304,31 +304,41 @@ gordon remotes use prod && gordon routes list
304 gordon remotes use staging && gordon routes list304 gordon remotes use staging && gordon routes list
305 ```305 ```
306 306
307-### Tailscale Admin + Wildcard App Domains307+### Private Admin + Wildcard App Domains
308 308
309-Use this pattern when Gordon admin/API is reachable only on a Tailscale path (self-signed or private cert),309+Recommended default: use your normal Gordon admin domain with a valid public certificate.
310-while app traffic still uses your public wildcard DNS and reverse-proxy routing.
311 310
312 ```toml311 ```toml
313 # ~/.config/gordon/remotes.toml312 # ~/.config/gordon/remotes.toml
314-active = "prod-ts"313+active = "prod"
315 314
316-[remotes.prod-ts]315+[remotes.prod]
317-url = "https://gordon-backend.tailnet.ts.net"316+url = "https://gordon.example.com"
318 token_env = "GORDON_TOKEN"317 token_env = "GORDON_TOKEN"
319-insecure_tls = true
320 ```318 ```
321 319
320+If your admin/API path is private over Tailscale, you have two options:
321+
322+1. Use `insecure_tls = true` for that remote.
323+2. Prefer a Tailscale-issued cert on the machine's `*.ts.net` name and keep verification enabled.
324+
325+Tailscale certificates are issued for tailnet MagicDNS names (for example `host-name.tailnet.ts.net`), not your custom domain. Enable HTTPS certificates in the Tailscale admin DNS settings, then generate files on the host:
326+
322 ```bash327 ```bash
323-# CLI calls Gordon admin API over Tailscale with insecure TLS allowed328+sudo tailscale cert --cert-file /etc/gordon/tls/cert.pem --key-file /etc/gordon/tls/key.pem host-name.tailnet.ts.net
324-gordon status329+```
325-gordon routes list330+
326-gordon deploy app.bnema.dev331+Configure Gordon to use them:
332+
333+```toml
334+[server]
335+tls_enabled = true
336+tls_port = 443
337+tls_cert_file = "/etc/gordon/tls/cert.pem"
338+tls_key_file = "/etc/gordon/tls/key.pem"
327 ```339 ```
328 340
329-`insecure_tls` only affects CLI -> Gordon admin HTTPS verification. It does not change341+`insecure_tls` only affects CLI -> Gordon admin HTTPS verification. It does not change runtime routing: Gordon reverse proxy and container routes can still serve wildcard app domains like `*.example.com`.
330-your runtime routing: the Gordon reverse proxy and container routes can still serve
331-`*.bnema.dev` behind your normal wildcard DNS setup.
332 342
333 ## Related343 ## Related
334 344

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 7

Tags 106

↑↓ moveenter openesc close