ReferenceClusterProduction

Deploying to Production

Deploy a single node cluster to production.

This page walks you through deploying a single node cluster for production use, which requires a few additional steps compared to development use.

License Keys

If your organization has an enterprise license for Synnax, you’ll need to provide your license key on startup. The easiest way to do this is using the --license-key flag when starting the node. Here’s an example:

synnax start --listen=localhost:9090 --license-key=000000-00000000-0000000000

In production, we recommend using an environment variable or configuration file to store your license key. This is more secure than passing the key as a command line argument. The following example shows how to set the license key using an environment variable:

export SYNNAX_LICENSE_KEY=000000-00000000-0000000000
synnax start --listen=localhost:9090

To see the full list of command line options, environment variables, and configuration file parameters, see this page.

Configuring TLS

We recommend using TLS for securing all communications with your cluster. In fact, TLS is required for connecting to a remote cluster with the Synnax Console.

TLS Certificate Options

There are four important command line options for configuring TLS:

OptionDescriptionDefault
--certs-dirThe path to a directory containing the necessary certificates for the cluster to use./usr/local/synnax/certs
--ca-certThe path relative to --certs-dir to the certificate authority (CA) certificate. This is only required if you're using a self-signed certificate. Certificates generated by public CA's like Let's Encrypt are already trusted, so you don't need to specify this option.ca.crt
--node-certThe path relative to --certs-dir to the node's public certificate file.node.crt
--node-keyThe path relative to --certs-dir to the node's private key file.node.key

Starting the Cluster with TLS

When starting the cluster with TLS, you’ll need to specify the correct options and start the node with the correct hostname in the --listen option. The hostname must match the hostname in the node certificate. Here’s an example for a let’s encrypt certificate:

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

Generating Certificates

Using Synnax’s Auto-Cert Feature

The easiest way to start a secure cluster using self-signed certificates is to use the --auto-cert command line flag when starting the cluster. This will automatically generate all of the relevant certificates and keys for you. Here’s an example for a local cluster:

synnax start --listen=localhost:9090 --auto-cert

Please note that the --auto-cert option will require you to install the generated CA certificate on your client machine in order to trust the self-signed certificate authority. We have a guide on an efficient way to do this here.

Using Let’s Encrypt with Certbot

The easiest way to get started with a trusted certificate is to use Certbot to generate a certificate for your domain. Please note that this requires your domain to be publicly accessible and have a valid DNS record. Once you have a certificate, you can use the --certs-dir option to specify the directory containing the certificate and key files. See the example above for a reference on how to do this.

Important caveats when using Docker

Certbot generates symlinked certificates and keys in /etc/letsencrypt/live/yourdomain.com/. When using Docker, you’ll need to mount the entire /etc/letsencrypt directory into the container, as the live directory contains symlinks to the actual certificate and key files. Here’s an example of how to do this:

 docker run -v /etc/letsencrypt:/usr/local/synnax/certs \
     -p 9090:9090 \
    synnaxlabs/synnax \
    -l localhost:9090 \
    -vm \
    --certs-dir=/usr/local/synnax/certs/live/demo.synnaxlabs.com \
    --node-cert=fullchain.pem  \
    --node-key=privkey.pem

Using Your Own Certificates

When using your own certificates, you’ll need to specify the --certs-dir option and provide the necessary certificates and keys in that directory.