Docker

This is a guide for installing The Things Stack Enterprise or Open Source on your own hardware using Docker, to run your own private LoRaWAN® network server.

There are several ways to run The Things Stack.

The Things Stack Open Source and Enterprise distributions are designed to run on your own hardware, which this guide covers.

Alternatively, to use The Things Stack in the cloud without installing it on your own hardware, see The Things Stack Cloud (our professional, SLA-backed offering) or The Things Stack Sandbox (our free-to-use The Things Stack Sandbox). To spin up your own EC2 instance, there is also an AWS Launcher. To install using balenaCloud on a Rasperry Pi, see the Balena section.

For highly available production cloud deployments with high throughput, we recommend using The Things Stack Cloud or AWS Launcher. All deployments of The Things Stack except Open Source and AWS Launcher support multi-tenancy, which allows you to create multiple private network servers within a single deployment, for example to resell to individual clients.

Continue following these instructions to run The Things Stack Enterprise or Open Source on your own hardware, using Docker.

In addition to the following written instructions, video instructions for installing The Things Stack are available on The Things Network youtube channel.

Show video

Prerequisites

  1. A server with a recommended 4 virtual CPUs and 16GB RAM running Docker and Docker Compose*
  2. DNS records pointing to your server’s IP address (skip if using localhost)
  3. A license for The Things Stack (only for Enterprise)

*Benchmark for 100K devices with 12 confirmed uplinks per day. Your requirements will vary depending on your load and desired redundancy.

If purchasing an Enterprise license, consider setting up a multi-tenant environment from the beginning if you plan to add tenants later. Switching from a a single-tenant to multi-tenant environment requires database migration.

For multi-tenant deployments, DNS records for *.domain need to be created in addition to the plain domain record. For offline deployments, internal DNS pointing to your server’s IP address can be used, and The Things Industries can provide a license for that domain name.

This guide shows you how to get everything up and running on a server. If you are comfortable with configuring servers and working with command line, this is the perfect place to start, but first, follow the guides to install Docker, to install Docker Compose, and to configure permissions for Docker Engine.

Next, see instructions on how to configure, set up certificates and finally run The Things Stack!

Configuration

This guide shows an example of configuring The Things Stack using configuration files, with an example domain thethings.example.com and TLS certificates from Let’s Encrypt. If configuring The Things Stack as localhost on a machine with no public IP or DNS address, see the localhost section. In addition to the written instructions below, video instructions for installing The Things Stack are available on The Things Network youtube channel. Show video Configuration Files The Things Stack requires two configuration files when installing with Docker: docker-compose.yml and ttn-lw-stack-docker.yml. The files are provided below:
Read

Certificates

The Things Stack has built in support for Transport Layer Security (TLS) and HTTPS. This requires a TLS certificate and a corresponding key. For using The Things Stack behind an external proxy that can terminate TLS see the proxy section.
Read

Running The Things Stack

Now that all configuration is done, you are ready to initialize The Things Stack and start it! Begin by opening a terminal prompt in the same directory as your docker-compose.yml file. Initialization The first time The Things Stack is started, it requires some initialization. Start by pulling the Docker images: docker compose pull Next, you need to initialize the database of the Identity Server: docker compose run --rm stack is-db migrate If you receive a permissions error, ensure you have correctly configured permissions for Docker Engine.
Read

Proxy

The Things Stack can work with an external proxy that can terminate TLS connections.
Read

Troubleshooting Installation

This section contains help for common issues you may encounter while installing The Things Stack. 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 for more information about the configuration options. Version in “docker-compose.yml” is unsupported Our docker-compose.yml file uses Compose file version 3.7. If using a package manager to install Docker Compose, it is possible to install an old, unsupported version. See Docker’s installation instructions to upgrade to a more recent version.
Read

Upgrading The Things Stack

This section contains instructions to upgrade a The Things Stack Enterprise or Open Source deployment.
Read

Balena

The Things Stack Open Source can also be installed on a Raspberry Pi 3 or 4 running balena. To run The Things Stack you need to deploy it to a balenaCloud fleet. This can be done by by clicking the button below: First, follow the instructions in your balenaCloud dashboard and click Create and deploy. Then, click Add device and configure the balenaOS file by filling in the presented form. Click Download balenaOS to download the resulting OS file and flash it to an SD card. Insert the SD card into your Raspberry Pi, connect it to the Internet and power it up. Enjoy the magic 🌟Over-The-Air🌟!
Read
← Azure Configuration →