TheThingsIndustries · KrishnaIyer · Mar 4, 2025 · Mar 3, 2025
@@ -96,15 +96,15 @@ sudo journalctl -f -u lorawan-stack.service
 
 ## Routing LoRaWAN Traffic
 
-Now that your stack has been successfully deployed, let's look at how to connect a LoRaWAN® Gateway, Register a LoRaWAN Device and read traffic from this device.
+Now that your stack has been successfully deployed, let's look at how to connect a LoRaWAN gateway, register a LoRaWAN device and read traffic from this device.
 
 ### Connecting a Gateway
 
-Please check [Gateways]({{< relref "gateways" >}}) section to find an extensive connecting guide for the particular brand/model of your gateway.
+Please check [Gateways]({{< ref "/hardware/gateways/concepts/adding-gateways" >}}) section to learn how to add gateways.
 
 ### Registering a Device
 
-Please check the [Adding Devices]({{< relref "/hardware/devices/adding-devices" >}}) guide.
+Please check the [Adding Devices]({{< ref "/hardware/devices/adding-devices" >}}) guide.
 
 ## AWS IoT
 

@@ -115,10 +115,10 @@ Be sure to configure `docker-compose.yml` and `ttn-lw-stack-docker.yml` for your
 
 ## 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`:
+To use CA certificates you already have or [self-signed certificates](#custom-certificate-authority), you will need to specify the custom certificates section of `docker-compose.yml`:
 
-{{< highlight yaml "linenos=table,linenostart=66" >}}
-{{< readfile path="/content/enterprise/docker/configuration/docker-compose-custom-certificates.yml" from=66 to=79 >}}
+{{< highlight yaml "linenos=table,linenostart=67" >}}
+{{< readfile path="/content/enterprise/docker/configuration/docker-compose-custom-certificates.yml" from=67 to=80 >}}
 {{< /highlight >}}
 
 You will also need to comment out the Let's Encrypt section of `ttn-lw-stack-docker.yml`:

@@ -61,6 +61,7 @@ services:
       - "8886:8886"
       - "1887:1887"
       - "8887:8887"
+      - "8889:8889"
       - "1700:1700/udp"
 
     # If using custom certificates:

@@ -5,7 +5,7 @@ services:
     # In production, replace 'latest' with tag from https://hub.docker.com/r/timescale/timescaledb/tags
     # If you are not using the Storage Integration nor Network Operations Center, you can use vanilla Postgres.
     # The minimum Postgres version supported is 14.x.
-    image: "timescale/timescaledb:latest-pg14"
+    image: "timescale/timescaledb:latest-pg16"
     restart: unless-stopped
     environment:
       - POSTGRES_PASSWORD=root
@@ -95,6 +95,7 @@ services:
       - "8887:8887"
       - "1888:1888"
       - "8888:8888"
+      - "8889:8889"
       - "1700:1700/udp"
 
     # If using custom certificates:

@@ -61,6 +61,7 @@ services:
       - "8886:8886"
       - "1887:1887"
       - "8887:8887"
+      - "8889:8889"
       - "1700:1700/udp"
 
     # If using custom certificates:

@@ -93,7 +93,7 @@ In production, replace the `image` with a working, stable tag from [Docker Hub -
 The simplest configuration for PostgreSQL looks like this (excerpted from the example `docker-compose.yml`):
 
 {{< highlight yaml "linenos=table,linenostart=4" >}}
-{{< readfile path="/content/enterprise/docker/configuration/docker-compose-enterprise.yml" from=4 to=17 >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=4 to=17 >}}
 {{< /highlight >}}
 
 {{< note >}}
@@ -131,7 +131,7 @@ It is also possible (and even preferred) to use a managed Redis database. In thi
 The simplest configuration for Redis looks like this (excerpted from the example `docker-compose.yml`):
 
 {{< highlight yaml "linenos=table,linenostart=19" >}}
-{{< readfile path="/content/enterprise/docker/configuration/docker-compose-enterprise.yml" from=19 to=27 >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=19 to=27 >}}
 {{< /highlight >}}
 
 ### {{% tts %}}
@@ -163,7 +163,7 @@ The `depends_on` field tells Docker Compose that {{% tts %}} depends on PostgreS
 Under the `volumes` section, volumes for the files that need to be persisted on the disk are defined. There are stored blob files (such as profile pictures) and certificate files retrieved with ACME (if required). Also, local `./config/stack/` directory is mounted on the container under `/config`, so that {{% tts %}} can find the configuration file at `/config/ttn-lw-stack-docker.yml`.
 
 {{< highlight yaml "linenos=table,linenostart=65" >}}
-{{< readfile path="/content/enterprise/docker/configuration/docker-compose-enterprise.yml" from=65 to=69 >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=65 to=69 >}}
 {{< /highlight >}}
 
 {{< note >}} If your `ttn-lw-stack-docker.yml` is in a directory other than `./config/stack`, you will need to change this volume accordingly. {{</ note >}}
@@ -177,7 +177,7 @@ The databases used by {{% tts %}} are configured in the `environment` section. I
 The `ports` section exposes {{% tts %}}'s ports outside the Docker container. Port `80` and `443` are mapped to the internal HTTP and HTTPS ports. The other ports have a direct mapping. If you don't need support for gateways and applications that don't use TLS, you can remove ports starting with `188`:
 
 {{< highlight yaml "linenos=table,linenostart=78" >}}
-{{< readfile path="/content/enterprise/docker/configuration/docker-compose-enterprise.yml" from=78 to=98 >}}
+{{< readfile path="/content/enterprise/docker/configuration/docker-compose-enterprise.yml" from=78 to=99 >}}
 {{< /highlight >}}
 
 {{< note >}} Be sure to provide network access to these ports on the machine you are running {{% tts %}}. {{</ note >}}
@@ -227,7 +227,9 @@ host, and also to use it as the default host.
 
 If using Let's Encrypt, certificates will automatically be requested the first time you access {{% tts %}}. You will notice that the page takes some time to load while certificates are obtained in the background.
 
-See the [TLS Options configuration reference]({{< ref "/enterprise/management/configuration/the-things-stack#tls-options" >}}) for more information.
+{{< highlight yaml "linenos=table,linenostart=61" >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=61 to=71 >}}
+{{< /highlight >}}
 
 Make sure that you use the correct `tls` configuration depending on whether you are using Let's Encrypt or your own certificate files.
 
@@ -237,28 +239,46 @@ If you are using your own certificate files, make sure to uncomment the lines th
 {{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=53 to=59 >}}
 {{< /highlight >}}
 
-If you are using Let's Encrypt in a multi-tenant {{% tts %}} environment, all tenant addresses have to be specified in the `ttn-lw-stack-docker.yml` file using `tls.acme.hosts` configuration option with `*.thethings.example.com` wildcard.
+See the [TLS Options configuration reference]({{< ref "/enterprise/management/configuration/the-things-stack#tls-options" >}}) for more information.
 
-{{< highlight yaml "linenos=table,linenostart=61" >}}
-{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=61 to=70 >}}
-{{< /highlight >}}
+Make sure that you use the correct `tls` configuration depending on whether you are using Let's Encrypt or your own certificate files.
 
 ### Console Component URLs
 
 The `console` section configures the URLs for the Web UI and the secret used by the console client. These tell {{% tts %}} where all its components are accessible. Be sure to replace these, and all the other server addresses, with yours.
 
-{{< highlight yaml "linenos=table,linenostart=89" >}}
-{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=89 to=115 >}}
+{{< highlight yaml "linenos=table,linenostart=91" >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=91 to=116 >}}
 {{< /highlight >}}
 
 {{< warning >}} Failure to correctly configure component URLs is a common problem that will prevent the stack from starting. Be sure to replace all instances of `thethings.example.com` with your domain name! {{</ warning >}}
 
 The `client-secret` will be needed later when authorizing the Console. Be sure to set and remember it!
 
-{{< highlight yaml "linenos=table,linenostart=116" >}}
-{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=116 to=121 >}}
+{{< highlight yaml "linenos=table,linenostart=117" >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=117 to=122 >}}
 {{< /highlight >}}
 
+### Managed Gateways {{< new-in-version "3.34.0" >}}
+
+If you want to connected managed gateways, e.g. [The Things Indoor Gateway Pro]({{< ref "/hardware/gateways/models/thethingsindoorgatewaypro" >}}), you need to enable The Things Gateway Controller. This is a central service operated by The Things Industries that allows for claiming and remotely managing gateways. {{% tts %}} is natively integrated with The Things Gateway Controller.
+
+To authenticate with The Things Gateway Controller, {{% tts %}} typically uses the same TLS certificate as used for the TLS server, either Let's Encrypt or custom certificates.
+
+When using Let's Encrypt:
+
+{{< highlight yaml "linenos=table,linenostart=143" >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=143 to=151 >}}
+{{< /highlight >}}
+
+When using custom certificates:
+
+{{< highlight yaml "linenos=table,linenostart=152" >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=152 to=156 >}}
+{{< /highlight >}}
+
+{{< note >}} If you are using a private PKI for generating certificates (e.g. a self-signed CA), you need to share your CA file with The Things Industries in order for The Things Gateway Controller to verify your certificate and authenticate your deployment. Contact [The Things Industries support](mailto:[email protected]). {{</ note >}}
+
 ### NOC
 
 {{< distributions "Enterprise" >}} The `noc` section configures the Network Operations Center.
