add rough influx/grafana guides

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 <http://your-vps-ip-address:8086>.
+
+## 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: <https://caddyserver.com/docs/install#debian-ubuntu-raspbian>
+
+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 <https://influx.example.com>.
+
+## 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. <http://some_ip:8086> or <https://influx.example.com>.
+
+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.

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 <https://grafana.example.com> 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: <https://influx.example.com>
+
+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.