Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      The Things Stack Enterprise

      • Overview
      • AWS
      • Kubernetes
      • Docker
        • Configuration
        • Certificates
        • Running The Things Stack
        • Proxy
        • Troubleshooting Installation
        • Upgrading The Things Stack
        • Balena
      • The Things Join Server
      • Manage The Things Stack

      Certificates

      Updated 4 March 2025 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      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.

      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.

      If you are deploying using ACME, move to the Automatic Certificate Management section.

      If you already have CA certificates, move to the 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 section.

      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!

      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.

      Create a ca.json file and write the following configuration to it:

      {
        "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.

      Using Custom Certificates

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

      67
      68
      69
      70
      71
      72
      73
      74
      75
      76
      77
      78
      79
      80
      
          # 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:

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

      And uncomment the custom certificates section:

      41
      42
      43
      44
      45
      46
      
      # If using custom certificates:
      tls:
        source: file
        root-ca: /run/secrets/ca.pem
        certificate: /run/secrets/cert.pem
        key: /run/secrets/key.pem

      In order to use the certificate (cert.pem) and key (key.pem), 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
      

      Make sure you have configured docker-compose.yml and ttn-lw-stack-docker.yml for your custom certificates, as shown in using custom certificates.

      Now that the permissions have been set you can move on to run The Things Stack!

      ← Configuration Running The Things Stack →

      On this page

      • Automatic Certificate Management
      • Custom Certificate Authority
      • Using Custom Certificates

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories