Skip to content

Supplying a Custom SSL Certificate

Two files, server.pem and server.key, are shipped with offline bundles and downloaded by online bundles during an update.

The certificate we provide is signed by us, Vector 35. If you're okay with the occasional "invalid certificate" warning in your web browser, there's no need to replace it. If, however, you wish to use your own SSL certificate, there are some restrictions you should be aware of.

Note

The certificate we provide is valid for all hostnames.

Removing TLS Entirely

You can remove TLS with the --no-tls flag. Importantly, this will not let you run a server over HTTP as clients require TLS. This can, however, let you run the Enterprise server behind a proxy successfully.

That proxy can then be wholly responsible for certificates instead of the Enterprise server. Be aware, however, that clients will be unable to connect to a server that is using a certificate from a CA (other than Vector 35) that is not in their trust store.

Certificate Restrictions

Warning

Clients will be unable to connect to a server that is using a certificate from a CA (other than Vector 35) that is not in their trust store.

The restrictions on certificates are as follows:

  • Must be valid PEM format
  • Intermediate certificates, if any, must follow the primary certificate in this file
  • Must be signed by either:
    • Vector 35
    • Any CA trusted by all clients
  • Must be valid for the hostname used by clients

The restrictions on keys are as follows:

  • Must be valid PEM format
  • Must not require a password

Using the Custom Certificate

Provide your certificate (ENTERPRISE_SERVER_CERT_FILE) and key (ENTERPRISE_SERVER_KEY_FILE) so the proxy can load them at startup. There are three ways to do this:

During Install

This is recommended for new deployments:

./manage_server install --certfile /path/to/your_cert.pem --keyfile /path/to/your_cert.key

The provided files will be copied into place and config.env will be populated with their paths.

After Install, via config.env

For existing installs, we recommend manually adding the following to the config.env file:

ENTERPRISE_SERVER_CERT_FILE=/path/to/your_cert.pem
ENTERPRISE_SERVER_KEY_FILE=/path/to/your_cert.key

Once you've done this, remember to restart the server, if it was already running:

./manage_server stop
./manage_server start --detach

After Install, via CLI Overrides

This is mostly useful for testing, but you can also specify these paths while running the start command to have them override whatever values are in the environment variables:

./manage_server start -c /path/to/your_cert.pem -k /path/to/your_cert.key

These values are not persisted. If you want to make these changes more permanent, update config.env (see above) once you’re satisfied things are working the way you want.