wmantly
426fa111ec
- New docs/concepts-{hosts,dns,access,api-tokens}.md -- plain-language
guides aimed at less technical readers, each linking onward to the
existing system-design-level doc for anyone who wants that detail.
Card help links (Proxy List, Add/Edit host, DNS Provider cards,
Users/Permissions/Groups cards) now point here instead of straight at
Installation/Architecture.
- The "New API Token" card had no help link at all -- added, pointing to
the new API Tokens doc.
- Fixed the in-app docs viewer rendering every docs/*.md page with a
garbled heading + stray <hr> at the top: Jekyll front matter (meant
only for the GitHub Pages build) was never stripped before being
handed to the markdown renderer.
- Fixed cross-doc links never resolving in-app, since this viewer serves
docs at /docs/<slug> with no .html suffix: rewritten to the correct
in-app URL, first by registered slug, falling back to the doc's real
filename (the correct, working link form on the Jekyll/GitHub Pages
build) -- same idea as the existing image-path fix, and lets one link
written in a doc work on both targets.
Bumps to v1.1.13.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KDEx8ghuZR61pqPXc6da9C
3.5 KiB
layout, title, description
| layout | title | description |
|---|---|---|
| default | Hosts & HTTPS | A plain-language guide to hosts, HTTPS certificates, and wildcards in theta42/proxy. |
Hosts & HTTPS
This page explains, in plain language, what a "host" is and how this app gets you working HTTPS without you having to think about certificates. For the deeper system-design detail, see Architecture; for step-by-step setup, see Installation.
What's a "host"?
A host is one entry telling the proxy: "when someone requests this
public address, send them to that server." For example: requests for
photos.example.com get sent to the little box in your closet running your
photo app on port 8080. Each app or service you want to reach from outside
your network — a home automation dashboard, a media server, this proxy's
own management UI — gets its own host entry.
Two settings on a host are easy to mix up:
- Incoming host name — the public address people type in their
browser (
photos.example.com). - Target IP/port — where the proxy actually sends the request behind
the scenes (
10.0.0.5:8080, or a hostname likephoto-server).
Everything else on the host form (traffic limits, access rules, authentication) is optional — a bare host with just those two fields already works.
HTTPS certificates: mostly automatic
Every public website needs an HTTPS certificate so browsers show the lock icon instead of a scary warning. This app gets one for you automatically from Let's Encrypt the first time a host is actually requested — you don't manually request, install, or renew anything for a normal host. This happens behind the scenes using a method called HTTP-01, and it's the default for every new host.
Wildcards: one certificate for a whole family of hosts
Sometimes you want every subdomain under one name to work — app1.,
app2., anything.example.com — without registering each one by hand and
waiting for its own certificate. That's what a wildcard host does: a
single host entry named *.example.com gets one certificate that covers
the whole family at once. Setting one up needs one extra piece of
information the automatic method above doesn't need — see
DNS Providers for why.
Once a wildcard exists, you have two ways to actually use it:
- Register nothing else, and turn on "Match any subdomain" on the wildcard host itself — any subdomain that doesn't already have its own entry gets automatically routed to the wildcard's target the first time it's requested. Convenient, but it means literal typos and random scan traffic get routed too, not just the subdomains you meant to use.
- Register each subdomain as its own host, as a "Parent Wildcard" child — more setup, but each subdomain can point at a different target/server while still reusing the one wildcard certificate instead of getting its own. This is the recommended default and is what "Match only subdomains defined here" (the host form's default) does.
You'll see the "Parent Wildcard" option light up automatically on the
host form whenever the name you're entering already has a matching
wildcard available to reuse — including the wildcard's own bare base
domain (e.g. example.com itself, not just something.example.com).
Want more detail?
This page skips the system-internals (Redis, OpenResty, the lookup service) and the exact install steps. For those, see Architecture and Installation.