Update docs for hosting stack on docker (#1296)

* doc: Implement findings * doc: Update certificates page * doc: Add feedback
TheThingsIndustries · Apr 7, 2024 · 7f2c927 · 7f2c927
1 parent 3e42d29
commit 7f2c927
Show file tree

Hide file tree

Showing 5 changed files with 83 additions and 65 deletions.
diff --git a/doc/content/the-things-stack/host/docker/_index.md b/doc/content/the-things-stack/host/docker/_index.md
@@ -20,10 +20,10 @@ For highly available production cloud deployments with high throughput, we recom
 
 Continue following these instructions to run {{% tts %}} Enterprise or Open Source on your own hardware, using Docker.
 
-In addition to the following written instructions, video instructions for installing {{% tts %}} are available on [The Things Network youtube channel](https://www.youtube.com/watch?v=XgPSU4UkDuE).
+In addition to the following written instructions, video instructions for installing {{% tts %}} are available on [The Things Network youtube channel](https://www.youtube.com/watch?v=DcmgJMvMfZc).
 
 <details><summary>Show video</summary>
-{{< youtube "XgPSU4UkDuE" >}}
+{{< youtube "DcmgJMvMfZc" >}}
 </details>
 
 ## Prerequisites

diff --git a/doc/content/the-things-stack/host/docker/certificates.md b/doc/content/the-things-stack/host/docker/certificates.md
@@ -9,7 +9,13 @@ aliases: [/getting-started/installation/certificates]
 
 <!--more-->
 
-In this guide, we request a free, trusted certificate from [Let's Encrypt](https://letsencrypt.org/getting-started/), using the built in ACME support, but if you already have a certificate (`cert.pem`) and a corresponding key (`key.pem`), you can also use those. For local deployments, you can set up your own Certificate Authority and issue a certificate-key pair.
+In this guide, we request a free, trusted certificate from [Let's Encrypt](https://letsencrypt.org/getting-started/), using the built in ACME support, but if you already have a certificate (`cert.pem`) and a corresponding key (`key.pem`), you can also use those. 
+
+If you are deploying using ACME, move to the [Automatic Certificate Management](#automatic-certificate-management) section.
+
+If you already have CA certificates, move to the [Using Custom Certificates](#using-custom-certificates) section.
+
+If you are deploying locally you can set up your own Certificate Authority and issue a certificate-key pair. Move to the [Custom Certificate Authority](#custom-certificate-authority) section.
 
 ## Automatic Certificate Management
 
@@ -38,48 +44,11 @@ Certificates will automatically be requested the first time you access {{% tts %
 
 Once you have created the `acme` folder and given it appropriate permissions, move on to [run {{% tts %}}]({{< ref "/the-things-stack/host/docker/running-the-stack" >}})!
 
-### Using Custom Certificates
-
-To use [CA certificates you already have](#certificates-from-a-certificate-authority) or [self-signed certificates](#custom-certificate-authority), you will need to uncomment the custom certificates section of `docker-compose.yml`:
-
-{{< highlight yaml "linenos=table,linenostart=66" >}}
-{{< readfile path="/content/the-things-stack/host/docker/configuration/docker-compose-custom-certificates.yml" from=66 to=79 >}}
-{{< /highlight >}}
-
-You will also need to comment out the Let's Encrypt section of `ttn-lw-stack-docker.yml`, and uncomment the custom certificates section:
-
-{{< highlight yaml "linenos=table,linenostart=48" >}}
-{{< readfile path="/content/the-things-stack/host/docker/configuration/ttn-lw-stack-docker-custom-certificates.yml" from=48 to=55 >}}
-{{< /highlight >}}
-
-### Certificates from a Certificate Authority
-
-If you want to use the certificate (`cert.pem`) and key (`key.pem`) that you already have, you also need to set these permissions.
-
-```bash
-sudo chown 886:886 ./cert.pem ./key.pem
-```
-
-{{< warning >}} If you don't set these permissions, you may encounter an error resembling `/run/secrets/key.pem: permission denied`. {{</ warning >}}
-
-The directory hierarchy should look like this:
-
-```bash
-cert.pem
-key.pem
-docker-compose.yml          # defines Docker services for running {{% tts %}}
-config/
-└── stack/
-    └── ttn-lw-stack-docker.yml    # configuration file for {{% tts %}}
-```
-
-Be sure to configure `docker-compose.yml` and `ttn-lw-stack-docker.yml` for your custom certificates, as shown in [using custom certificates](#using-custom-certificates).
-
 ## Custom Certificate Authority
 
 To use TLS on a local or offline deployment, you can use your own Certificate Authority. In order to set that up, you can use `cfssl`, CloudFlare's PKI/TLS toolkit. The `cfssl` installation instructions can be found [here](https://github.com/cloudflare/cfssl#installation).
 
-Write the configuration for your CA to `ca.json`:
+Create a `ca.json` file and write the following configuration to it:
 
 ```json
 {
@@ -139,3 +108,46 @@ config/
 ```
 
 Be sure to configure `docker-compose.yml` and `ttn-lw-stack-docker.yml` for your custom certificates, as shown in [using custom certificates](#using-custom-certificates).
+
+## Using Custom Certificates
+
+To use CA certificates you already have or [self-signed certificates](#custom-certificate-authority), you will need to uncomment the custom certificates section of `docker-compose.yml`:
+
+{{< highlight yaml "linenos=table,linenostart=66" >}}
+{{< readfile path="/content/the-things-stack/host/docker/configuration/docker-compose-custom-certificates.yml" from=66 to=79 >}}
+{{< /highlight >}}
+
+You will also need to comment out the Let's Encrypt section of `ttn-lw-stack-docker.yml`:
+
+{{< highlight yaml "linenos=table,linenostart=48" >}}
+{{< readfile path="/content/the-things-stack/host/docker/configuration/ttn-lw-stack-docker-custom-certificates.yml" from=48 to=55 >}}
+{{< /highlight >}}
+
+And uncomment the custom certificates section:
+
+{{< highlight yaml "linenos=table,linenostart=41" >}}
+{{< readfile path="/content/the-things-stack/host/docker/configuration/ttn-lw-stack-docker-custom-certificates.yml" from=41 to=46 >}}
+{{< /highlight >}}
+
+In order to use the certificate (`cert.pem`) and key (`key.pem`), you also need to set these permissions:
+
+```bash
+sudo chown 886:886 ./cert.pem ./key.pem
+```
+
+{{< warning >}} If you don't set these permissions, you may encounter an error resembling `/run/secrets/key.pem: permission denied`. {{</ warning >}}
+
+The directory hierarchy should look like this:
+
+```bash
+cert.pem
+key.pem
+docker-compose.yml          # defines Docker services for running {{% tts %}}
+config/
+└── stack/
+    └── ttn-lw-stack-docker.yml    # configuration file for {{% tts %}}
+```
+
+Make sure you have configured `docker-compose.yml` and `ttn-lw-stack-docker.yml` for your custom certificates, as shown in [using custom certificates](#using-custom-certificates).
+
+Now that the permissions have been set you can move on to [run {{% tts %}}]({{< ref "/the-things-stack/host/docker/running-the-stack" >}})!
diff --git a/doc/content/the-things-stack/host/docker/configuration/index.md b/doc/content/the-things-stack/host/docker/configuration/index.md
@@ -9,29 +9,33 @@ This guide shows an example of configuring {{% tts %}} using configuration files
 
 If configuring {{% tts %}} as `localhost` on a machine with no public IP or DNS address, see the [`localhost`](#running-the-things-stack-as-localhost) section.
 
-In addition to the written instructions below, video instructions for installing {{% tts %}} are available on [The Things Network youtube channel](https://www.youtube.com/c/TheThingsNetworkCommunity).
+In addition to the written instructions below, video instructions for installing {{% tts %}} are available on [The Things Network youtube channel](https://www.youtube.com/watch?v=DcmgJMvMfZc).
 
 <details><summary>Show video</summary>
-{{< youtube "XgPSU4UkDuE" >}}
+{{< youtube "DcmgJMvMfZc" >}}
 </details>
 
 ## Configuration Files
+{{% tts %}} requires two configuration files when installing with Docker: `docker-compose.yml` and `ttn-lw-stack-docker.yml`. The files are provided below:
 
-{{% tts %}} requires two configuration files when installing with Docker: `docker-compose.yml` and `ttn-lw-stack-docker.yml`.
+{{< tabs/container "Enterprise" "Open Source" >}}
+{{< tabs/tab "Enterprise" >}}
 
-Example files for Enterprise and Open source are provided [below](#example-configuration-files). Note that you must replace the example server address `thethings.example.com` in `ttn-lw-stack-docker.yml`, and you should change additional settings for production deployments, which we cover below.
+Download the example `docker-compose.yml` for {{% tts %}} Enterprise <a href="docker-compose-enterprise.yml" download="docker-compose.yml">here</a>.
 
-### `docker-compose.yml`
+Download the example `ttn-lw-stack-docker.yml` for {{% tts %}} Enterprise <a href="ttn-lw-stack-docker-enterprise.yml" download="ttn-lw-stack-docker.yml">here</a>.
 
-`docker-compose.yml` defines the Docker services of {{% tts %}} and its dependencies, and is used to configure Docker.
+{{< /tabs/tab >}}
+{{< tabs/tab "Open Source" >}}
 
-### `ttn-lw-stack-docker.yml`
+Download the example `docker-compose.yml` for {{% tts %}} Open Source <a href="docker-compose-open-source.yml" download="docker-compose.yml">here</a>.
 
-`ttn-lw-stack-docker.yml` contains the configuration specific to {{% tts %}} deployment and is used to configure {{% tts %}}. When {{% tts %}} starts, it searches through `ttn-lw-stack-docker.yml` for component server addresses, a TLS certificate source, client authentication credentials, and other configuration parameters.
+Download the example `ttn-lw-stack-docker.yml` for {{% tts %}} Open Source <a href="ttn-lw-stack-docker-open-source.yml" download="ttn-lw-stack-docker.yml">here</a>.
 
-The configuration options in `ttn-lw-stack-docker` can also be specified using command-line flags or environment variables. All configuration options have a corresponding environment variable and command-line flag. See the [Configuration Reference]({{< ref "reference/configuration" >}}) for more information about the configuration options.
+{{< /tabs/tab >}}
+{{< /tabs/container >}}
 
-This guide assumes the following directory hierarchy. Create this folder structure with `docker-compose.yml`and `ttn-lw-stack-docker.yml`:
+Create the following folder structure with `docker-compose.yml`and `ttn-lw-stack-docker.yml`:
 
 ```bash
 docker-compose.yml          # defines Docker services for running {{% tts %}}
@@ -40,26 +44,21 @@ config/
     └── ttn-lw-stack-docker.yml    # configuration file for {{% tts %}}
 ```
 
-## Example Configuration Files
+Make sure you replace the example server address `thethings.example.com` in `ttn-lw-stack-docker.yml` with the address of your deployment. The easiest way to do this is to use the search and replace function in your preferred code editor.
 
-{{< tabs/container "Enterprise" "Open Source" >}}
-{{< tabs/tab "Enterprise" >}}
-
-Download the example `docker-compose.yml` for {{% tts %}} Enterprise <a href="docker-compose-enterprise.yml" download="docker-compose.yml">here</a>.
+Next, proceed to the instructions below on how to change additional settings for production deployments.
 
-Download the example `ttn-lw-stack-docker.yml` for {{% tts %}} Enterprise <a href="ttn-lw-stack-docker-enterprise.yml" download="ttn-lw-stack-docker.yml">here</a>.
+## Configuration Files Explained
 
-{{< /tabs/tab >}}
-{{< tabs/tab "Open Source" >}}
+### `docker-compose.yml`
 
-Download the example `docker-compose.yml` for {{% tts %}} Open Source <a href="docker-compose-open-source.yml" download="docker-compose.yml">here</a>.
+`docker-compose.yml` defines the Docker services of {{% tts %}} and its dependencies, and is used to configure Docker.
 
-Download the example `ttn-lw-stack-docker.yml` for {{% tts %}} Open Source <a href="ttn-lw-stack-docker-open-source.yml" download="ttn-lw-stack-docker.yml">here</a>.
+### `ttn-lw-stack-docker.yml`
 
-{{< /tabs/tab >}}
-{{< /tabs/container >}}
+`ttn-lw-stack-docker.yml` contains the configuration specific to {{% tts %}} deployment and is used to configure {{% tts %}}. When {{% tts %}} starts, it searches through `ttn-lw-stack-docker.yml` for component server addresses, a TLS certificate source, client authentication credentials, and other configuration parameters.
 
-These example configuration files contain all of the configuration settings you need to run {{% tts %}} for development. Be sure to update `ttn-lw-stack-docker.yml` with your server address.
+The configuration options in `ttn-lw-stack-docker` can also be specified using command-line flags or environment variables. All configuration options have a corresponding environment variable and command-line flag. See the [Configuration Reference]({{< ref "reference/configuration" >}}) for more information about the configuration options.
 
 Settings in `docker-compose.yml` and `ttn-lw-stack-docker.yml` files are explained in detail in [Understanding Docker Configuration](#understanding-docker-configuration) and [Understanding The Things Stack Configuration](#understanding-the-things-stack-configuration) sections below. Further, we provide tips for running {{% tts %}} in production.
 

diff --git a/doc/content/the-things-stack/host/docker/running-the-stack.md b/doc/content/the-things-stack/host/docker/running-the-stack.md
@@ -47,7 +47,7 @@ docker compose run --rm stack is-db create-tenant
 
 This will take the `tenancy.default-id` Tenant ID from the [configuration]({{< relref "configuration" >}}) in `ttn-lw-stack-docker.yml`. To specify another Tenant ID, use the `--id` parameter.
 
-Next, an initial `admin` user has to be created. Make sure to give it a good password.
+Next, an initial `admin` user has to be created. Make sure the user ID is in lowercase and give it a good password.
 
 ```bash
 docker compose run --rm stack is-db create-admin-user \

diff --git a/doc/content/the-things-stack/host/docker/troubleshooting.md b/doc/content/the-things-stack/host/docker/troubleshooting.md
@@ -28,6 +28,13 @@ Our `docker-compose.yml` file uses [Compose file version 3.7](https://docs.docke
 
 Ensure you have a DNS record pointing to your server's public IP address. See your domain registrar's help section for instructions, or [name.com's DNS guide](https://www.name.com/support/articles/205188538-Pointing-your-domain-to-hosting-with-A-records) for general information about pointing records to your IP address.
 
+## Key Permission Denied
+
+If you run into `/run/secrets/key.pem: permission denied`, you have probably forgotten to set permissions. To set permissions:
+```bash
+sudo chown 886:886 ./cert.pem ./key.pem
+```
+
 ## Forbidden
 
 If you see an error reading: