Configuration

Parameters

The following parameters can be configured for the Collector App:

The Collector App needs a database to store users and settings. Different SQL database management systems can be configured for this purpose. By default, the Collector App uses a SQLite database in the form of a file. So no database server is needed.

There are several ways to configure the Collector App which are explained below.

Secure web communication (TLS)

The Web/API server of the Collector App runs unencrypted (http). It is also not possible to configure encryption (https). The reason for this is that otherwise the configuration effort would be much more complicated, especially due to certificate management. In a trusted, internal network, unencrypted operation can be tolerated under certain circumstances.

To run the Collector App via TLS (https), the web server nginx is recommended. This can act as a so-called reverse proxy. You can configure the Collector App to run only on localhost or a secure VPN. Nginx is installed on the same server or on one in the VPN and connects to the Collector App via the unencrypted http protocol. Outward to the insecure network, nginx provides a secure https server. Thus nginx is able to forward the requests coming over the secure protocol to the collector.

Example Nginx configuration as a reverse proxy for the Collector app:

events {}
http {

  upstream collector_app {
      server {http_collector_url};
  }

  map $http_upgrade $connection_upgrade {
          default upgrade;
          ''      close;
  }

# Requests to http are redirected to https
  server {
      listen 0.0.0.0:80;
      server_name {server_name};
      server_tokens off;
      return 301 https://$host$request_uri;
  }

# The secure https server
  server {
      listen 443 ssl;
      ssl_certificate {path_to_cert};
      ssl_certificate_key {path_to_key};

      ssl_protocols TLSv1.2 TLSv1.1 TLSv1;

      server_name {server_name};
      access_log /var/log/nginx/myapp.log;
      error_log /var/log/nginx/myapp_error.log;

      location /collector-app {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header Host $http_host;
         proxy_set_header X-NginX-Proxy true;
         proxy_set_header X-Ssl on;

         proxy_pass http://collector_app/collector-app;
      }

      location /api/ {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header Host $http_host;
         proxy_set_header X-NginX-Proxy true;
         proxy_set_header X-Ssl on;

         proxy_pass http://collector_app/api/;
      }

      location /api/subscriptions {
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header Host $host;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection $connection_upgrade;
         proxy_connect_timeout 7d;
         proxy_send_timeout 7d;
         proxy_read_timeout 7d;


         proxy_pass http://collector_app/api/subscriptions;
      }

      location / {
          return 301 /collector_app/;
      }
  }
}

The value for the collector app url {http_collector_url} and the nginx host name {server_name} must be configured accordingly. You also need a signed certificate {path_to_cert} and key {path_to_key}. If the Collector App is operated over the Internet, the certificate service Let's Encrypt can be used.

A self-signed certificate can also be created for testing purposes:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

JSON file

The default configuration file is located

• under Windows in the App Data directory: %appdata%/iTE-SI/Collector-App/config/default.json
• and on Docker/Linux /etc/collector-app/default.json.

By default, the file has the following contents:

{
  "host": "0.0.0.0",
  "port": 4000,
  "tokenSecret": "this-is-a-secret-value-with-at-least-32-characters",
  "encryptionKey": "e44c966f21b9e1577802464f8924e6a37e3e9751fa01304213b2f845d8841d61",
  "corsOrigin": "http://localhost:4000",
  "apiUrl": "http://localhost:4000/api/graphql",
  "wsUrl": "ws://localhost:4000/api/subscriptions",
  "database": {
    }, "type": "sqlite",
    "database": "/var/lib/collector-app/db.sqlite3"
  }
}

In the database section different SQL databases can be configured. For this we refer to the documentation of typeorm: https://github.com/typeorm/typeorm/blob/0.2.45/docs/connection-options.md

By default a sqlite3 database file is used, so that the Collector App can run standalone without other dependencies. This database is usually sufficient for the performance of the app.

Custom Configuration

If you want to customize the default settings, you should not do this to the default.json file, but create a copy production.json in the same directory. This file can now be customized as you like.

Environment variables

For the deployment via Docker container but also for setting the secret keys, environment variables are especially useful. If a variable is set, it is used in preference to the value in the configuration file.

General environment variables

• COLLECTOR_APP_HOST
• COLLECTOR_APP_PORT
• COLLECTOR_APP_TOKEN_SECRET
• COLLECTOR_APP_ENCRYPTION_KEY
• COLLECTOR_APP_CORS_ORIGIN
• COLLECTOR_APP_PUBLIC_GRAPHQL_URL
• COLLECTOR_APP_PUBLIC_WS_URL

Database Environment Variables

To configure the database, the typeorm environment variables are set as described here.

• TYPEORM_CACHE
• TYPEORM_CACHE_ALWAYS_ENABLED
• TYPEORM_CACHE_DURATION
• TYPEORM_CACHE_OPTIONS
• TYPEORM_CONNECTION
• TYPEORM_DATABASE
• TYPEORM_DEBUG
• TYPEORM_DRIVER_EXTRA
• TYPEORM_HOST
• TYPEORM_LOGGER
• TYPEORM_LOGGING
• TYPEORM_MAX_QUERY_EXECUTION_TIME
• TYPEORM_PASSWORD
• TYPEORM_PORT
• TYPEORM_SCHEMA
• TYPEORM_SID
• TYPEORM_SUBSCRIBERS
• TYPEORM_SUBSCRIBERS_DIR
• TYPEORM_SYNCHRONIZE
• TYPEORM_URL
• TYPEORM_USERNAME
• TYPEORM_UUID_EXTENSION