Skip to main content

Front TLS at install (the --tls flag)

When people reach the platform, the request lands on a front. MOD can put a Caddy server in front to terminate TLS (handle the encrypted connection) and forward to the normal web tier. The --tls flag chooses, at install time, which certificate that front serves. The choice is an install flag, not a one-way door — you can switch it later on a running install.

In plain words: the front is the doorman. --tls decides what kind of ID badge it shows visitors. All three options let the platform support encryption in transit (e.g. NIST SC-8); off is only for when something else in front already does the encryption.

The three modes​

  • internal (the default) — Caddy's own LOCAL certificate authority. Works offline and air-gapped and auto-renews with no internet, so a long-offline site never hits the 90-day public-cert expiry. Browsers will show a warning until each user's machine trusts the site CA — install that CA with the offline-access setup (offline-access-setup.sh). Recommended for on-prem, LAN-only or offline sites.

  • public — Let's Encrypt. Needs this host reachable at its public domain on :80 and :443. Browsers trust it with no setup. Recommended when the install is on a real public domain (SaaS or internet-facing).

  • off — NO encryption at the front. Logins, API keys, session tokens and file uploads cross the network in plain text. Only use it when something else in front already terminates TLS (a corporate load balancer or a reverse proxy you control).

What should I do?​

Reach over the internet at a public domain? use public. Offline / LAN / air-gapped on-prem? use internal (the default). Already behind your own TLS-terminating proxy? use off.

Choosing it at install​

Pass the flag to the install so it is set up front, instead of being asked interactively:

./start-main-server.sh --tls=internal     # local CA (default)
./start-main-server.sh --tls=public       # Let's Encrypt
./start-main-server.sh --tls=off          # front does no TLS

The space form works too: --tls internal. If you leave the flag off, an interactive install asks and defaults to enabled in internal mode; a non-interactive install with no prior value does the same silently and says so. Leaving it off when you already declined before keeps whatever is already recorded.

Switching it on an existing install​

The same choice is switchable on a running install through the update script. It rewrites the front-TLS decision in the config, then brings the front (Caddy

  • nginx) back in line — without running a full update and without touching any volumes:
./update-system.sh --tls=public     # e.g. move an on-prem install onto Let's Encrypt
./update-system.sh --tls=internal   # back to the local CA
./update-system.sh --tls=off        # disable front TLS

What it does, in words:

  • Turning it on (internal or public): Caddy takes the host :80/:443, and nginx is moved to loopback-only alternate ports behind Caddy.
  • Turning it off: the Caddy front is stopped and removed (its certificate storage is kept, so re-enabling reuses it), and nginx is restored to the default host :80/:443.
  • No change requested: if the install is already in the mode you asked for, it says so and changes nothing.

When you run ./update-system.sh with no --tls flag, it prints one status line showing the current mode and how to change it, e.g.:

Front TLS: enabled (mode=internal) — change with ./update-system.sh --tls=<mode>

--help on either script lists the three modes in full.

Related: FIPS mode at install — what MOD does and does not do toward a FIPS-validated crypto path, and when to choose off because something in front already terminates TLS.