docs: initial docs deployment (#10)

.dictionary

@@ -5,3 +5,8 @@ xoxys
 Proxmox
 VE
 TBD
+PVE
+SELinux
+CLI
+JSON
+toc

.drone.jsonnet

@@ -320,60 +320,60 @@ local PipelineDocs = {
         NPM_CONFIG_LOGLEVEL: 'error',
       },
     },
-    // {
+    {
-    //   name: 'testbuild',
+      name: 'testbuild',
-    //   image: 'thegeeklab/hugo:0.83.1',
+      image: 'thegeeklab/hugo:0.83.1',
-    //   commands: [
+      commands: [
-    //     'hugo -s docs/ -b http://localhost/',
+        'hugo -s docs/ -b http://localhost/',
-    //   ],
+      ],
-    // },
+    },
-    // {
+    {
-    //   name: 'link-validation',
+      name: 'link-validation',
-    //   image: 'thegeeklab/link-validator',
+      image: 'thegeeklab/link-validator',
-    //   commands: [
+      commands: [
-    //     'link-validator -ro',
+        'link-validator -ro',
-    //   ],
+      ],
-    //   environment: {
+      environment: {
-    //     LINK_VALIDATOR_BASE_DIR: 'docs/public',
+        LINK_VALIDATOR_BASE_DIR: 'docs/public',
-    //   },
+      },
-    // },
+    },
-    // {
+    {
-    //   name: 'build',
+      name: 'build',
-    //   image: 'thegeeklab/hugo:0.83.1',
+      image: 'thegeeklab/hugo:0.83.1',
-    //   commands: [
+      commands: [
-    //     'hugo -s docs/',
+        'hugo -s docs/',
-    //   ],
+      ],
-    // },
+    },
-    // {
+    {
-    //   name: 'beautify',
+      name: 'beautify',
-    //   image: 'node:lts-alpine',
+      image: 'node:lts-alpine',
-    //   commands: [
+      commands: [
-    //     'npm install -g js-beautify',
+        'npm install -g js-beautify',
-    //     "html-beautify -r -f 'docs/public/**/*.html'",
+        "html-beautify -r -f 'docs/public/**/*.html'",
-    //   ],
+      ],
-    //   environment: {
+      environment: {
-    //     FORCE_COLOR: true,
+        FORCE_COLOR: true,
-    //     NPM_CONFIG_LOGLEVEL: 'error',
+        NPM_CONFIG_LOGLEVEL: 'error',
-    //   },
+      },
-    // },
+    },
-    // {
+    {
-    //   name: 'publish',
+      name: 'publish',
-    //   image: 'plugins/s3-sync',
+      image: 'plugins/s3-sync',
-    //   settings: {
+      settings: {
-    //     access_key: { from_secret: 's3_access_key' },
+        access_key: { from_secret: 's3_access_key' },
-    //     bucket: 'geekdocs',
+        bucket: 'geekdocs',
-    //     delete: true,
+        delete: true,
-    //     endpoint: 'https://sp.rknet.org',
+        endpoint: 'https://sp.rknet.org',
-    //     path_style: true,
+        path_style: true,
-    //     secret_key: { from_secret: 's3_secret_access_key' },
+        secret_key: { from_secret: 's3_secret_access_key' },
-    //     source: 'docs/public/',
+        source: 'docs/public/',
-    //     strip_prefix: 'docs/public/',
+        strip_prefix: 'docs/public/',
-    //     target: '/${DRONE_REPO_NAME}',
+        target: '/${DRONE_REPO_NAME}',
-    //   },
+      },
-    //   when: {
+      when: {
-    //     ref: ['refs/heads/main', 'refs/tags/**'],
+        ref: ['refs/heads/main', 'refs/tags/**'],
-    //   },
+      },
-    // },
+    },
   ],
   depends_on: [
     'build-package',

.drone.yml

@@ -479,6 +479,51 @@ steps:
     FORCE_COLOR: true
     NPM_CONFIG_LOGLEVEL: error
 
+- name: testbuild
+  image: thegeeklab/hugo:0.83.1
+  commands:
+  - hugo -s docs/ -b http://localhost/
+
+- name: link-validation
+  image: thegeeklab/link-validator
+  commands:
+  - link-validator -ro
+  environment:
+    LINK_VALIDATOR_BASE_DIR: docs/public
+
+- name: build
+  image: thegeeklab/hugo:0.83.1
+  commands:
+  - hugo -s docs/
+
+- name: beautify
+  image: node:lts-alpine
+  commands:
+  - npm install -g js-beautify
+  - html-beautify -r -f 'docs/public/**/*.html'
+  environment:
+    FORCE_COLOR: true
+    NPM_CONFIG_LOGLEVEL: error
+
+- name: publish
+  image: plugins/s3-sync
+  settings:
+    access_key:
+      from_secret: s3_access_key
+    bucket: geekdocs
+    delete: true
+    endpoint: https://sp.rknet.org
+    path_style: true
+    secret_key:
+      from_secret: s3_secret_access_key
+    source: docs/public/
+    strip_prefix: docs/public/
+    target: /${DRONE_REPO_NAME}
+  when:
+    ref:
+    - refs/heads/main
+    - refs/tags/**
+
 trigger:
   ref:
   - refs/heads/main
@@ -585,6 +630,6 @@ depends_on:
 
 ---
 kind: signature
-hmac: b6ecc59cd94c224bbd990f1d6be90ec6c28e8faf121b37c56f47fa9befb77ad8
+hmac: 791f2a668d1295b69cb7000c3a38b8e3ca15d99b1c8ac40559c71aa9456fc018
 
 ...

.github/settings.yml

@@ -1,6 +1,7 @@
 repository:
   name: prometheus-pve-sd
   description: Prometheus Service Discovery for Proxmox VE
+  homepage: https://prometheus-pve-sd.geekdocs.de
   topics: prometheus, proxmox, metrics, sd, python
 
   private: false

README.md

@@ -12,7 +12,9 @@ Prometheus Service Discovery for Proxmox VE
 [![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/prometheus-pve-sd)
 [![License: MIT](https://img.shields.io/github/license/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/blob/main/LICENSE)
 
-TBD
+This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the Proxmox PVE API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd).
+
+You can find the full documentation at [https://prometheus-pve-sd.geekdocs.de](https://prometheus-pve-sd.geekdocs.de).
 
 ## Contributors
 

docs/config.yaml

@@ -0,0 +1,31 @@
+---
+baseURL: https://prometheus-pve-sd.geekdocs.de/
+title: prometheus-pve-sd
+theme: hugo-geekdoc
+pygmentsUseClasses: true
+pygmentsCodeFences: true
+
+# Geekdoc configuration
+disablePathToLower: true
+enableGitInfo: true
+
+# Needed for mermaid/katex shortcodes
+markup:
+  goldmark:
+    renderer:
+      unsafe: true
+  tableOfContents:
+    startLevel: 1
+
+params:
+  geekdocMenuBundle: true
+  geekdocToC: 3
+
+  geekdocRepo: https://github.com/thegeeklab/prometheus-pve-sd
+  geekdocEditPath: edit/main/docs/content
+
+  geekdocDateFormat: "Jan 2, 2006"
+  geekdocSearch: true
+
+  geekdocLegalNotice: https://thegeeklab.de/legal-notice/#contact-information
+  geekdocPrivacyPolicy: https://thegeeklab.de/legal-notice/#privacy-policy

docs/content/_index.md

@@ -0,0 +1,15 @@
+---
+title: Documentation
+---
+
+[![Build Status](https://img.shields.io/drone/build/thegeeklab/prometheus-pve-sd?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/prometheus-pve-sd)
+[![Docker Hub](https://img.shields.io/badge/dockerhub-latest-blue.svg?logo=docker&logoColor=white)](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd)
+[![Quay.io](https://img.shields.io/badge/quay-latest-blue.svg?logo=docker&logoColor=white)](https://quay.io/repository/thegeeklab/prometheus-pve-sd)
+[![Python Version](https://img.shields.io/pypi/pyversions/prometheus-pve-sd.svg)](https://pypi.org/project/prometheus-pve-sd/)
+[![PyPI Status](https://img.shields.io/pypi/status/prometheus-pve-sd.svg)](https://pypi.org/project/prometheus-pve-sd/)
+[![PyPI Release](https://img.shields.io/pypi/v/prometheus-pve-sd.svg)](https://pypi.org/project/prometheus-pve-sd/)
+[![GitHub contributors](https://img.shields.io/github/contributors/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/graphs/contributors)
+[![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/prometheus-pve-sd)
+[![License: MIT](https://img.shields.io/github/license/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/blob/main/LICENSE)
+
+This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the Proxmox PVE API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd).

docs/content/configuration/_index.md

@@ -0,0 +1,11 @@
+---
+title: Configuration
+---
+
+Changes can be made on different locations which will be processed in the following order (last wins):
+
+- default configuration (build-in)
+- global configuration file (path depends on your operating system)
+- user-defined configuration file
+- environment variables
+- CLI options

docs/content/configuration/cli.md

@@ -0,0 +1,31 @@
+---
+title: CLI options
+---
+
+You can get all available CLI options by running `prometheus-pve-sd --help`:
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< highlight Shell "linenos=table" >}}
+$ prometheus-pve-sd --help
+usage: prometheus-pve-sd [-h] [-c CONFIG_FILE] [-o OUTPUT_FILE] [-d LOOP_DELAY] [--no-service] [-f LOG_FORMAT] [-v] [-q] [--version]
+
+Prometheus Service Discovery for Proxmox VE
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -c CONFIG_FILE, --config CONFIG_FILE
+                        location of configuration file
+  -o OUTPUT_FILE, --output OUTPUT_FILE
+                        output file
+  -d LOOP_DELAY, --loop-delay LOOP_DELAY
+                        delay between discovery runs
+  --no-service          run discovery only once
+  -f LOG_FORMAT, --log-format LOG_FORMAT
+                        used log format
+  -v                    increase log level
+  -q                    decrease log level
+  --version             show program's version number and exit
+{{< /highlight >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->

docs/content/configuration/defaults.md

@@ -0,0 +1,42 @@
+---
+title: Default settings
+---
+
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<!-- spellchecker-disable -->
+{{< highlight YAML "linenos=table" >}}
+---
+logging:
+    # supported log levels: debug|info|warning|error|critical
+    level: warning
+    # supported log formats: console|json|simple
+    format: console
+
+output_file:
+loop_delay: 300
+# Run pve sd in a loop and discover hosts every n seconds (as defined in loop_delay).
+# Can be disabled to run disovery only once.
+service: true
+
+exclude_state: []
+exclude_vmid: []
+
+pve:
+    server:
+    user:
+    password
+    auth_timeout: 5
+    verify_ssl: true
+
+# Example
+# pve:
+#     server: proxmox.example.com
+#     user: root
+#     password: secure
+#     auth_timeout: 5
+#     verify_ssl: true
+{{< /highlight >}}
+<!-- spellchecker-enable -->
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->

docs/content/configuration/env.md

@@ -0,0 +1,29 @@
+---
+title: Environment Variables
+---
+
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<!-- spellchecker-disable -->
+{{< highlight Shell "linenos=table" >}}
+PROMETHEUS_PVE_SD_CONFIG_FILE=
+# supported log levels: debug|info|warning|error|critical
+PROMETHEUS_PVE_SD_LOG_LEVEL=warning
+# supported log formats: console|json|simple
+PROMETHEUS_PVE_SD_LOG_FORMAT=console
+PROMETHEUS_PVE_SD_OUTPUT_FILE=
+PROMETHEUS_PVE_SD_LOOP_DELAY=300
+# Run pve sd in a loop and discover hosts every n seconds (as defined in PROMETHEUS_PVE_SD_LOOP_DELAY).
+# Can be disabled to run disovery only once.
+PROMETHEUS_PVE_SD_SERVICE=true
+PROMETHEUS_PVE_SD_EXCLUDE_STATE=
+PROMETHEUS_PVE_SD_EXCLUDE_VMID=
+PROMETHEUS_PVE_SD_PVE_SERVER=
+PROMETHEUS_PVE_SD_PVE_USER=
+PROMETHEUS_PVE_SD_PVE_PASSWORD=
+PROMETHEUS_PVE_SD_PVE_AUTH_TIMEOUT=5
+PROMETHEUS_PVE_SD_PVE_VERIFY_SSL=true
+{{< /highlight >}}
+<!-- spellchecker-enable -->
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->

docs/content/setup/_index.md

@@ -0,0 +1,3 @@
+---
+title: Setup
+---

docs/content/setup/docker.md

@@ -0,0 +1,26 @@
+---
+title: Using docker
+---
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< highlight Shell "linenos=table" >}}
+docker run \
+    -e PROMETHEUS_PVE_SD_LOG_LEVEL=info \
+    -e PROMETHEUS_PVE_SD_LOG_FORMAT=console \
+    -e PROMETHEUS_PVE_SD_OUTPUT_FILE=/out/pve.json \
+    -e PROMETHEUS_PVE_SD_SERVICE=false \
+    -e PROMETHEUS_PVE_SD_PVE_SERVER=pve.example.com \
+    -e PROMETHEUS_PVE_SD_PVE_USER=root \
+    -e PROMETHEUS_PVE_SD_PVE_PASSWORD=secure \
+    -e PY_COLORS=1 \
+    -v $(pwd):/out \
+    thegeeklab/prometheus-pve-sd
+{{< /highlight >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
+{{< hint info >}}
+**Info**\
+Keep in mind, that you have to pass SELinux labels (:Z or :z) to your mount option if you are working on SELinux enabled systems.
+{{< /hint >}}

docs/content/setup/pip.md

@@ -0,0 +1,20 @@
+---
+title: Using pip
+---
+
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<!-- spellchecker-disable -->
+{{< highlight Shell "linenos=table" >}}
+# From PyPI as unprivileged user
+$ pip install prometheus-pve-sd --user
+
+# .. or as root
+$ sudo pip install prometheus-pve-sd
+
+# From Wheel file
+$ pip install https://github.com/thegeeklab/prometheus-pve-sd/releases/download/v0.1.0/prometheus_pve_sd-0.1.0-py3-none-any.whl
+{{< /highlight >}}
+<!-- spellchecker-enable -->
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->

docs/content/usage/_index.md

@@ -0,0 +1,58 @@
+---
+title: Usage
+---
+
+{{< toc >}}
+
+## Start PVE SD
+
+Create a [configuration file](/configuration/defaults/) with the required parameters to connect to your PVE server before you start the service.
+
+```Shell
+run prometheus-pve-sd -vv --loop-delay 900 -o /etc/prometheus/pve.json
+```
+
+## Available Labels
+
+The following list of meta labels can be used to relabel your scrape results:
+
+`__meta_pve_ip`
+
+`__meta_pve_name`
+
+`__meta_pve_type`
+
+`__meta_pve_vmid`
+
+`__meta_pve_cpu`
+
+`__meta_pve_cores`
+
+`__meta_pve_memory`
+
+`__meta_pve_status`
+
+`__meta_pve_groups`
+: Groups will be discovered from the `Notes` field of a host and need to be set as JSON e.g. `{"groups":["group1","group2"]}`
+
+## Prometheus configuration
+
+This example configuration snippet for the Prometheus `scrape_config` Prometheus to scrape `telegraf` assuming that it is deployed on all your servers.
+
+```YAML
+- file_sd_configs:
+  - files:
+    - /opt/prometheus/conf/file_sd/proxmox.json
+  job_name: telegraf-pve
+  metrics_path: /metrics
+  relabel_configs:
+  - replacement: telegraf
+    target_label: job
+  - replacement: ${1}:9273
+    source_labels:
+    - __meta_pve_name
+    target_label: __address__
+  - source_labels:
+    - __meta_pve_name
+    target_label: instance
+```

docs/data/menu/main.yml

@@ -0,0 +1,19 @@
+---
+main:
+  - name: Setup
+    sub:
+      - name: Using pip
+        ref: "/setup/pip"
+      - name: Using docker
+        ref: "/setup/docker"
+  - name: Configuration
+    ref: "/configuration"
+    sub:
+      - name: Default settings
+        ref: "/configuration/defaults"
+      - name: CLI options
+        ref: "/configuration/cli"
+      - name: Environment variables
+        ref: "/configuration/env"
+  - name: Usage
+    ref: "/usage"

docs/data/menu/more.yml

@@ -0,0 +1,10 @@
+---
+more:
+  - name: Releases
+    ref: "https://github.com/thegeeklab/prometheus-pve-sd/releases"
+    external: true
+    icon: "gdoc_download"
+  - name: "View Source"
+    ref: "https://github.com/thegeeklab/prometheus-pve-sd"
+    external: true
+    icon: "gdoc_github"

docs/static/.htaccess

@@ -0,0 +1,16 @@
+ErrorDocument 404 /404.html
+
+ExpiresActive On
+ExpiresDefault "access plus 600 seconds"
+ExpiresByType text/css "access plus 1 week"
+ExpiresByType text/javascript "access plus 1 month"
+ExpiresByType text/html "access plus 1 seconds"
+ExpiresByType application/javascript "access plus 1 month"
+ExpiresByType application/x-javascript "access plus 1 month"
+ExpiresByType image/gif "access plus 1 week"
+ExpiresByType image/jpeg "access plus 1 week"
+ExpiresByType image/png "access plus 1 week"
+ExpiresByType image/x-icon "access plus 1 month"
+ExpiresByType image/svg+xml "access plus 1 week"
+ExpiresByType application/x-font-woff "access plus 1 week"
+ExpiresByType application/font-woff2 "access plus 1 week"