@@ -267,25 +287,25 @@ Besides `ui` and `oauth` settings, storage settings need to be configured in the
 
 To authorize the NOC, be sure to set and remember the client secret.
 
-{{< highlight yaml "linenos=table,linenostart=161" >}}
-{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=161 to=170 >}}
+{{< highlight yaml "linenos=table,linenostart=157" >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=157 to=175 >}}
 {{< /highlight >}}
 
 To visualize data, configure the `grafana` section.
 
-{{< highlight yaml "linenos=table,linenostart=179" >}}
-{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=179 to=184 >}}
+{{< highlight yaml "linenos=table,linenostart=176" >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=176 to=181 >}}
 {{< /highlight >}}
 
 ### Multi-tenancy
 
 {{< distributions "Enterprise" >}} If running a multi-tenant environment, we need to configure the default tenant ID, and the base domain from which tenant IDs are inferred. See the [`tenancy` configuration reference]({{< ref "/enterprise/management/configuration/the-things-stack#multi-tenancy" >}}).
 
 {{< highlight yaml "linenos=table,linenostart=188" >}}
-{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=188 to=191 >}}
+{{< readfile path="/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=184 to=187 >}}
 {{< /highlight >}}
 
-For multi-tenant environments you'll also need to configure tenant admin keys:
+For multi-tenant environments you'll also need to configure tenant admin keys in the `is` section:
 
 {{< highlight yaml "linenos=table,linenostart=40" >}}
 {{< readfile path="/content/enterprise/docker/configuration/ttn-lw-stack-docker-enterprise.yml" from=40 to=42 >}}

@@ -47,12 +47,13 @@ tls:
 
 # Let's encrypt for "thethings.example.com"
 # tls:
-#   source: 'acme'
+#   source: acme
 #   acme:
-#     dir: '/var/lib/acme'
-#     email: '[email protected]'
-#     hosts: ['thethings.example.com']
-#     default-host: 'thethings.example.com'
+#     enable: true
+#     dir: /var/lib/acme
+#     email: "[email protected]"
+#     hosts: ["thethings.example.com"]
+#     default-host: "thethings.example.com"
 
 # If Gateway Server enabled, defaults for "thethings.example.com":
 gs:
@@ -68,9 +69,6 @@ gcs:
   basic-station:
     default:
       lns-uri: "wss://thethings.example.com:8887"
-  the-things-gateway:
-    default:
-      mqtt-server: "mqtts://thethings.example.com:8881"
 
 # Web UI configuration for "thethings.example.com":
 console:
@@ -87,6 +85,8 @@ console:
       base-url: "https://thethings.example.com/api/v3"
     js:
       base-url: "https://thethings.example.com/api/v3"
+    gcs:
+      base-url: "https://thethings.example.com/api/v3"
     qrg:
       base-url: "https://thethings.example.com/api/v3"
     edtc:
@@ -109,21 +109,17 @@ as:
     downlink:
       public-address: "thethings.example.com:1885/api/v3"
 
-# If Device Claiming Server enabled, defaults for "thethings.example.com":
-dcs:
-  oauth:
-    authorize-url: "https://thethings.example.com/oauth/authorize"
-    token-url: "https://thethings.example.com/oauth/token"
-    logout-url: "https://thethings.example.com/oauth/logout"
-    client-id: "device-claiming"
-    client-secret: "device-claiming" # choose or generate a secret
-  ui:
-    canonical-url: "https://thethings.example.com/claim"
-    as:
-      base-url: "https://thethings.example.com/api/v3"
-    dcs:
-      base-url: "https://thethings.example.com/api/v3"
-    is:
-      base-url: "https://thethings.example.com/api/v3"
-    ns:
-      base-url: "https://thethings.example.com/api/v3"
+# Managed gateway configuration, defaults for "thethings.example.com".
+# This configures a connection with The Things Gateway Controller, a service operated by The Things Industries.
+# This allows connecting, for example, The Things Indoor Gateway Pro.
+ttgc:
+  enabled: true
+  domain: thethings.example.com
+  # If using custom certificates (the X.509 Extended Key Usage must include Client Authentication):
+  tls:
+    source: file
+    certificate: /run/secrets/cert.pem
+    key: /run/secrets\
+  # If using Let's Encrypt (see above):
+  # tls:
+  #   source: acme
@@ -60,13 +60,14 @@ http:
 
 # Let's encrypt for "thethings.example.com"
 tls:
-  source: "acme"
+  source: acme
   acme:
-    dir: "/var/lib/acme"
+    enable: true
+    dir: /var/lib/acme
     email: "[email protected]"
     hosts: ["thethings.example.com"]
-    # If running a multi-tenant environment, specify the wildcard address:
-    # hosts: ["*.thethings.example.com"]
+    # If running a multi-tenant environment, specify the wildcard address too:
+    # hosts: ["*.thethings.example.com", "thethings.example.com"]
     default-host: "thethings.example.com"
 
 # If Gateway Server enabled, defaults for "thethings.example.com":
@@ -97,14 +98,14 @@ console:
       base-url: "https://thethings.example.com/api/v3"
     gs:
       base-url: "https://thethings.example.com/api/v3"
-    gcs:
-      base-url: "https://thethings.example.com/api/v3"
     ns:
       base-url: "https://thethings.example.com/api/v3"
     as:
       base-url: "https://thethings.example.com/api/v3"
     js:
       base-url: "https://thethings.example.com/api/v3"
+    gcs:
+      base-url: "https://thethings.example.com/api/v3"
     qrg:
       base-url: "https://thethings.example.com/api/v3"
     edtc:
@@ -139,24 +140,20 @@ as:
     downlink:
       public-address: "thethings.example.com:1885/api/v3"
 
-# If Device Claiming Server enabled, defaults for "thethings.example.com":
-dcs:
-  oauth:
-    authorize-url: "https://thethings.example.com/oauth/authorize"
-    token-url: "https://thethings.example.com/oauth/token"
-    logout-url: "https://thethings.example.com/oauth/logout"
-    client-id: "device-claiming"
-    client-secret: "device-claiming" # choose or generate a secret
-  ui:
-    canonical-url: "https://thethings.example.com/claim"
-    as:
-      base-url: "https://thethings.example.com/api/v3"
-    dcs:
-      base-url: "https://thethings.example.com/api/v3"
-    is:
-      base-url: "https://thethings.example.com/api/v3"
-    ns:
-      base-url: "https://thethings.example.com/api/v3"
+# Managed gateway configuration, defaults for "thethings.example.com".
+# This configures a connection with The Things Gateway Controller, a service operated by The Things Industries.
+# This allows connecting, for example, The Things Indoor Gateway Pro.
+ttgc:
+  enabled: true
+  domain: thethings.example.com
+  # Let's Encrypt
+  tls:
+    source: acme
+  # If using custom certificates:
+  # tls:
+  #   source: file
+  #   certificate: /run/secrets/cert.pem
+  #   key: /run/secrets/key.pem
 
 # If Network Operations Center is enabled, defaults for "thethings.example.com":
 noc: