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
78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
---
|
|
layout: default
|
|
title: Hosts & HTTPS
|
|
description: 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](architecture.html); for
|
|
step-by-step setup, see [Installation](installation.html).
|
|
|
|
## 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 like `photo-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](https://letsencrypt.org) 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](concepts-dns.html) 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](architecture.html) and [Installation](installation.html).
|
|
|
|
[← Back to Home](index.html)
|