Requirements

Summary

You'll probably require a database and a reverse proxy for local development. Luckily a docker-compose.yaml is provided that has a TimescaleDB and NGINX reverse proxy configured. Just run docker compose up -d nginx postgresql and the required services should be up and running.

PostgreSQL (with Timescale)

Trajectory-trace requires a PostgreSQL database with the PostGIS and Timescale plugins enabled. You can install PostgreSQL and all Plugins manually or use the batteries included Docker image provided by TimescaleDB.

Docker

docker run -p 5432:5432 \
    -e POSTGRES_USER=postgres \
    -e POSTGRES_PASSWORD=postgres \
    timescale/timescaledb-ha:pg15.7-ts2.15.2-all-oss

Docker Compose

services:
  postgresql:
    image: timescale/timescaledb-ha:pg15.7-ts2.15.2-all-oss
    shm_size: '1gb'
    ports:
      - 5432:5432
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres

MQTT

You'll need to deploy a MQTT broker along with the application. We recommend Mosquitto but you can choose any MQTT to your liking. This guide will assume you use Mosquitto as a broker, so expect some deviations if you choose any other broker.

docker run mosquitto -p 1883:1883

If enabled authentication for you broker (you probably should), you'll need to give trajectory-trace access credentials to read from the broker. You can do so, by editing the application configuration and passing in username and password. If you don't want to dedicate the whole MQTT broker to trajectory-trace, we recommend specifying a root topic root_topic in the application configuration, giving the trajectory-trace user access to read from that topic and all sub-topics. You'll then need to modify the root_topic config value to be that MQTT topic.

For example you have a locally running Mosquitto instance on port 1883, with a user trajectory-trace and password secret123. The user trajectory-trace has read access to a topic called ttrace. The configuration would look like this:

[mqtt_config]
endpoint = "localhost"
port = 1883
root_topic = "/ttrace"
username = "trajectory-trace"
password = "secret123"

(optional) Mqtt identity provider

info

This step is recommended for production deployments. Feel free to skip this if you are only experimenting with trajectory-trace.

Trajectory-trace allows you to manage MQTT users and their credentials from within the application. This is highly recommended, because it significantly increases the overally security and accessability. The Mosquitto Go-Auth Plugin allows Mosquitto to use a PostgreSQL database for user authentication and authorization. Trajectory-trace maintains a table with mqtt users in its database by default. A system user that is used by the backend is created automatically on backend startup. If you set the MQTT credentials in the config the system user will be created with the provided credentials. To use said table, you'll need to configure Mosquitto-Go-Auth like this (replace postgres connection information):

auth_opt_backends postgres
auth_opt_hasher bcrypt
auth_opt_pg_hasher bcrypt
auth_opt_pg_host postgresql   # replace
auth_opt_pg_port 5432         # replace
auth_opt_pg_sslmode disable   # replace
auth_opt_pg_dbname postgres   # replace
auth_opt_pg_user postgres     # replace
auth_opt_pg_password postgres # replace
auth_opt_pg_connect_tries 5
auth_opt_pg_userquery SELECT password_hash from "mqtt_users" where name = $1 limit 1
auth_opt_pg_aclquery SELECT DISTINCT mqtt_prefix || mqtt_ingest_topic FROM source JOIN mqtt_users ON mqtt_users.source = source.id WHERE mqtt_users.name = $1 and $2 = $2
auth_opt_pg_superquery SELECT COUNT(*) from "mqtt_users" where name = $1 and superuser = true

More information about how to configure Mosquitto-Go-Auth can be found here.

Optional

Reverse Proxy

tip

Required for production use.

For using the frontend and backend of Trajectory-Trace deploying a reverse proxy alongside the application is required. Otherwise the builtin session authentication won't work and therefore the frontend is not able to communicate with the backend. You can use any reverse proxy you like, the only important requirement is that both frontend and backend are served under the same host, including the port.

You can use the nginx configuration for local development as inspiration.

events {
    worker_connections  1024;
}
http {
    server {
        listen 8080;
        location /api {
            proxy_pass http://localhost:3001;
        }
        location /api/graphql/ws {
            proxy_pass http://localhost:3001/api/graphql/ws;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
            proxy_set_header Host $host;

        }
        location / {
            proxy_pass http://localhost:3000;
        }
    }
}

Jaeger