82 lines
4.0 KiB
Markdown
82 lines
4.0 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`).
|
|
|
|
## Load Balancing
|
|
|
|
If you have multiple servers running the same application, you can load balance traffic across them. When editing a host, you can specify **Additional Targets** (one `IP:port` per line). The proxy will automatically distribute incoming requests across your primary target and all additional targets using a round-robin strategy, providing simple high availability and load distribution without extra configuration.
|
|
|
|
## 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)
|