HTTPS

Companion can serve HTTPS itself, so you do not need a reverse proxy in front of it. Only administrators can set it up.

Two ports

Port	Default	When it listens
HTTP	8080	Always.
HTTPS	8443	Only while a certificate is installed. It starts the moment you install one and stops when you remove it, without a restart.

Publish the HTTPS port when you start the container, for example on the standard port 443:

docker run -d --name pizug-companion -p 3000:8080 -p 443:8443 -v pizug_companion:/data --restart=always pizug/companion:2.0.0

Install a certificate

There are two ways. When both are present, the files win.

In the browser

Open HTTPS in the menu, paste or upload the certificate and its private key, and save. The page checks that the two belong together and shows subject, issuer, names, validity and warnings. The private key is stored encrypted and is never shown again. To renew a certificate that keeps its key, leave the key field empty.

If you do not want to send a private key through a browser over plain HTTP during the first setup, use the command line and restart the container afterwards:

docker run --rm -v pizug_companion:/data -v /path/to/certs:/certs:ro pizug/companion:2.0.0 \
  tls set --cert /certs/fullchain.pem --key /certs/privkey.pem

tls show describes the stored certificate and tls clear removes it.

From files

Set COMPANION_TLS_CERT and COMPANION_TLS_KEY to the paths of the two files inside the container. The files are read again when they change, so certbot, cert-manager or a scheduled copy can renew the certificate without a restart. While files are configured, the HTTPS page shows the certificate but does not accept uploads. If the files cannot be read at start, the server does not start.

What is accepted

• PEM only. The certificate first, followed by any intermediate certificates (the usual “fullchain” layout).
• An unencrypted private key. Remove a passphrase with openssl pkey -in encrypted.key -out plain.key first; Companion encrypts the key itself when it stores it.
• .pfx / PKCS#12 bundles are not accepted yet. Convert one with openssl pkcs12 -in bundle.pfx -out fullchain-and-key.pem -noenc (-nodes on OpenSSL 1.x).

The page warns, but does not refuse, when the certificate is expired or expires within 30 days, has no subject alternative names, lacks its intermediates, or lists an IP address as a DNS name. Browsers only match an IP address against an IP entry of the certificate.

Plain HTTP while HTTPS is on

The HTTP port keeps working. Two settings on the HTTPS page decide what browsers see there:

• Redirect sends page loads on HTTP to HTTPS. API calls and the health check are not redirected.
• External HTTPS address is the address users reach the server at when it differs from “same host, port 8443”: for example https://companion.example.com with the mapping -p 443:8443 above, or behind a load balancer.

To allow HTTPS only, do not publish the HTTP port (leave out -p 3000:8080). It stays reachable inside the container for the health check.

Behind a reverse proxy

You can also end TLS at a reverse proxy and keep Companion on plain HTTP. The proxy must send X-Forwarded-Proto: https.

nginx

Companion’s user interface sends a request header named tenant_key. nginx silently drops headers with an underscore unless the server block says underscores_in_headers on;. Without it, every tool behaves as if no tenant was chosen.