From bb798bd0514a79cc5e641038c105254d48fed01e Mon Sep 17 00:00:00 2001 From: Tobias Kaupat Date: Thu, 27 Jun 2024 09:32:08 +0200 Subject: [PATCH] Platform Admin Docs --- .../administration/server-certificates.md | 115 ++++++++++ .../administration/server-configuration.md | 216 ++++++++++++++++++ docusaurus.config.ts | 2 +- 3 files changed, 332 insertions(+), 1 deletion(-) create mode 100644 docs/platform/administration/server-certificates.md create mode 100644 docs/platform/administration/server-configuration.md diff --git a/docs/platform/administration/server-certificates.md b/docs/platform/administration/server-certificates.md new file mode 100644 index 00000000..3d7d51e3 --- /dev/null +++ b/docs/platform/administration/server-certificates.md @@ -0,0 +1,115 @@ + + +# Server Certificates + +The server needs certificates for different use cases. + +## HTTPS (Frontend) + +The frontend is always serves via HTTP. To setup HTTPS connections to the Platform Frontend you will need a reverse proxy like Nginx or Apache. + +By default we setup an nginx using docker together with the [let's encrypt companion](https://github.com/jwilder/docker-letsencrypt-nginx-proxy-companion) to provide HTTPS. + +## CoAPs (Devices) + +Devices can used secure CoAPs connections to the backend. To use CoAPs a Certificate signed by Lobaro is required. + + +The setup consists of the following steps: + +1. Create a Certificate Signing Request (CSR) +2. Request a Certificate from Lobaro +3. Install the signed Certificate in the Platform + + + + +### Create a Certificate Signing Request (CSR) + +#### Create Private Key + +The key must be created at the Platform server and should never leave the system. + + openssl ecparam -name prime256v1 -genkey -noout -out platform.key + +:::error +Do not send the resulting private key file `platform.key` to anyone. +::: + +#### Create CSR + +Update "-subj" parameter in the command below according to you server and organisation. + +* C is Country Name: e.g. `C=DE` +* ST is State or Province Name (full name): e.g. `ST=Hamburg` +* O is Organization Name (eg, company): e.g. `O=Lobaro GmbH` +* CN is Common Name (e.g. server FQDN or YOUR name): e.g. `CN=up.lobaro.com` + * The CN **must** match your domain that is configured in the devices. It can also be an IP address. + + + +```bash +openssl req -new -key platform.key -sha256 -subj "/C=DE/ST=Hamburg/O=Lobaro GmbH/CN=up.lobaro.com" -out "platform.csr" +``` + +Verify your request with: + +```bash + openssl req -text -noout -in platform.csr +``` + +### Request Certificate from Lobaro + +Send the generated CSR file (**platform.csr**) to [support@lobaro.de](mailto:support@lobaro.de) to receive a valid certificate for your Server. + +### Install the signed Certificate in the Platform + +Add or update the following keys in the Platform configuration file: + +```yaml +server: + dtlsConfig: + dtlsCertDir: "./config" # This way the configuration directory is used to lookup the key and cert. + dtlsCertName: "platform" # Used to lookup "platform.crt" and "platform.key" +featureToggle: + dtlsSecureCoapServiceEnabled: true # removed in > v1.59.1 +``` + +:::danger +We recommend to **not backup the `platform.key`** file. If it's lost, we can issue new certificates. + +If you need to backup the key file make sure the backup is encrypted in a secure way. +::: + + + + +In case you choose another location than `./config` the `docker-compose.yml` must be updated to mount the `dtlsCertDir`: + +```yaml +services: + lobaro-backend: + volumes: + - : +``` + + + +To apply the Configuration restart the Platfrom: + +```bash +docker restart platform_lobaro-backend_1 +``` + +:::tip +In case the commands fails with e.g. +`Error response from daemon: No such container: platform_lobaro-backend_1` + +Execute + +``` +docker ps | grep lobaro +``` + +You should find the container that is running the platform. The restart command can be issued with the `CONTAINER ID` or `NAME` +::: \ No newline at end of file diff --git a/docs/platform/administration/server-configuration.md b/docs/platform/administration/server-configuration.md new file mode 100644 index 00000000..ba1aa701 --- /dev/null +++ b/docs/platform/administration/server-configuration.md @@ -0,0 +1,216 @@ +# Server Configuration + +:::info[Required roles] +Server Admin (ssh access required) +::: + +Each value is loaded from different locations (highest priority first, e.g. 1. overrides 2.): + +1. Environment variables +2. Config File +3. Command line Flags +4. Default values + +## Commandline and Environment Variables + +Some options are only available via Environment Variables + +| Environment Variable | Commandline parameter | Description | Version | +|----------------------|-----------------------|--------------------------------------------------------------|-----------| +| | --config | Defile path of config file (default:lobaro-iot-platform.yml) | | +| LOB_JSON_LOGGING=1 | --json_logging=1 | Enable JSON Logging | >= 1.84.1 | + +## Configuration File + +```toml +# This is an generated example config file for the Lobaro Backend +# On production systems you can change the default values as required + +# Enable debug log output +Debug = false +# License key for the Lobaro Backend to unlock certain features +License = '' +# TCP port for Tekelek devices +TekelekTcpPort = 54345 +# TCP port for Dragino devices +DraginoTcpPort = 5600 +# DevEUI Blocks for Hardware Provisioning +DevEUIBlocks = [] + +# Frontend HTTP Server Configuration +[Server] +# Frontend URL without trailing slash (not needed when using a single domain) +FrontendUrl = '' +# Port to listen on, deprecated in favour of Bind. When Bins is set Port is ignored +Port = 0 +# Address to bind to, e.g. :8082 +Bind = ':8082' +# Enable development mode. Not safe for production! +# Authentication might be disabled. +DevMode = false +# Token secret to encrypt API Tokens. When changed, all existing Tokens are invalidated. +ApiTokenSecret = '' +# Token secret to encrypt User Tokens. When changed, all existing Tokens are invalidated. +OauthTokenSecret = '' +# Token secret to encrypt User Refresh Tokens. When changed, all existing Tokens are invalidated. +OauthRefreshTokenSecret = '' +# Directory where all file based data is stored +DataDir = './data' + +# DTLS Configuration, used by CoAPs Server +[Server.DtlsConfig] +DtlsCertDir = '' +DtlsCertName = '' +AcceptPoolSize = 10000 + +# Customer specific branding configuration +[Branding] +PlatformName = 'IoT Platform' +FrontendBaseUrl = '' +DefaultLogoUrl = '/static/branding/logo.svg' +LegalDisclosureUrl = 'https://www.lobaro.com/contact/' +ParserDocUrl = 'https://doc.lobaro.com/x/Y4B5' +DisplayDocLinks = true +IntegrationDocUrl = 'https://doc.lobaro.com/x/YIB5' +AllowRegistration = false +Favicon = '/static/img/favicon.ico' + +# Deprecated: use BrandingConfig +[Whitelabel] +PlatformName = '' + +# Postgres Database Configuration +[Database] +Database = 'postgres' +# Schema for the database, default is public. If empty string the search_path will be determined by the db +Schema = 'public' +Username = 'postgres' +Password = 'admin' +Host = 'localhost' +Port = 5432 +SslMode = 'disable' +MaxOpenConns = 90 +MaxIdleConns = 20 +# Enable debug log output for the database +Debug = false +AutoFixMigration = false +# Threshold for slow queries in milliseconds +SlowQueryThresholdMs = 5000 + +# Cache Configuration +[Database.Cache] +# Expiration time for the device cache in seconds, 0 = no cache +DeviceExpirationSec = 600 +# Disable the local cache +LocalCacheDisabled = false +# Expiration time for the local cache in seconds +LocalCacheExpirationSec = 3600 +# Purge time for the local cache in seconds +LocalCachePurgeSec = 3600 + +# Email Server settings +[Email] +Server = '' +Tls = false +Username = '' +Password = '' +Sender = '' + +# CoAP(s) Server Configuration +[CoapServer] +# CoAP port +CoapPort = 5683 +# CoAPs port +CoapsPort = 5684 + +# Digimondo Platform specific settings +[Digimondo] +ApiKey = '' + +# MQTT Broker Configuration for outbound MQTT Integrations +[Mqtt] +Name = '' +ClientId = '' +Broker = '' +Username = '' +Password = '' + +# Internal MQTT Broker Configuration +[MqttBrokerConfig] +StartBroker = false +AdminUsername = 'admin' +AdminPassword = 'admin' +# port used for broker +Port = 1883 + +# DevEUI Provisioning Configuration +[DevEUIConfig] +# When set to true, the server will assign a new DevEUI when a device with that DevEUI already exists in the platform +CheckDeviceExistOnNewEui = false + +# Allows to enable/disable single features +[FeatureToggle] +HardwareActivationEnabled = true +WmbusParserApiTabEnabled = true +WmbusParserApiPublic = false + +# JavaScript Device Parser Configuration +[Parser] +TimeoutMs = 250 + +# Device Data Storage related Configuration +[Data] +DefaultRetentionDuration = '' + +# Organisation related Configuration +[Organisation] +DefaultUserLimit = 0 +DefaultMaxSubOrganisations = 0 +MaxDepthSubOrganisations = 10 + +# NATS related Configuration. NATS is used as the internal Message Broker +[Nats] +# Start the internal nats server, host has to be localhost then +StartNatsServer = true +# NATS server hostname or IP address to connect to +Host = 'localhost' +# NATS server port to connect to +Port = 4222 +Username = 'admin' +Password = 'admin' +HTTPPort = 8222 +# Enable NATS for CoAP and CoAPs datasource +EnableCoapDatasource = false +# Size of the NATS client pool for publishing messages +ClientPoolSize = 1000 +# Hostname or IP address of the config companion +ConfigCompanionHost = 'localhost' +# Port of the config companion +ConfigCompanionPort = 8099 +# Number of workers for the uplink handler queue +UplinkHandlerWorkers = 2 +# Number of workers for the integrations queue +IntegrationHandlerWorkers = 4 +# Maximum memory (RAM) size of JetStream streams in bytes +JetStreamMaxMemory = 1073741824 +# Maximum memory (disk) usage of JetStream streams in bytes +JetStreamMaxStore = 0 +# Path to store JetStream data +JetStreamStoreDirectory = './data/jetstream' + +# general Config regarding the REST API offered by the platform +[RestApiConfig] +LogBodyOnPanic = false +LogHttpHeaderOnPanic = false + +# Integration related Configuration +[Integration] +# Default timeout for MQTT integrations in milliseconds +MqttDefaultTimeoutMs = 10000 +# Default timeout for HTTP integrations in milliseconds +HttpDefaultTimeoutMs = 10000 +# Rate limit for updating logging in case if success Seconds, 0 for no limit +LoggingSuccessRateLimitSeconds = 10 +# Rate limit for updating logging in case of error/failur in Seconds, 0 for no limit +LoggingErrorRateLimitSeconds = 10 +``` \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 33095f2c..4152094b 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -152,7 +152,7 @@ const config: Config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, - additionalLanguages: ['bash', 'json'], // https://prismjs.com/#supported-languages + additionalLanguages: ['bash', 'json', 'toml'], // https://prismjs.com/#supported-languages }, zoom: { selector: '.markdown img',