Merge pull request #13 from luissimas/docs/usage

Docs/usage

README.md

@@ -15,6 +15,37 @@ An agent that collects metrics from an zettelkasten and stores them into an Infl
 - Authenticate in private git repositories using personal access tokens
 - Grafana dashboards included
 
+## Usage
+
+The exporter is distributed as both a binary and a Docker image. The currently documented ways of deploy are via docker compose and Kubernetes. For details about the setup, check out the examples:
+
+- [Docker compose example](./examples/compose).
+- [Kubernetes example](./examples/kubernetes).
+
+Note that for a complete solution, it will be necessary to also configure InfluxDB and Grafana. For more information about setting them up, refer to their documentation. Here are some links that might be useful:
+
+- https://grafana.com/docs/grafana/latest/getting-started/get-started-grafana-influxdb/
+- https://docs.influxdata.com/influxdb/v2/get-started/setup/
+
+## Configuration
+
+All configuration is supplied via environment variables. You should supply at least the required variables and either the `ZETTELKASTEN_DIRECTORY` or the `ZETTELKASTEN_GIT_URL` variables.
+
+| Name                       | Description                                                          | Default                        | Required |
+| -------------------------- | -------------------------------------------------------------------- | ------------------------------ | -------- |
+| INFLUXDB_URL               | The InfluxDB URL                                                     |                                | Yes      |
+| INFLUXDB_TOKEN             | The InfluxDB token to authenticate in the bucket                     |                                | Yes      |
+| INFLUXDB_ORG               | The InfluxDB org containing the bucket                               |                                | Yes      |
+| INFLUXDB_BUCKET            | The InfluxDB bucket to register metrics                              |                                | Yes      |
+| ZETTELKASTEN_DIRECTORY     | The local directory containing the zettelkasten                      |                                | No       |
+| ZETTELKASTEN_GIT_URL       | The URL for the git repository containing the zettelkasten           |                                | No       |
+| ZETTELKASTEN_GIT_TOKEN     | The access token to authenticate with private repositories           |                                | No       |
+| ZETTELKASTEN_GIT_BRANCH    | The branch to use for git repositories                               | main                           | No       |
+| COLLECTION_INTERVAL        | Time to wait between metric collections                              | 5m                             | No       |
+| COLLECT_HISTORICAL_METRICS | Wether to collect historical metrics at startup                      | true                           | No       |
+| IGNORE_FILES               | Comma separated list of files that will be ignored in the collection | .git,obsidian,.trash,README.md | No       |
+| LOG_LEVEL                  | The minimum log level                                                | INFO                           | No       |
+
 ## References
 
 https://prometheus.io/docs/instrumenting/writing_exporters/
@@ -28,3 +59,5 @@ https://github.com/influxdata/helm-charts/tree/master/charts/influxdb2
 https://grafana.com/docs/grafana/latest/getting-started/get-started-grafana-influxdb/
 
 https://docs.influxdata.com/flux/v0/get-started/
+
+https://github.com/onedr0p/exportar

examples/Zettelkasten-InfluxDB.json → dashboards/Zettelkasten-InfluxDB.json

@@ -18,7 +18,7 @@
   "editable": true,
   "fiscalYearStartMonth": 0,
   "graphTooltip": 0,
-  "id": 3,
+  "id": 1,
   "links": [],
   "panels": [
     {
@@ -213,7 +213,7 @@
             "type": "influxdb",
             "uid": "edogaymh9y96of"
           },
-          "query": "from(bucket: v.defaultBucket)\n|> range(start: -1d)\n|> last()\n|> group()",
+          "query": "from(bucket: v.defaultBucket)\n|> range(start: v.timeRangeStart, stop: v.timeRangeStop)\n|> last()\n|> group()",
           "refId": "A"
         }
       ],
@@ -428,7 +428,7 @@
       "type": "timeseries"
     }
   ],
-  "refresh": "1m",
+  "refresh": "10s",
   "schemaVersion": 39,
   "tags": [],
   "templating": {
@@ -437,7 +437,7 @@
         "current": {
           "selected": false,
           "text": "influxdb",
-          "value": "edogaymh9y96of"
+          "value": "bdp8tekqeihogd"
         },
         "hide": 0,
         "includeAll": false,
@@ -454,14 +454,14 @@
     ]
   },
   "time": {
-    "from": "now-5y",
+    "from": "now-1h",
     "to": "now"
   },
   "timeRangeUpdatedDuringEditOrView": false,
   "timepicker": {},
   "timezone": "browser",
   "title": "Zettelkasten",
   "uid": "fdoghlpqzr5kwe",
-  "version": 8,
+  "version": 2,
   "weekStart": ""
 }

