{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

h2(#certificates). Choose the SSL configuration (SSL_MODE)

Arvados requires an SSL certificate to work correctly. This installer supports these options:

* @self-signed@: let the installer create a self-signed certificate
* @lets-encrypt@: automatically obtain and install an SSL certificate for your hostname
* @bring-your-own@: supply your own certificate in the `certs` directory

h3(#self-signed). Using a self-signed certificate

In the default configuration, this installer uses self-signed certificate(s):

<notextile>
<pre><code>SSL_MODE="self-signed"
</code></pre>
</notextile>

This works everywhere and does not require that you have a domain name.  However, after installation, users will need to "install the self-signed root certificate in the browser.":#ca_root_certificate"

h3(#lets-encrypt). Using a Let's Encrypt certificate

To automatically get a valid certificate via Let's Encrypt, change the configuration like this:

<notextile>
<pre><code>SSL_MODE="lets-encrypt"
</code></pre>
</notextile>

This requires that you have a "real" hostname that you control.  The hostname for your Arvados cluster must be defined in @HOSTNAME_EXT@ and resolve to the public IP address of your Arvados instance, so that Let's Encrypt can validate the domainname ownership and issue the certificate.

When using AWS, EC2 instances can have a default hostname that ends with <i>amazonaws.com</i>. Let's Encrypt has a blacklist of domain names for which it will not issue certificates, and that blacklist includes the <i>amazonaws.com</i> domain, which means the default hostname can not be used to get a certificate from Let's Encrypt.

h3(#bring-your-own). Bring your own certificate

To supply your own certificate, change the configuration like this:

<notextile>
<pre><code>SSL_MODE="bring-your-own"
</code></pre>
</notextile>

Copy your certificate files to the directory specified with the variable @CUSTOM_CERTS_DIR@. The provision script will find it there. The certificate and its key need to be copied to a file named after @HOSTNAME_EXT@. For example, if @HOSTNAME_EXT@ is defined as @my-arvados.example.net@, the script will look for

<notextile>
<pre><code>${CUSTOM_CERTS_DIR}/my-arvados.example.net.crt
${CUSTOM_CERTS_DIR}/my-arvados.example.net.key
</code></pre>
</notextile>

All certificate files will be used by nginx. You may need to include intermediate certificates in your certificate file. See "the nginx documentation":http://nginx.org/en/docs/http/configuring_https_servers.html#chains for more details.