Enterprise

Set up TLS

Start a Synnax Core that encrypts every connection with a TLS certificate.

A Synnax Core started without --insecure encrypts every connection with TLS. It needs a certificate for the name that clients use to reach it.

That name is the host in --listen, such as synnax.example.com in --listen=synnax.example.com:9090. The Core binds the port on all network interfaces, whatever the host is. The host must be a name or address that clients can reach, so do not use 0.0.0.0. Use localhost only when every client runs on the same computer.

--insecure turns off TLS only. Users still log in.

Choose a certificate

Certificate	Use it when	Clients
Self-signed	You have no certificate authority.	Each client computer must install the CA certificate.
From your organization	Your organization issues certificates to its hosts.	Computers that already trust your organization’s CA need nothing.
From a public CA	The Core has a public DNS name.	Clients trust it already.

Use a self-signed certificate

Start the Core with --auto-cert:
```
synnax start --listen=synnax.example.com:9090 --auto-cert
```
The Core creates a certificate authority (CA) and a certificate for the --listen host. It writes ca.crt, ca.key, node.crt, and node.key to /usr/local/synnax/certs. To use a different folder, set --certs-dir.
Install ca.crt on each client computer.

The certificate covers only the --listen host. It does not cover localhost or other names of the computer. If you change the host, the next start replaces node.crt and node.key with a pair signed by the same CA, so clients need no new CA certificate.

--auto-cert replaces a node.crt that does not cover the --listen host, even one you supplied. Do not use it with your own certificate.

In Docker, the certificate folder is inside the container. Mount a volume at /usr/local/synnax/certs, or a new container makes a new CA and every client must install it again:

docker run --name synnax -p 9090:9090 --mac-address 02:5a:00:00:00:01 \
  -v synnax-data:/synnax/synnax-data -v synnax-certs:/usr/local/synnax/certs \
  synnaxlabs/synnax --listen=synnax.example.com:9090 --auto-cert

To create the files without starting the Core, run synnax cert ca, then synnax cert node synnax.example.com. synnax cert node does not replace files that exist.

Use your own certificate

Put the certificate and its private key, both in PEM format, in one folder. The certificate must cover the --listen host.

Start the Core with the folder and the two file names:

synnax start --listen=synnax.example.com:9090 \
  --certs-dir=/etc/synnax/certs --node-cert=synnax.crt --node-key=synnax.key

If the certificate does not cover the host, the Core does not start. It logs an error such as serves a certificate that does not cover that host; no client can verify it: x509: certificate is valid for localhost, not synnax.example.com.

The Core needs no CA files for your own certificate. When you replace the certificate files, the Core uses the new files for the next connection, with no restart.

Example: Let’s Encrypt

Get a certificate for the domain with Certbot. The domain must have a public DNS record. The Core then reads the files in place, in /etc/letsencrypt/live/<domain>.

The Core serves a renewed certificate at once. Its embedded Driver and its sessions keep the files the Core read at start, so restart the Core after each renewal. Certbot runs each program in /etc/letsencrypt/renewal-hooks/deploy after a renewal.

For a Core that runs as the synnax user, as in Run the Core as a service:

Let the synnax group read the private key. Certbot keeps the group and mode at each renewal:

sudo chmod 0755 /etc/letsencrypt/live /etc/letsencrypt/archive
sudo chgrp synnax /etc/letsencrypt/live/synnax.example.com/privkey.pem
sudo chmod 0640 /etc/letsencrypt/live/synnax.example.com/privkey.pem

Start the Core with the Certbot files. Do not use --auto-cert:

synnax start --listen=synnax.example.com:9090 \
  --certs-dir=/etc/letsencrypt/live/synnax.example.com \
  --node-cert=fullchain.pem --node-key=privkey.pem

Restart the Core after each renewal:

printf '#!/bin/sh\nsystemctl restart synnax\n' \
  | sudo tee /etc/letsencrypt/renewal-hooks/deploy/restart-synnax
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-synnax

The Core in the image runs as user and group 65532.

Let group 65532 read the private key. Certbot keeps the group and mode at each renewal:

sudo chmod 0755 /etc/letsencrypt/live /etc/letsencrypt/archive
sudo chgrp 65532 /etc/letsencrypt/live/synnax.example.com/privkey.pem
sudo chmod 0640 /etc/letsencrypt/live/synnax.example.com/privkey.pem

Mount all of /etc/letsencrypt read-only, so the links in live resolve, and start the Core with the Certbot files. Do not use --auto-cert:

docker run -d --name synnax -p 9090:9090 --mac-address 02:5a:00:00:00:01 \
  --stop-signal SIGINT --stop-timeout 30 \
  -v synnax-data:/synnax/synnax-data -v /etc/letsencrypt:/etc/letsencrypt:ro \
  synnaxlabs/synnax --listen=synnax.example.com:9090 \
  --certs-dir=/etc/letsencrypt/live/synnax.example.com \
  --node-cert=fullchain.pem --node-key=privkey.pem

Restart the container after each renewal:

printf '#!/bin/sh\ndocker restart synnax\n' \
  | sudo tee /etc/letsencrypt/renewal-hooks/deploy/restart-synnax
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-synnax

Connect to the Core

Console -> when you add the Core, turn on Secure. See Connect the Console.
Browser -> use https://, for example https://synnax.example.com:9090.
Client libraries -> set secure to true. See Connect with TLS.

For more than one address with different certificates, see Serve multiple listeners.

Previous in Enterprise

Upgrade

Install certificates