Guides
Domains and HTTPS
Available
This page describes what is in the code on the main branch. Let's Encrypt (
tls = "auto") has only been tested against a test ACME server, not yet against the real Let's Encrypt service.
How it works
The daemon contains a reverse proxy that listens on ports 80 and 443. A
service with domains and a port receives the traffic for those domains:
namespace = "shop"
[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com", "www.shop.example.com"]
tls = "auto"
namespace: shop
service:
web:
image: ghcr.io/example/shop:1.4.2
port: 3000
domains: [shop.example.com, www.shop.example.com]
tls: auto
Point the DNS records of the domains at the server and open ports 80 and 443 in its firewall. Deploy, and the proxy serves the service. For routes with TLS, plain HTTP requests are redirected to HTTPS.
The proxy sends the traffic to the container's port. Add a
health check and a replica receives traffic only
when it is ready.
The proxy is on by default. podos setup --ingress off turns it off,
--http-listen and --https-listen change its addresses, and
podos setup --reset http-listen goes back to the default. See
podos setup.
TLS modes
tls |
Certificate |
|---|---|
auto |
From Let's Encrypt over ACME. This is the default when tls is not set. Needs podos setup --acme-email EMAIL. |
self-signed |
Issued by the Podos internal CA created by podos setup. Useful for test environments and internal names. Browsers do not trust it by default. |
off |
None: plain HTTP. |
cert:<name> |
A certificate you upload to the environment under <name> with podos cert set. |
Private keys are stored encrypted, like secrets, and never appear in manifests, logs or API responses.
Let's Encrypt (auto)
Turn it on once on the server:
sudo podos setup --acme-email admin@example.com
--acme-email saves the contact address and records your agreement to the
certificate authority's terms of service
(https://letsencrypt.org/repository/). Only this saved setting enables
tls = "auto". Without it, a route with auto is reported as broken in
podos ps, and every other route keeps working.
Podos has only tested this against a test ACME server, not against the real
Let's Encrypt service yet. A wildcard domain such as *.example.com cannot
use auto; use an uploaded certificate or self-signed.
Your own certificate (cert:<name>)
Upload the chain (leaf first) and the unencrypted key, for the namespace and environment:
podos cert set shop-cert --cert fullchain.pem --key privkey.pem
podos cert list
Then name it in the manifest:
namespace = "shop"
[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com"]
tls = "cert:shop-cert"
namespace: shop
service:
web:
image: ghcr.io/example/shop:1.4.2
port: 3000
domains: [shop.example.com]
tls: cert:shop-cert
The certificate must exist and cover the service's domains when you deploy,
or the release is refused. podos cert set takes effect at once: upload a
renewed certificate under the same name and no redeploy is needed. If you
remove a certificate that a service still uses, the HTTPS handshakes of its
routes fail and podos ps reports the missing certificate. See
podos cert.
Staging or a private CA
Available By default tls = "auto" uses Let's Encrypt production. To test with
Let's Encrypt staging, or to use a private ACME CA, start the daemon with
--acme-directory URL (https only). With a private CA, --acme-ca-file PATH
names the PEM file with the only roots trusted for that connection; the file
and its directory must not be writable by group or others. Both are daemon
flags, not saved by podos setup. See podos daemon.
Paths
A domain may include a path, example.com/shop. The longest matching path
wins. Two services of one environment cannot claim the same domain and path.
One domain, one environment
A domain belongs to one environment. The first claim wins across the whole server: a release that asks for a domain that another namespace holds is refused. Give each environment its own domains, for example with an override:
namespace = "shop"
environments = ["test", "prod"]
[service.web]
image = "ghcr.io/example/shop:1.4.2"
port = 3000
domains = ["shop.example.com"]
[environment.test.service.web]
domains = ["test.shop.example.com"]
tls = "self-signed"
namespace: shop
environments: [test, prod]
service:
web:
image: ghcr.io/example/shop:1.4.2
port: 3000
domains: [shop.example.com]
environment:
test:
service:
web:
domains: [test.shop.example.com]
tls: self-signed
podos down removes the environment's domains and its uploaded
certificates.
When something is wrong
podos ps prints findings about the namespace's domains below the table:
a missing certificate, auto without --acme-email, or a route that could
not be set up. A release is refused before anything starts when a domain is
claimed by another namespace, a cert: certificate is missing or does not
cover the domains, or a wildcard domain uses auto.