examples/compose/docker-compose.yaml

@@ -0,0 +1,55 @@
+# This is a sample compose file for deploying the zettelkasten-exporter
+# using an InfluxDB storage.
+version: '3.8'
+
+volumes:
+  influxdb-data: {}
+  influxdb-config: {}
+  grafana-data: {}
+
+services:
+  grafana:
+    image: grafana/grafana
+    depends_on:
+      - influxdb
+    restart: unless-stopped
+    volumes:
+      - grafana-data:/var/lib/grafan
+    ports:
+      - 3000:3000
+
+  influxdb:
+    image: influxdb:2
+    environment:
+      # We opt for an automated setup of InfluxDB for simplicity. It's
+      # strongly recommended to change those credentials or doing a
+      # manual InfluxDB setup
+      DOCKER_INFLUXDB_INIT_MODE: setup
+      DOCKER_INFLUXDB_INIT_USERNAME: admin
+      DOCKER_INFLUXDB_INIT_PASSWORD: password
+      DOCKER_INFLUXDB_INIT_ORG: default
+      DOCKER_INFLUXDB_INIT_BUCKET: zettelkasten
+      DOCKER_INFLUXDB_INIT_RETENTION: 1w
+      DOCKER_INFLUXDB_INIT_ADMIN_TOKEN: demo-auth-token
+    volumes:
+      - influxdb-data:/var/lib/influxdb2
+      - influxdb-config:/etc/influxdb2
+    ports:
+      - 8086:8086
+
+  zettelkasten-exporter:
+    image: ghcr.io/luissimas/zettelkasten-exporter:latest
+    depends_on:
+      - influxdb
+    environment:
+      LOG_LEVEL: INFO
+      # Here we use a local directory for simplicity, but check out the
+      # README to see how to configure different sources such as git repositories.
+      ZETTELKASTEN_DIRECTORY: /sample
+      COLLECTION_INTERVAL: 10s
+      INFLUXDB_TOKEN: demo-auth-token
+      INFLUXDB_URL: http://influxdb:8086
+      INFLUXDB_ORG: default
+      INFLUXDB_BUCKET: zettelkasten
+    volumes:
+      - ./sample:/sample

examples/compose/sample/dir1/dir2/four.md

@@ -0,0 +1,3 @@
+# Four
+
+Relative link to [[../three.md]]. And another link to [[one]].

examples/compose/sample/dir1/three.md

@@ -0,0 +1,7 @@
+# Three
+
+Multiple links in this one.
+
+[[one]]
+[[two.md]]
+[[four]]

examples/compose/sample/one.md

@@ -0,0 +1,5 @@
+# One
+
+This is a markdown note.
+
+This is a [[link to a second|two.md]] note.

examples/compose/sample/two.md

@@ -0,0 +1,3 @@
+# Two
+
+This note links to the [[three.md]] note.

examples/kubernetes/manifest.yaml

@@ -0,0 +1,66 @@
+# This is a sample manifest for deploying the zettelkasten-exporter using an InfluxDB
+# storage.
+# To deploy InfluxDB, see: https://github.com/influxdata/helm-charts/tree/master/charts/influxdb2
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: monitoring
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: zettelkasten-exporter-env
+  namespace: monitoring
+type: Opaque
+data:
+  # These are placeholder values. Replace them with the
+  # appropriate values for your setup.
+  github-token: YW55LXRva2Vu
+  influxdb-token: YW55LXRva2Vu
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: zettelkasten-exporter
+  namespace: monitoring
+  labels:
+    app.kubernetes.io/name: zettelkasten-exporter
+spec:
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: zettelkasten-exporter
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: zettelkasten-exporter
+    spec:
+      containers:
+        - name: zettelkasten-exporter
+          image: "ghcr.io/luissimas/zettelkasten-exporter:latest"
+          env:
+          - name: LOG_LEVEL
+            value: INFO
+          - name: COLLECTION_INTERVAL
+            value: 5m
+          - name: ZETTELKASTEN_GIT_URL
+            value: <YOUR_REPOSITORY_GIT_URL>
+          - name: ZETTELKASTEN_GIT_BRANCH
+            value: master
+          - name: ZETTELKASTEN_GIT_TOKEN
+            valueFrom:
+              secretKeyRef:
+                name: zettelkasten-exporter-env
+                key: github-token
+          - name: INFLUXDB_URL
+            value: http://influxdb-influxdb2
+          - name: INFLUXDB_ORG
+            value: homelab
+          - name: INFLUXDB_BUCKET
+            value: zettelkasten
+          - name: INFLUXDB_TOKEN
+            valueFrom:
+              secretKeyRef:
+                name: zettelkasten-exporter-env
+                key: influxdb-token