Restructure documentation (#1394)

* doc: Move cloud section to top * doc: Update TTS Cloud clusters page * doc: Add enterprise cluster selector * doc: Move billing docs * doc: Move alerting * doc: Move console * doc: Update data formats * doc: Update cloud mainpage * doc: Update LoRaWAN support page * doc: Move CLI * doc: Move more topics to concepts * doc: Move enterprise items * doc: Move user management * doc: Move PacketBroker * doc: Update migration documentation * doc: Update docker * doc: Update AWS * doc: Move kubernetes * doc: Remove host section * doc: Update integrations section * doc: Update gateways * doc: Move components * doc: Move configuration * doc: Move reference topics to appropriate sections * doc: Move end devices * doc: Update features pages * doc: Update events * doc: Update NOC content * docs: Release 3.32.3 (#1392) * doc: Move migration under concepts * doc: Fix comments --------- Co-authored-by: The Things Bot <36884541+TheThingsBot@users.noreply.github.com>
TheThingsIndustries · Jan 20, 2025 · ab36344 · ab36344
1 parent 6fea088
commit ab36344
Show file tree

Hide file tree

Showing 973 changed files with 3,125 additions and 3,768 deletions.
diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md
@@ -1,7 +1,6 @@
 ---
 name: Release
 about: Checklist for releases
-
 ---
 
 <!--
@@ -12,15 +11,14 @@ Please check items along as you follow the release process.
 
 This is a checklist for releases. This is filled in by both the releaser and the reviewer where necessary.
 
-
 #### Update Documentation
 
 - [ ] Create a new release in the [`whats-new` section](https://github.com/TheThingsIndustries/lorawan-stack-docs/tree/master/doc/content/whats-new) and copy the release CHANGELOG from [TheThingsIndustries/lorawan-stack](https://github.com/TheThingsIndustries/lorawan-stack). The title is the release version and the date is the release date.
-- [ ] Copy the contents of the latest UPGRADING.md from the [lorawan-stack-aws](https://github.com/TheThingsIndustries/lorawan-stack-aws) to [/the-things-stack/host/aws/ecs/changelog](https://github.com/TheThingsIndustries/lorawan-stack-docs/tree/master/doc/content/the-things-stack/host/aws/ecs/changelog/index.md)
+- [ ] Copy the contents of the latest UPGRADING.md from the [lorawan-stack-aws](https://github.com/TheThingsIndustries/lorawan-stack-aws) to [/enterprise/aws/ecs/changelog](https://github.com/TheThingsIndustries/lorawan-stack-docs/tree/master/doc/content/enterprise/aws/ecs/changelog/index.md)
 - [ ] Remove empty sections from the created release file.
 - [ ] Update the [documentation version](https://github.com/TheThingsIndustries/lorawan-stack-docs/blob/master/doc/config/_default/config.toml#L28) to match the current PATCH, if necessary (`3.${minor}.${patch}`). Note that this previously included a "v" prefix and only included a minor, but the patch must be included or repository and CLI links will break, and no "v" should be prefixed.
 - [ ] To generate documentation, create a clone of [TheThingsIndustries/lorawan-stack](https://github.com/TheThingsIndustries/lorawan-stack), and **checkout the git tag of the release**.
-- [ ] To generate API documentation, run the following from within the clone of [TheThingsIndustries/lorawan-stack](https://github.com/TheThingsIndustries/lorawan-stack): 
+- [ ] To generate API documentation, run the following from within the clone of [TheThingsIndustries/lorawan-stack](https://github.com/TheThingsIndustries/lorawan-stack):
 
 ```bash
 $ tools/bin/mage ttiProto:hugoData
@@ -68,7 +66,7 @@ $ rm ../lorawan-stack-docs/doc/content/ttn-lw-cli/ttn-lw-cli_end-devices.md.bak
 #### Check (for reviewers)
 
 - [ ] A new section has been created in [`whats-new`](doc/content/whats-new) with the corresponding CHANGELOG from [TheThingsIndustries/lorawan-stack](https://github.com/TheThingsIndustries/lorawan-stack). The title is the release version and the date is the release date.
-- [ ] The latest UPGRADING.md from the [lorawan-stack-aws](https://github.com/TheThingsIndustries/lorawan-stack-aws) has been copied to [/the-things-stack/host/aws/ecs/changelog](https://github.com/TheThingsIndustries/lorawan-stack-docs/tree/master/doc/content/the-things-stack/host/aws/ecs/changelog/index.md)
+- [ ] The latest UPGRADING.md from the [lorawan-stack-aws](https://github.com/TheThingsIndustries/lorawan-stack-aws) has been copied to [/enterprise/aws/ecs/changelog](https://github.com/TheThingsIndustries/lorawan-stack-docs/tree/master/doc/content/enterprise/aws/ecs/changelog/index.md)
 - [ ] The documentation version is up to date with the latest PATCH (`3.${minor}.${patch}`). No "v" is prefixed.
 - [ ] The TTI and TTN API documentation has been generated and updated in [doc/data/api](https://github.com/TheThingsIndustries/lorawan-stack-docs/blob/master/doc/data/api). This includes the following files:
 

diff --git a/CODEOWNERS b/CODEOWNERS
@@ -17,33 +17,32 @@
 /doc/content/integrations/payload-formatters @vlasebian @KrishnaIyer
 
 # Subject matter experts
-/doc/content/the-things-stack/interact/cli @KrishnaIyer
-/doc/content/the-things-stack/interact/console @ryaplots @KrishnaIyer
-/doc/content/the-things-stack/host/docker @KrishnaIyer
-/doc/content/the-things-stack/host/aws @KrishnaIyer @johanstokking @happyRip
-/doc/content/the-things-stack/migrating @happyRip @KrishnaIyer
-/doc/content/the-things-stack/cloud @happyRip @KrishnaIyer
-/doc/content/the-things-stack/management/events @johanstokking @KrishnaIyer
+/doc/content/concepts/features/cli @KrishnaIyer
+/doc/content/concepts/console @ryaplots @KrishnaIyer
+/doc/content/enterprise/docker @KrishnaIyer
+/doc/content/enterprise/aws @KrishnaIyer @johanstokking @happyRip
+/doc/content/migration @happyRip @KrishnaIyer
+/doc/content/cloud @happyRip @KrishnaIyer
+/doc/content/concepts/features/events @johanstokking @KrishnaIyer
 
 /doc/content/api @KrishnaIyer @johanstokking
-/doc/content/reference/configuration @johanstokking @KrishnaIyer
-/doc/content/the-things-stack/management/branding @ryaplots @KrishnaIyer
-/doc/content/reference/email-templates @nicholaspcr @KrishnaIyer
+/doc/content/enterprise/management/configuration @johanstokking @KrishnaIyer
+/doc/content/cloud/branding @ryaplots @KrishnaIyer
 /doc/content/reference/federated-auth @nicholaspcr @KrishnaIyer
-/doc/content/reference/frequency-plans @halimi @KrishnaIyer
-/doc/content/reference/interop-repository @johanstokking @halimi @KrishnaIyer
-/doc/content/the-things-stack/concepts/networking @KrishnaIyer
-/doc/content/reference/root-certificates @KrishnaIyer
+/doc/content/concepts/features/lorawan/frequency-plans @halimi @KrishnaIyer
+/doc/content/enterprise/join-server/interop-configuration @johanstokking @halimi @KrishnaIyer
+/doc/content/concepts/networking @KrishnaIyer
+/doc/content/concepts/advanced/root-certificates @KrishnaIyer
 /doc/content/reference/stripe @mjamescompton @KrishnaIyer
 
 # Reference components
-/doc/reference/components/application-server @johanstokking @vlasebian @KrishnaIyer
-/doc/reference/components/gateway-configuration-server @KrishnaIyer @nicholaspcr
-/doc/reference/components/gateway-server @johanstokking @vlasebian @KrishnaIyer
-/doc/reference/components/identity-server @nicholaspcr @ryaplots
-/doc/reference/components/join-server @johanstokking @ryaplots @KrishnaIyer
-/doc/reference/components/network-server @johanstokking @halimi @KrishnaIyer
-/doc/reference/components/packet-broker-agent @johanstokking @vlasebian @KrishnaIyer
+/doc/concepts/architecture/components/application-server @johanstokking @vlasebian @KrishnaIyer
+/doc/concepts/architecture/components/gateway-configuration-server @KrishnaIyer @nicholaspcr
+/doc/concepts/architecture/components/gateway-server @johanstokking @vlasebian @KrishnaIyer
+/doc/concepts/architecture/components/identity-server @nicholaspcr @ryaplots
+/doc/concepts/architecture/components/join-server @johanstokking @ryaplots @KrishnaIyer
+/doc/concepts/architecture/components/network-server @johanstokking @halimi @KrishnaIyer
+/doc/concepts/architecture/components/packet-broker-agent @johanstokking @vlasebian @KrishnaIyer
 
 # Clear generated code
 /doc/data/api/*/*.yml
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -91,7 +91,7 @@ Mark documentation that applies only to a specific distribution in one of the fo
 
 - Use the Front Matter `distributions` element to add a list of distributions, i.e `distribution: ["Enterprise", "Cloud"]`. This will mark the page in the parent's table of contents, and will produce a notification on the page
 - Use the `{{< distributions "Enterprise" "Cloud" >}}` shortcode to produce a notification on the page
-- Note that you should not use the `{{< distributions >}}`,  `{{< new-in-version >}}`, or `{{< deprecated-in-version >}}` shortcodes in a heading, as Hugo will not correctly generate the ID element for it. Put it at the beginning of the paragraph below.
+- Note that you should not use the `{{< distributions >}}`, `{{< new-in-version >}}`, or `{{< deprecated-in-version >}}` shortcodes in a heading, as Hugo will not correctly generate the ID element for it. Put it at the beginning of the paragraph below.
 
 ## Style Guidelines
 
@@ -126,15 +126,15 @@ Please respect the following guidelines for content in our documentation site.
   - Wrap large CLI output with `<details><summary>Show CLI output</summary> ... output here ... </details>`.
   - `yaml` (not `yml`) for YAML. Wrap strings with single quotes `''` (because of frequent Go templates that use double quotes).
 - For variables which a user must replace, use a command to define the variable in the shell, if possible, e.g `API_KEY="your-api-key"`.
-- If not possible to define the variable, use angle brackets to indicate a variable that needs to be replaced, e.g `https://<server-address>`. 
+- If not possible to define the variable, use angle brackets to indicate a variable that needs to be replaced, e.g `https://<server-address>`.
 - In long command line examples or other code snippets, use the following guidelines:
   - If a line is longer than 80 columns, try to find a "natural" break
   - If a line is longer than 120 columns, insert a line break
   - In very special cases, longer lines are tolerated
 
 ## Building Frequency Plans Documentation
 
-The [Frequency Plans](https://github.com/TheThingsIndustries/lorawan-stack-docs/blob/master/doc/content/reference/frequency-plans/_index.md) section contains all frequency plans that are officially supported by {{% tts %}}. The list of frequency plans is populated from the [LoRaWAN Frequency Plans for {{% tts %}} Github repository](https://github.com/TheThingsNetwork/lorawan-frequency-plans/). To update the list of frequency plans with the newest changes from the Frequency Plans repository, run `make freq.deps`.
+The [Frequency Plans](https://github.com/TheThingsIndustries/lorawan-stack-docs/blob/master/doc/content/concepts/features/lorawan/frequency-plans/_index.md) section contains all frequency plans that are officially supported by {{% tts %}}. The list of frequency plans is populated from the [LoRaWAN Frequency Plans for {{% tts %}} Github repository](https://github.com/TheThingsNetwork/lorawan-frequency-plans/). To update the list of frequency plans with the newest changes from the Frequency Plans repository, run `make freq.deps`.
 
 ## Legal
 

diff --git a/doc/archetypes/section-bundle/_index.md b/doc/archetypes/section-bundle/_index.md
@@ -28,8 +28,8 @@ For example:
 <div class="fixed-table table-name">
 
 | Header 1 | Header 2 |
-|---|---|
-| Col 1 | Col 2 |
+| -------- | -------- |
+| Col 1    | Col 2    |
 
 </div>
 
@@ -79,7 +79,7 @@ For an inline tag, use the `{{< new-in-version "3.8.5" >}}` shortcode to tag doc
 
 For an inline tag, use the `{{< deprecated-in-version "3.8.5" >}}` shortcode.
 
-You may additionally provide information using the `{{< warning >}}` shortcode, e.g {{< warning "This feature will be removed in January 5, 2021 for Cloud deployments" >}} 
+You may additionally provide information using the `{{< warning >}}` shortcode, e.g {{< warning "This feature will be removed in January 5, 2021 for Cloud deployments" >}}
 
 ## Sections
 
@@ -100,6 +100,7 @@ There is no need to add the word "note" at the beginning of a note, or "warning"
 ## Images
 
 Taking screenshots is done as follows:
+
 - In Chrome: activate the Developer Tools and toggle the Device Toolbar. In the Device Toolbar, select Laptop with HiDPI screen (add it if not already there), and click Capture Screenshot in the menu on the right.
 - In Firefox: enter Responsive Design Mode. In the Device Toolbar, select "Laptop with HiDPI screen" (add it if not already there) and Take a screenshot of the viewport.
 
@@ -118,7 +119,9 @@ To separate instructions for the console and CLI, use the `tabs/container` short
 {{< tabs/container "Console" "CLI" >}}
 
 {{< tabs/tab "Console" >}}
+
 ## These are console instructions
+
 {{< /tabs/tab >}}
 
 {{< tabs/tab "CLI" >}}
@@ -144,7 +147,7 @@ $ SECRET=$(echo $LNS_KEY | xxd -p -u | perl -pe 's/\n//')
 $ ttn-lw-cli gateways update $GTW_ID --lbs-lns-secret.value $SECRET
 ```
 
-If not possible to define the variable, use angle brackets to indicate a variable that needs to be replaced, e.g `https://<server-address>`. 
+If not possible to define the variable, use angle brackets to indicate a variable that needs to be replaced, e.g `https://<server-address>`.
 
 ## Syntax Highlighting
 
@@ -182,7 +185,7 @@ SOME_ENV="value"
 # file: yaml-file.yml
 services:
   stack:
-    image: 'thethingsnetwork/lorawan-stack:<the tag>'
+    image: "thethingsnetwork/lorawan-stack:<the tag>"
 ```
 
 ### Line Breaks
@@ -213,5 +216,5 @@ $ curl --location --header 'Authorization: Bearer NNSXS.XXXXXXXXX' --header 'Acc
 It is also possible to host source code (or any text file) and display it using shortcodes. For example:
 
 {{< highlight yaml "linenos=table,linenostart=5" >}}
-{{< readfile path="/content/the-things-stack/host/docker/configuration/docker-compose-enterprise.yml" from=5 to=14 >}}
+{{< readfile path="/content/enterprise/docker/configuration/docker-compose-enterprise.yml" from=5 to=14 >}}
 {{< /highlight >}}
diff --git a/doc/archetypes/section-bundle/troubleshooting.md b/doc/archetypes/section-bundle/troubleshooting.md
@@ -15,7 +15,7 @@ Title the troubleshooting page "Troubleshooting <name_of_section>", so that it i
 
 ## Component address is not included in this license
 
-Ensure that you configure the `is.oauth.ui.canonical-url` with a domain that matches the domain in your license. See the [Configuration Reference]({{< ref src="/reference/configuration" >}}) for more information about the configuration options.
+Ensure that you configure the `is.oauth.ui.canonical-url` with a domain that matches the domain in your license. See the [Configuration Reference]({{< ref src="/enterprise/management/configuration" >}}) for more information about the configuration options.
 
 ## Version in "docker-compose.yml" is unsupported
 

diff --git a/doc/content/api/_index.md b/doc/content/api/_index.md
@@ -1,8 +1,7 @@
 ---
 title: "API"
 description: ""
-aliases:
-  ["/api/reference/grpc", "/the-things-stack/interact/api/", "/reference/api"]
+aliases: ["/api/reference/grpc", "/concepts/featuresapi/", "/reference/api"]
 weight: 7
 menu:
   main:

diff --git a/doc/content/api/concepts/auth/oauth-access-tokens/_index.md b/doc/content/api/concepts/auth/oauth-access-tokens/_index.md
@@ -2,13 +2,12 @@
 title: "OAuth access tokens"
 description: ""
 weight: 1
-aliases:
-  [ /api/concepts/auth/oauth-access-tokens ]
+aliases: [/api/concepts/auth/oauth-access-tokens]
 ---
 
 <!--more-->
 
-To use this authentication method, you first need to [register an **OAuth client**]({{<ref "/the-things-stack/interact/adding-oauth-clients">}}) . After the registration is complete and accepted, you can **request authorization** by sending the user to the **authorization URL**:
+To use this authentication method, you first need to [register an **OAuth client**]({{<ref "/concepts/advanced/adding-oauth-clients">}}) . After the registration is complete and accepted, you can **request authorization** by sending the user to the **authorization URL**:
 
 ```
 https://<HOSTNAME>/oauth/authorize?client_id=<CLIENT-ID>&redirect_uri=<REDIRECT-URI>&state=<STATE>&response_type=code

diff --git a/doc/content/api/concepts/errors/_index.md b/doc/content/api/concepts/errors/_index.md
@@ -53,7 +53,7 @@ Fields of the JSON message are described below.
 
 ## Rate limiting
 
-API request may be subject to [rate limits]({{< ref "/reference/rate-limiting" >}}).
+API request may be subject to [rate limits]({{< ref "/enterprise/management/rate-limiting" >}}).
 
 When the rate limit is reached, the server returns a `429 Too Many Requests` response.
 

diff --git a/doc/content/api/concepts/fieldmasks/_index.md b/doc/content/api/concepts/fieldmasks/_index.md
@@ -97,7 +97,7 @@ Without the field masks specified, this request would not return the `name`, `de
 
 {{< note >}} Keep in mind that application ID (`application_ids.application_id`), end device ID (`device_id`), AppEUI/JoinEUI (`join_eui`), DevEUI (`dev_eui`) and API key IDs cannot be updated after creation. These fields are part of the allowed field mask, but they can only be used at creation, after which they can no longer be changed.
 
-For example, to properly register an end device in {{% tts %}} like described in the [devices]({{< ref "/devices/adding-devices/manual" >}}) section, it is necessary to set the `dev_eui` field to device's DevEUI. However, updating the DevEUI after device is created will not be possible, i.e. will fail with the `forbidden path(s) in field mask` error. {{</ note >}}
+For example, to properly register an end device in {{% tts %}} like described in the [devices]({{< ref "/hardware/devices/adding-devices/manual" >}}) section, it is necessary to set the `dev_eui` field to device's DevEUI. However, updating the DevEUI after device is created will not be possible, i.e. will fail with the `forbidden path(s) in field mask` error. {{</ note >}}
 
 To update fields, the field mask must also be specified in the JSON object (query parameters do not work for `PUT` requests). The field mask has the following format:
 

diff --git a/doc/content/api/concepts/lora-gateway/_index.md b/doc/content/api/concepts/lora-gateway/_index.md
@@ -9,17 +9,17 @@ aliases: ["/reference/api/gateway_server_mqtt"]
 
 <!--more-->
 
-See the [port allocations]({{< ref "/the-things-stack/concepts/networking/#port-allocations" >}}) guide to check which protocol is supported on which port.
+See the [port allocations]({{< ref "/concepts/networking/#port-allocations" >}}) guide to check which protocol is supported on which port.
 
 ## LoRa Basics™ Station
 
-{{% tts %}} provides {{% lbs %}} [LNS]({{< ref "/gateways/concepts/lora-basics-station/#lorawan-network-server-lns" >}}) and [CUPS]({{< ref "/gateways/concepts/lora-basics-station/#configuration-and-update-server-cups" >}}) end points for gateways to connect.
+{{% tts %}} provides {{% lbs %}} [LNS]({{< ref "/hardware/gateways/concepts/lora-basics-station/#lorawan-network-server-lns" >}}) and [CUPS]({{< ref "/hardware/gateways/concepts/lora-basics-station/#configuration-and-update-server-cups" >}}) end points for gateways to connect.
 
 These protocols follow the {{% lbs %}} [reference specification](https://lora-developers.semtech.com/build/software/lora-basics/lora-basics-for-gateways/?url=cupsproto.html).
 
 {{< note "{{% lbs %}} CUPS API is usually exposed on the HTTP(s) port(s)." />}}
 
-Implementation specific details for clients using the {{% lbs %}} LNS protocol to communicate with {{% tts %}} is documented in the [LoRa Basics Station Implementation Guide]({{< ref "/reference/lbs" >}}).
+Implementation specific details for clients using the {{% lbs %}} LNS protocol to communicate with {{% tts %}} is documented in the [LoRa Basics Station Implementation Guide]({{< ref "/hardware/gateways/concepts/lora-basics-station/implementation-guide" >}}).
 
 This reference describes the MQTT protocol used by the Gateway Server. Packet forwarders implementing the MQTT protocols are specific for {{% tts %}}.
 
@@ -37,13 +37,13 @@ To communicate with the MQTT protocol, the Gateway Server and the gateway are ex
 
 ### MQTT v2
 
-The MQTT v2 gateway APIs are used by [The Things Kickstarter Gateway]({{< ref "/gateways/models/thethingskickstartergateway">}}) and use the [TTN v2 MQTT](https://github.com/TheThingsNetwork/lorawan-stack/blob/master/pkg/gatewayserver/io/mqtt/format_protobufv2.go) format.
+The MQTT v2 gateway APIs are used by [The Things Kickstarter Gateway]({{< ref "/hardware/gateways/models/thethingskickstartergateway">}}) and use the [TTN v2 MQTT](https://github.com/TheThingsNetwork/lorawan-stack/blob/master/pkg/gatewayserver/io/mqtt/format_protobufv2.go) format.
 
 ### MQTT v3
 
 The MQTT v3 protocol uses the {{% tts %}} v3 messages definitions.
 
-Gateways can connect using the username `{gateway-id}@{tenant-id}` and an API key as the password. Check how to [register a gateway and create an API key]({{< ref "/gateways/concepts/adding-gateways/">}}).
+Gateways can connect using the username `{gateway-id}@{tenant-id}` and an API key as the password. Check how to [register a gateway and create an API key]({{< ref "/hardware/gateways/concepts/adding-gateways/">}}).
 
 <div class="fixed-table table-api">
 
@@ -58,9 +58,9 @@ Gateways can connect using the username `{gateway-id}@{tenant-id}` and an API ke
 
 #### Connecting to the Gateway Server
 
-See [Networking]({{< ref "/the-things-stack/concepts/networking" >}}) for the default port of the MQTT server.
+See [Networking]({{< ref "/concepts/networking" >}}) for the default port of the MQTT server.
 
-The username is `<gateway-id>@<tenant-id>` (e.g. `gtw1@tenant1`), and the password is a gateway API key with the `RIGHT_GATEWAY_LINK` right enabled. You can generate this API key by following instructions in the [Creating Gateways]({{< ref "/gateways/concepts/adding-gateways#create-gateway-api-key" >}}) section.
+The username is `<gateway-id>@<tenant-id>` (e.g. `gtw1@tenant1`), and the password is a gateway API key with the `RIGHT_GATEWAY_LINK` right enabled. You can generate this API key by following instructions in the [Creating Gateways]({{< ref "/hardware/gateways/concepts/adding-gateways#create-gateway-api-key" >}}) section.
 
 Authenticated clients get **write-only** access to the following topics: