v3.24.1

Getting Started Devices Gateways Integrations Reference
Get The Things Stack

Getting Started

    Overview
  • Quick Start
  • What Is The Things Stack?
  • Console
  • Subscription and Billing Management
  • Command-line Interface
  • Installing The Things Stack
    • Configuration
    • Certificates
    • Running The Things Stack
    • Troubleshooting Installation
    • Balena
  • Upgrading The Things Stack
  • Migrating to The Things Stack
  • The Things Stack Cloud
  • The Things Stack AWS Launcher
  • The Things Stack on Kubernetes
  • The Things Join Server
  • The Things Network
  • Server Addresses
  • Packet Broker
  • Single Sign-On
  • Users and Organizations
  • Using the API
  • Working with Events
  • Troubleshooting Getting Started

Certificates

The Things Stack needs to be configured with Transport Layer Security (TLS) and HTTPS. This requires a TLS certificate and a corresponding key.

In this guide, we request a free, trusted certificate from Let’s Encrypt, 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.

Automatic Certificate Management

The Things Stack can be configured to automatically retrieve and update Let’s Encrypt certificates. Assuming you followed the configuration steps, create an acme directory where The Things Stack can store the certificate data:

mkdir ./acme
sudo chown 886:886 ./acme
Warning:
886 is the UID and the GID of the user that runs The Things Stack in the Docker container. If you don’t set these permissions, you may encounter an error resembling open /var/lib/acme/acme_account+key<...>: permission denied.

The directory hierarchy should look like this:

acme/
docker-compose.yml          # defines Docker services for running The Things Stack
config/
└── stack/
    └── ttn-lw-stack-docker.yml    # configuration file for The Things Stack

If you are using Let’s Encrypt in a multi-tenant The Things Stack environment, make sure you specify all tenant addresses in the TLS configuration of ttn-lw-stack-docker.yml. Read more in the TLS section.

Certificates will automatically be requested the first time you access The Things Stack. You will notice that the page takes some time to load while certificates are obtained in the background.

Once you have created the acme folder and given it appropriate permissions, move on to run The Things Stack!

Using Custom Certificates

To use CA certificates you already have or self-signed certificates, you will need to uncomment the custom certificates section of docker-compose.yml:

66
67
68
69
70
71
72
73
74
75
76
77
78
79
    # If using custom certificates:
    secrets:
      - ca.pem
      - cert.pem
      - key.pem

# If using custom certificates:
secrets:
  ca.pem:
    file: ./ca.pem
  cert.pem:
    file: ./cert.pem
  key.pem:
    file: ./key.pem

You will also need to comment out the Let’s Encrypt section of ttn-lw-stack-docker.yml, and uncomment the custom certificates section:

48
49
50
51
52
53
54
55
# Let's encrypt for "thethings.example.com"
# tls:
#   source: 'acme'
#   acme:
#     dir: '/var/lib/acme'
#     email: 'you@thethings.example.com'
#     hosts: ['thethings.example.com']
#     default-host: 'thethings.example.com'

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.

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.

The directory hierarchy should look like this:

cert.pem
key.pem
docker-compose.yml          # defines Docker services for running The Things Stack
config/
└── stack/
    └── ttn-lw-stack-docker.yml    # configuration file for The Things Stack

Be sure to configure docker-compose.yml and ttn-lw-stack-docker.yml for your custom certificates, as shown in 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.

Write the configuration for your CA to ca.json:

{
  "names": [
    {"C": "NL", "ST": "Noord-Holland", "L": "Amsterdam", "O": "The Things Demo"}
  ]
}

Then use the following command to generate the CA key and certificate:

cfssl genkey -initca ca.json | cfssljson -bare ca

Now write the configuration for your certificate to cert.json:

{
  "hosts": ["thethings.example.com"],
  "names": [
    {"C": "NL", "ST": "Noord-Holland", "L": "Amsterdam", "O": "The Things Demo"}
  ]
}
Note:
Remember to replace thethings.example.com with your server address!

Then, run the following command to generate the server key and certificate:

cfssl gencert -ca ca.pem -ca-key ca-key.pem cert.json | cfssljson -bare cert

The next steps assume the certificate key is called key.pem, so you’ll need to rename cert-key.pem to key.pem.

At the end, your directory should look like this:

cert.pem
key.pem
ca.pem
docker-compose.yml          # defines Docker services for running The Things Stack
config/
└── stack/
    └── ttn-lw-stack-docker.yml    # configuration file for The Things Stack

Be sure to configure docker-compose.yml and ttn-lw-stack-docker.yml for your custom certificates, as shown in using custom certificates.

← Configuration Running The Things Stack →

On this page

  • Automatic Certificate Management
  • Custom Certificate Authority

The Things Stack

Getting Started

Devices

Gateways

Integrations

Reference

Contributing

GitHub

Forum

About Us

The Things Network

The Things Industries

About this page

Last changed by Ben Olayinka on 08 Mar 2023.
doc: Refactor installation guide (#1062)

Edit on Github