Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
Merge pull request #1481 from TheThingsNetwork/feature/config-reference
Configuration Reference starting point
- Loading branch information
Showing
12 changed files
with
272 additions
and
57 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
--- | ||
title: "Configuration" | ||
description: "" | ||
weight: 2 | ||
--- | ||
|
||
The Things Stack binary can be configured with many different options. Those options can be provided as command-line flags, environment variables or using a configuration file. | ||
|
||
<!--more--> | ||
|
||
## Configuration Sources | ||
|
||
In this reference we will refer to configuration options by name. On this page we will show how the `console.ui.canonical-url` option can be configured. | ||
|
||
### Command-line flags | ||
|
||
Command-line flags have the highest priority and, as such, override other means of configuration (environment variable or file). This looks as follows: | ||
|
||
```bash | ||
$ ttn-lw-stack start console --console.ui.canonical-url "https://thethings.example.com/console" | ||
``` | ||
|
||
### Environment variables | ||
|
||
Environment variables for configuration options are very similar to the command-line flags, except that they are in uppercase, and all separators (`.` or `-`) are replaced by underscores (`_`). Environment variables are also prefixed with `TTN_LW_`. | ||
|
||
> In many cases you'll want to use a `.env` file that is loaded using the [`dotenv` command of direnv](https://direnv.net/man/direnv-stdlib.1.html) or the [`env_file` option of Docker Compose](https://docs.docker.com/compose/compose-file/#env_file). You can also `export` each environment variable, or run `export $(grep -v '^#' .env | xargs)` to export all variables in the `.env` file. | ||
The option from the command-line example from above would look as follows with environment variables: | ||
|
||
```bash | ||
TTN_LW_CONSOLE_UI_CANONICAL_URL="https://thethings.example.com/console" | ||
``` | ||
|
||
### Configuration files | ||
|
||
You can also configure The Things Stack with a YAML configuration file. This is again similar to the command-line flags, except that each `.` represents a YAML node. This allows you to group related options together: | ||
|
||
```yaml | ||
console: | ||
ui: | ||
canonical-url: 'https://thethings.example.com/console' | ||
# other console UI options | ||
# other console options | ||
``` | ||
|
||
You can specify the location of the YAML configuration file with the command-line flag `-c` or `--config`. If this flag is not present, The Things Stack will look for config files in the following locations: | ||
|
||
- The current directory | ||
- The user's home directory (as [determined by Go](https://golang.org/pkg/os/#UserHomeDir)) | ||
- The user's config directory (as [determined by Go](https://golang.org/pkg/os/#UserConfigDir)) | ||
|
||
You can run The Things Stack with the `--help` flag, and check the description of the `--config` flag for the exact locations that are being checked. | ||
|
||
### Defaults | ||
|
||
The Things Stack can be used for local testing purposes without any custom configuration. | ||
|
||
## Printing the Current Configuration | ||
|
||
You can see the current configuration with the `config` command of `ttn-lw-stack` or `ttn-lw-cli`. By default this will print the configuration as CLI flags. Use the `--env` or `--yml` flags to print the configuration as environment variables or as YAML. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: "Application Server Options" | ||
description: "" | ||
weight: 5 | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: "Console Options" | ||
description: "" | ||
weight: 7 | ||
--- |
5 changes: 5 additions & 0 deletions
5
doc/content/reference/configuration/gateway-configuration-server.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: "Gateway Configuration Server Options" | ||
description: "" | ||
weight: 8 | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: "Gateway Server Options" | ||
description: "" | ||
weight: 3 | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: "Identity Server Options" | ||
description: "" | ||
weight: 2 | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: "Join Server Options" | ||
description: "" | ||
weight: 6 | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
title: "Network Server Options" | ||
description: "" | ||
weight: 4 | ||
--- |
174 changes: 174 additions & 0 deletions
174
doc/content/reference/configuration/the-things-stack.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,174 @@ | ||
--- | ||
title: "Generic Server Options" | ||
description: "" | ||
weight: 1 | ||
--- | ||
|
||
## Global Options | ||
|
||
Under normal circumstances, only `info`, `warn` and `error` logs are printed to the console. For development, you may also want to see `debug` logs. | ||
|
||
- `log.level`: The minimum level log messages must have to be shown (default "info") | ||
|
||
## TLS Options | ||
|
||
The Things Stack serves several endpoints using TLS. TLS certificates can come from different sources. | ||
|
||
- `tls.source`: Source of the TLS certificate (file, acme, key-vault) | ||
|
||
If `file` is specified as `tls.source`, the location of the certificate and key need to be configured. | ||
|
||
- `tls.certificate`: Location of TLS certificate | ||
- `tls.key`: Location of TLS private key | ||
|
||
If `acme` is specified as `tls.source`, certificates will be requested from Let's Encrypt (the default `tls.acme.endpoint`) and stored in the given `tls.acme.dir`. | ||
|
||
- `tls.acme.endpoint`: ACME endpoint | ||
- `tls.acme.dir`: Location of ACME storage directory | ||
- `tls.acme.email`: Email address to register with the ACME account | ||
- `tls.acme.hosts`: Hosts to enable automatic certificates for | ||
- `tls.acme.default-host`: Default host to assume for clients without SNI | ||
|
||
If `key-vault` is specified as `tls.source`, the certificate with the given ID is loaded from the key vault. | ||
|
||
- `tls.key-vault.id`: ID of the certificate | ||
|
||
For client-side TLS, you may configure a Root CA and optionally disable verification of certificate chains. | ||
|
||
- `tls.root-ca`: Location of TLS root CA certificate (optional) | ||
- `tls.insecure-skip-verify`: Skip verification of certificate chains (insecure) | ||
|
||
## gRPC Options | ||
|
||
The `grpc` options configure how The Things Stack listens for gRPC connections. The format is `host:port`. When listening on TLS ports, it uses the global [TLS configuration]({{< ref "#tls-options" >}}). | ||
|
||
- `grpc.listen`: Address for the TCP gRPC server to listen on | ||
- `grpc.listen-tls`: Address for the TLS gRPC server to listen on | ||
|
||
When running a cluster in a trusted network, you can allow sending credentials over insecure connections with the `allow-insecure-for-credentials` option: | ||
|
||
- `grpc.allow-insecure-for-credentials`: Allow transmission of credentials over insecure transport | ||
|
||
## HTTP Options | ||
|
||
The `http` options configure how The Things Stack listens for HTTP connections. The format is `host:port`. When listening on TLS ports, it uses the global [TLS configuration]({{< ref "#tls-options" >}}). | ||
|
||
- `http.listen`: Address for the HTTP server to listen on | ||
- `http.listen-tls`: Address for the HTTPS server to listen on | ||
|
||
The Things Stack uses secure cookies that are encrypted with a `block-key` and signed with a `hash-key`. In production deployments you'll want these to stay the same between restarts. The keys are encoded as hex. | ||
|
||
- `http.cookie.block-key`: Key for cookie contents encryption (16, 24 or 32 bytes) | ||
- `http.cookie.hash-key`: Key for cookie contents verification (32 or 64 bytes) | ||
|
||
The Things Stack serves a number of internal endpoints for health, metrics and debugging. These will usually be disabled or password protected in production deployments. | ||
|
||
- `http.health.enable`: Enable health check endpoint on HTTP server | ||
- `http.health.password`: Password to protect health endpoint (username is health) | ||
- `http.metrics.enable`: Enable metrics endpoint on HTTP server | ||
- `http.metrics.password`: Password to protect metrics endpoint (username is metrics) | ||
- `http.pprof.enable`: Enable pprof endpoint on HTTP server | ||
- `http.pprof.password`: Password to protect pprof endpoint (username is pprof) | ||
|
||
It is possible to redirect users to the canonical URL of a deployment. There are options to redirect to a given host, or redirect from HTTP to HTTPS. | ||
|
||
- `http.redirect-to-host`: Redirect all requests to one host | ||
- `http.redirect-to-tls`: Redirect HTTP requests to HTTPS | ||
|
||
The HTTP server serves static files for the web UI. If these files are not in the standard location, you may need to change the search path. | ||
|
||
- `http.static.mount`: Path on the server where static assets will be served | ||
- `http.static.search-path`: List of paths for finding the directory to serve static assets from | ||
|
||
## Interoperability Options | ||
|
||
The Things Stack supports interoperability according to LoRaWAN Backend Interfaces specification. The following options are used to configure the server for this. | ||
|
||
- `interop.listen-tls`: Address for the interop server to listen on | ||
- `interop.sender-client-cas`: Path to PEM encoded file with client CAs of sender IDs to trust | ||
|
||
## Redis Options | ||
|
||
Redis is the main data store for the [Network Server]({{< relref "network-server.md" >}}), [Application Server]({{< relref "application-server.md" >}}) and [Join Server]({{< relref "join-server.md" >}}). Redis is also used by the [Identity Server]({{< relref "identity-server.md" >}}) for caching and can be used by the [events system]({{< ref "#events-options" >}}) for exchanging events between components. | ||
|
||
- `redis.address`: Address of the Redis server | ||
- `redis.password`: Password of the Redis server | ||
- `redis.database`: Redis database to use | ||
- `redis.namespace`: Namespace for Redis keys | ||
|
||
## Blob Options | ||
|
||
The `blob` options configure how The Things Stack reads or writes files such as pictures, the frequency plans repository or files required for Backend Interfaces interoperability. The `provider` field selects the provider that is used, and which other options are read. | ||
|
||
- `blob.provider`: Blob store provider (local, aws, gcp) (default "local") | ||
|
||
If the blob provider is `local`, you need to specify the directory to use. | ||
|
||
- `blob.local.directory`: Local directory that holds the buckets (default "./public/blob") | ||
|
||
If the blob provider is `aws`, you need to specify the S3 region, the access key ID and secret access key. | ||
|
||
- `blob.aws.region`: S3 region | ||
- `blob.aws.access-key-id`: Access key ID | ||
- `blob.aws.secret-access-key`: Secret access key | ||
|
||
If the blob provider is `gcp`, you can specify the credentials with either the credentials data, or with the path to the credentials file. | ||
|
||
- `blob.gcp.credentials`: JSON data of the GCP credentials, if not using JSON file | ||
- `blob.gcp.credentials-file`: Path to the GCP credentials JSON file | ||
|
||
## Events Options | ||
|
||
The `events` options configure how events are shared between components. When using a single instance of The Things Stack, the `internal` backend is the best option. If you need to communicate in a cluster, you can use the `redis` or `cloud` backend. | ||
|
||
- `events.backend`: Backend to use for events (internal, redis, cloud) (default "internal") | ||
|
||
When using the `redis` backend, the global [Redis configuration]({{< ref "#redis-options" >}}) is used. Alternatively, you may customize the Redis configuration that is used for events. | ||
|
||
- `events.redis.address`: Address of the Redis server | ||
- `events.redis.password`: Password of the Redis server | ||
- `events.redis.database`: Redis database to use | ||
- `events.redis.namespace`: Namespace for Redis keys | ||
|
||
With the `cloud` backend, the configured publish and subscribe URLs are passed to [the Go CDK](https://gocloud.dev/howto/pubsub/). | ||
|
||
- `events.cloud.publish-url`: URL for the topic to send events | ||
- `events.cloud.subscribe-url`: URL for the subscription to receiving events | ||
|
||
## Frequency Plans Options | ||
|
||
The `frequency-plans` configuration is used by the [Gateway Server]({{< relref "gateway-server.md" >}}) and the [Network Server]({{< relref "network-server.md" >}}). It can load configuration from a number of sources. | ||
|
||
- `frequency-plans.config-source`: Source of the frequency plans (static, directory, url, blob) | ||
|
||
The `url` source loads frequency plans from the given URL. See the [lorawan-frequenc-plans](https://github.com/TheThingsNetwork/lorawan-frequency-plans) repository for more information. | ||
|
||
- `frequency-plans.url` | ||
|
||
The `directory` source loads from the given directory. | ||
|
||
- `frequency-plans.directory` | ||
|
||
The `blob` source loads from the given path in a bucket. This requires the global [blob configuration]({{< ref "#blob-options" >}}). | ||
|
||
- `frequency-plans.blob.bucket`: Bucket to use | ||
- `frequency-plans.blob.path`: Path to use | ||
|
||
## Cluster Options | ||
|
||
The `cluster` options configure how The Things Stack communicates with other components in the cluster. These options do not need to be set when running a single instance of The Things Stack. The most important options are the ones to configure the addresses of the other components in the cluster. | ||
|
||
- `cluster.identity-server`: Address for the Identity Server | ||
- `cluster.gateway-server`: Address for the Gateway Server | ||
- `cluster.network-server`: Address for the Network Server | ||
- `cluster.application-server`: Address for the Application Server | ||
- `cluster.join-server`: Address for the Join Server | ||
- `cluster.crypto-server`: Address for the Crypto Server | ||
|
||
The cluster keys are 128 bit, hex-encoded keys that cluster components use to authenticate to each other. | ||
|
||
- `cluster.keys`: Keys used to communicate between components of the cluster. The first one will be used by the cluster to identify itself | ||
|
||
It is possible to configure the cluster to use TLS or not. We recommend to enable TLS for production deployments. | ||
|
||
- `cluster.tls`: Do cluster gRPC over TLS |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters