16561: Document ListenURL config.
[arvados.git] / doc / _includes / _ssl_config_single.liquid
1 {% comment %}
2 Copyright (C) The Arvados Authors. All rights reserved.
3
4 SPDX-License-Identifier: CC-BY-SA-3.0
5 {% endcomment %}
6
7 h2(#certificates). Choose the SSL configuration (SSL_MODE)
8
9 Arvados requires an SSL certificate to work correctly. This installer supports these options:
10
11 * @self-signed@: let the installer create a self-signed certificate
12 * @lets-encrypt@: automatically obtain and install an SSL certificate for your hostname
13 * @bring-your-own@: supply your own certificate in the `certs` directory
14
15 h3(#self-signed). Using a self-signed certificate
16
17 In the default configuration, this installer uses self-signed certificate(s):
18
19 <notextile>
20 <pre><code>SSL_MODE="self-signed"
21 </code></pre>
22 </notextile>
23
24 When connecting to the Arvados web interface for the first time, you will need to accept the self-signed certificate as trusted to bypass the browser warnings. This can be a little tricky to do. Alternatively, you can also install the self-signed root certificate in your browser, see <a href="#ca_root_certificate">below</a>.
25
26 h3(#lets-encrypt). Using a Let's Encrypt certificate
27
28 To automatically get a valid certificate via Let's Encrypt, change the configuration like this:
29
30 <notextile>
31 <pre><code>SSL_MODE="lets-encrypt"
32 </code></pre>
33 </notextile>
34
35 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.
36
37 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.
38
39 h3(#bring-your-own). Bring your own certificate
40
41 To supply your own certificate, change the configuration like this:
42
43 <notextile>
44 <pre><code>SSL_MODE="bring-your-own"
45 </code></pre>
46 </notextile>
47
48 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
49
50 <notextile>
51 <pre><code>${CUSTOM_CERTS_DIR}/my-arvados.example.net.crt
52 ${CUSTOM_CERTS_DIR}/my-arvados.example.net.key
53 </code></pre>
54 </notextile>
55
56 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.