diff --git a/doc/3-metrics/0-influx.md b/doc/3-metrics/0-influx.md index 4abe456..a021841 100644 --- a/doc/3-metrics/0-influx.md +++ b/doc/3-metrics/0-influx.md @@ -1 +1,122 @@ # InfluxDB + +*These instructions are a work in progress, and some parts may be broken.* + +This guide assumes you are running these commands as root. On a hardened system, this would be a bad thing, but it's fine for testing. + +Start by getting a machine to work on, such as a Vultr VPS. + +Update the machine, and install the `docker.io` package on it: + +```sh +sudo apt update +sudo apt upgrade -y +sudo apt install -y docker.io +``` + +Create an Influx config file skeleton: + +```sh +docker run --rm influxdb:2.7 influxd print-config > influxdb2-config.yml +``` + +You can read through the config and modify anything you like. Then create a data directory that will be mounted inside the container: + +```sh +mkdir -p /root/influxdb2 +``` + +Create the InfluxDB container: + +```sh +docker run \ + --name influxdb2 \ + -d \ + --restart always \ + -p 8086:8086 \ + -v /root/influxdb2:/var/lib/influxdb2 \ + -v /root/influxdb2-config.yml:/etc/influxdb2/config.yml \ + influxdb:2.7 +``` + +Check that the container is running: + +```sh +docker ps +``` + +Once the container is running, you need to access it. You can either run insecurely and access it directly on port 8086, or you can set up a reverse proxy to serve as a secure "middleman" between the internet and the container. + +## Direct Access + +To access InfluxDB directly, ensure you allow the port in your system's firewall, if applicable. Ubuntu on Vultr comes with `ufw` enabled by default. You can allow the port with: + +```sh +ufw allow 8086 +``` + +Then you can view InfluxDB by navigating to . + +## Reverse Proxy + +You will need a domain name so that you can add a DNS `A` record for your VPS IP address. For instance, running `host influxdb.metrics.roeber.dev` shows the VPS IP address of 155.138.217.70. + +You will also need to choose a reverse proxy like Nginx or Caddy. Caddy may be simpler to learn, and it will automatically handle TLS certificate generation for you if it listens on a public IP. + +To install Caddy on Ubuntu: + +Ensure the firewall (if applicable) allows web traffic: + +```sh +ufw allow 80 +ufw allow 443 +``` + +Once installed, you can modify `/etc/caddy/Caddyfile` to include the following: + +```conf +influx.example.com { + reverse_proxy :8086 +} +``` + +Reload Caddy with `systemctl reload caddy`, wait a few moments for TLS certificate generation, and then navigate to . + +## InfluxDB Setup + +Once you can access InfluxDB in your browser, you can perform setup. Copy the operator API token that you get during the setup process (you *cannot* get it back if you lose it, so keep it safe.) + +Open up a shell in the container and set the op token: + +```bash +docker exec -it influxdb2 bash +export INFLUX_TOKEN=token_you_got_from_the_web_interface +``` + +Create an organization named e.g. `augusta` and bucket named `mybucket`: + +```bash +influx org create --name augusta +influx bucket create --org augusta --name mybucket +``` + +Create a user and give all rights in the organization: + +```bash +influx user create --org augusta --name newguy --password somep@ssword +influx auth create --org augusta --user newguy --all-access --description "All access on Augusta organization for user newguy" # https://stackoverflow.com/a/72817942 +``` + +## ChirpStack Integration + +In InfluxDB, create an API token that has read/write access to the bucket you want ChirpStack to work with. Keep it handy. + +In ChirpStack, go to Applications -> your application name -> Integrations. Click the `+` button below InfluxDB. + +Select `InfluxDB v2` for the version. + +For the endpoint, enter the URL you use to get to InfluxDB, e.g. or . + +Enter the Influx organization, bucket, and the token you just generated, then submit. + +If data is being sent from a ChirpStack gateway to Chirpstack for the application you just added the Influx integration to, that same data should start showing up in InfluxDB. diff --git a/doc/3-metrics/1-grafana.md b/doc/3-metrics/1-grafana.md index b392791..899ad02 100644 --- a/doc/3-metrics/1-grafana.md +++ b/doc/3-metrics/1-grafana.md @@ -1 +1,60 @@ # Grafana + +*These instructions are a work in progress, and some parts may be broken.* + +You can do this on the same machine as Influx; just make sure you add another DNS `A` record if you are using a reverse proxy. + +Create `grafana.ini`: + +```ini +[server] +domain = grafana.example.com +root_url = https://grafana.example.com/ +``` + +SSH in to `grafana.example.com`. + +`mkdir grafana` + +`chown -R ubuntu:root grafana` + +```bash +docker run -d -p 3000:3000 --name=grafana \ + --user "1000" \ + --volume "$PWD/grafana:/var/lib/grafana" \ + --volume "$PWD/grafana.ini:/etc/grafana/grafana.ini" \ + --restart always \ + grafana/grafana-oss +``` + +It is possible that the container would set its permission on its own (i.e. `chown` not required.) + +Add a Caddy entry in `/etc/caddy/Caddyfile`: + +```conf +grafana.example.com { + reverse_proxy :3000 +} +``` + +Reload Caddy with `systemctl reload caddy`. + +Go to in a browser to confirm it works, and do initial setup. + +## Connect to InfluxDB + +Create a read/write token for the bucket in InfluxDB and keep it handy. + +Menu -> Connections -> Data Sources -> type InfluxDB + +Once on the InfluxDB data source screen, select "Flux" as the query language. + +Enter the URL: + +Uncheck "Basic auth". + +Under "InfluxDB Details" enter the Influx organization the bucket is in, the token you created in InfluxDB earlier, and the bucket name. + +Then "Save & test" to make sure it's working. + +Finally, you can create a dashboard that uses the data source and format it however you like.