update docs & examples

.samples/Caddyfile

@@ -0,0 +1,14 @@
+lg.example.com:443 {
+    tls person@example.com
+    file_server {
+            root /etc/hyperglass/static/ui
+            index /etc/hyperglass/static/ui/index.html
+        }
+        file_server /custom {
+            root /etc/hyperglass/static/custom
+        }
+        file_server /images {
+            root /etc/hyperglass/static/images
+        }
+    reverse_proxy localhost:8001
+}

.samples/hyperglass-docker.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=hyperglass
+PartOf=docker.service
+After=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=true
+WorkingDirectory=/opt/hyperglass
+EnvironmentFile=/etc/hyperglass/hyperglass.env
+ExecStart=/usr/bin/docker compose up -d --remove-orphans
+ExecStop=/usr/bin/docker compose down
+
+[Install]
+WantedBy=multi-user.target

.samples/hyperglass-manual.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=hyperglass
+After=network.target
+Requires=redis-server
+
+[Service]
+User=root
+Group=root
+EnvironmentFile=/etc/hyperglass/hyperglass.env
+ExecStart=python3 -m hyperglass.console start
+
+[Install]
+WantedBy=multi-user.target

.samples/hyperglass.nginx

@@ -0,0 +1,49 @@
+server {
+  listen 80;
+  listen [::]:80;
+  server_name lg.example.com;
+  return 301 https://$host$request_uri;
+}
+server {
+  listen [::]:443 ssl ipv6only=on;
+  listen 443 ssl;
+  ssl_certificate <path to cert chain>
+  ssl_certificate_key <path to key>
+
+  client_max_body_size 2M;
+
+  server_name lg.example.com;
+
+  root /etc/hyperglass/static;
+
+  location / {
+    try_files $uri $uri/ /ui /ui/$uri =404;
+    index /ui/index.html;
+  }
+
+  location /openapi.json {
+      try_files $uri @proxy_to_app;
+  }
+
+  location /custom/ {
+      try_files $uri $uri/ /custom;
+  }
+
+  location /images/ {
+      try_files $uri $uri/ /images;
+  }
+
+  location /api {
+      try_files $uri @proxy_to_app;
+  }
+
+  location @proxy_to_app {
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Host $http_host;
+    proxy_redirect off;
+    proxy_pass http://[::1]:8001;
+  }
+
+}

.samples/sample_devices.yaml

@@ -0,0 +1,7 @@
+devices:
+  - name: Example Device
+    address: 127.0.0.1
+    credential:
+      username: test
+      password: test
+    platform: juniper

docs/pages/configuration.mdx

@@ -1,4 +1,24 @@
-import { Callout } from 'nextra-theme-docs';
+import { Code, Table, Td, Th, Tr } from "nextra/components";
+import { Callout } from "nextra-theme-docs";
+import platforms from "~/platforms.json";
+import { Supported } from "./platforms.mdx";
+
+export const Platforms = () => (
+    <ul>
+        {platforms.reduce((final, platform) => {
+            if (platform.native) {
+                const element = (
+                    <li key={platform.name}>
+                        <Supported style={{ display: "inline", marginRight: "0.5rem" }} />
+                        {platform.name}
+                    </li>
+                );
+                final = [...final, element];
+            }
+            return final;
+        }, [])}
+    </ul>
+);
 
 Once you've gotten started with a basic configuration, you'll probably want to customize the look and feel of hyperglass by changing the logo or color scheme. Fortunately, there are _a lot_ ways to customize hyperglass.
 
@@ -8,12 +28,12 @@ Once you've gotten started with a basic configuration, you'll probably want to c
 | :----------- | :------------------------------------------------------------------------- |
 | `config`     | Application-wide configuration such as logging, web UI customization, etc. |
 | `devices`    | Your devices and their associated configurations.                          |
-| `directives` | Custom [directives](/configuration/directives-file-reference) (commands).  |
+| `directives` | Custom [directives](configuration/directives.mdx) (commands).              |
 
 <Callout type="info">
-  **File Extensions** <br />
-  All the examples in the docs are provided in [YAML](https://yaml.org/) format, but [TOML](https://toml.io/),
-  JSON, and Python files are also supported.
+    **File Extensions** <br />
+    All the examples in the docs are provided in [YAML](https://yaml.org/) format, but [TOML](https://toml.io/),
+    JSON, and Python files are also supported.
 </Callout>
 
 ### Using a Python File
@@ -55,3 +75,21 @@ main = {
     }
   }
 ```
+
+## Built-in Directives
+
+hyperglass ships with predefined [directives](configuration/directives.mdx) for the following [platforms](platforms.mdx):
+
+<Platforms />
+
+All built in directives require that the following `attrs` be defined on each device using the directive:
+
+| Attribute | Value                                                     |
+| :-------- | :-------------------------------------------------------- |
+| `source4` | IPv4 address used to source Ping and Traceroute commands. |
+| `source6` | IPv6 address used to source Ping and Traceroute commands. |
+
+<Callout type="warning">
+    If you do not utilize IPv6 in your network, you'll need to create your own directive that only
+    has IPv4 commands.
+</Callout>

docs/pages/configuration/_meta.json

@@ -1,4 +1,6 @@
 {
-  "reference": "Reference",
+  "config": "Config File",
+  "devices": "Devices File",
+  "directives": "Directives File",
   "examples": "Examples"
 }

docs/pages/configuration/examples/basic-configuration.mdx

@@ -3,13 +3,13 @@ title: Basic Configuration
 description: Get started with a basic hyperglass configuration
 ---
 
-import { Callout } from 'nextra-theme-docs';
+import { Callout } from "nextra-theme-docs";
 
 To get started, hyperglass only needs to know about your devices.
 
 <Callout>
-  **Devices** are your routers, switches, or whatever else you want to call the endpoints hyperglass
-  will query for information.
+    **Devices** are your routers, switches, or whatever else you want to call the endpoints
+    hyperglass will query for information.
 </Callout>
 
 ## Simple Device Configuration
@@ -18,12 +18,15 @@ Create a file called `devices.yaml` in the directory `/etc/hyperglass`.
 
 ```yaml filename="devices.yaml"
 devices:
-  - name: NYC Router 1
-    address: <IP address hyperglass will use to log into the router>
-    credential:
-      username: <Username hyperglass will use to log into the router>
-      password: <Password hyperglass will use to log into the router>
-    platform: cisco_ios
+    - name: NYC Router 1
+      address: <IP address hyperglass will use to log into the router>
+      credential:
+          username: <Username hyperglass will use to log into the router>
+          password: <Password hyperglass will use to log into the router>
+      platform: cisco_ios
+      attrs:
+          source4: <IPv4 address from which to source ping & traceroute commands>
+          source6: <IPv4 address from which to source ping & traceroute commands>
 ```
 
 That's it!

docs/pages/installation.mdx

@@ -5,6 +5,64 @@ description: Installing hyperglass
 
 import { Callout, Tab, Tabs } from 'nextra-theme-docs';
 
+## Docker
+<Callout type="info">
+**Docker is the recommended method for running hyperglass.**
+</Callout>
+
+### 1. [Install Docker](https://docs.docker.com/engine/install/)
+
+### 2. Download hyperglass
+
+```shell copy
+mkdir /etc/hyperglass
+cd /opt
+git clone https://github.com/thatmattlove/hyperglass/tree/v2.0.0 --depth=1
+```
+
+### Quickstart (optional)
+
+Do this if you just want to see the hyperglass page working with a fake device.
+
+```shell copy
+cp /opt/hyperglass/.samples/sample_devices.yaml /etc/hyperglass/devices.yaml
+cd /opt/hyperglass
+docker compose up
+```
+
+Navigate to http://localhost:8001
+
+### 3. Setup Reverse Proxy
+
+[Caddy](https://caddyserver.com) is recommended, but any reverse proxy ([NGINX](https://www.nginx.com), [Apache2](https://httpd.apache.org)) will work.
+
+#### Caddy
+
+[**Install Caddy**](https://caddyserver.com/docs/install)
+
+```shell copy
+cp /opt/hyperglass/.samples/Caddyfile /etc/caddy/Caddyfile
+```
+
+Change the `lg.example.com` and `[email protected]` values to match your hyperglass FQDN and email address (the email address is for automatic SSL certificate generation via Let's Encrypt).
+
+<Callout type="info">
+If you prefer to use other Let's Encrypt validation methods or your own SSL certificate, modify your `/etc/hyperglass/Caddyfile` in accordance with the [Caddy docs](https://caddyserver.com/docs/caddyfile-tutorial).
+</Callout>
+
+Restart the Caddy service: `systemctl restart caddy{:shell}`
+
+#### NGINX
+
+```shell copy
+cp /opt/hyperglass/.samples/hyperglass.nginx /etc/nginx/sites-available/hyperglass
+ln -s /etc/nginx/sites-available/hyperglass /etc/nginx/sites-enabled/hyperglass
+```
+
+Change the `lg.example.com` value to match your hyperglass FQDN.
+
+Change the `<path to cert chain>` and `<path to key>` values to match the path to your certificate and private key files.
+
 ## Automatic installation
 
 If your system runs on:

docs/pages/installation/_meta.json

@@ -0,0 +1,6 @@
+{
+  "docker": "Using Docker",
+  "manual": "Manual Installation",
+  "environment-variables": "Environment Variables",
+  "reverse-proxy": "Reverse Proxy"
+}

docs/pages/installation/docker.mdx

@@ -0,0 +1,54 @@
+---
+title: Using Docker
+description: Installing hyperglass with Docker
+---
+
+import { Button } from "nextra/components";
+import { Callout } from "nextra-theme-docs";
+
+## Docker
+
+<Callout type="info">**Docker is the recommended method for running hyperglass.**</Callout>
+
+### 1. Install Docker
+
+<Button className="nx-my-4 nx-py-2 nx-px-4 nx-font-bold">
+    <a target="_blank" href="https://docs.docker.com/engine/install/">
+        Docker Engine Installation Guide
+    </a>
+</Button>
+
+### 2. Download hyperglass
+
+```shell copy
+mkdir /etc/hyperglass
+cd /opt
+git clone https://github.com/thatmattlove/hyperglass/tree/v2.0.0 --depth=1
+```
+
+### Optional: Quickstart
+
+Do this if you just want to see the hyperglass page working with a fake device.
+
+```shell copy
+cp /opt/hyperglass/.samples/sample_devices.yaml /etc/hyperglass/devices.yaml
+cd /opt/hyperglass
+docker compose up
+```
+
+Navigate to http://localhost:8001
+
+### 3. Create a `systemd` service
+
+<Callout type="info">
+    Before you create and start the hyperglass service, you may want to verify whether or not you
+    intend to change any [environment variables](environment-variables.mdx) and change them first.
+</Callout>
+
+```shell copy
+cp /opt/hyperglass/.samples/hyperglass-docker.service /etc/hyperglass/hyperglass.service
+ln -s /etc/hyperglass/hyperglass.service /etc/systemd/system/hyperglass.service
+systemctl daemon-reload
+systemctl enable hyperglass
+systemctl start hyperglass
+```

docs/pages/installation/environment-variables.mdx

@@ -0,0 +1,22 @@
+---
+title: Environment Variables
+description: hyperglass environment variables
+---
+
+There are some configuration variables that must be supplied before hyperglass can start or read its configuration files. Most of the time, you should not need to modify these.
+
+Environment variables may be overridden at the command line, or by placing them in `${HYPERGLASS_APP_PATH}/hyperglass.env`.
+
+| Variable Name               | Type    | Default           | Description                                                                                                        |
+| :-------------------------- | :------ | :---------------- | :----------------------------------------------------------------------------------------------------------------- |
+| `HYPERGLASS_DEBUG`          | boolean | `false`           | Enable debug logging                                                                                               |
+| `HYPERGLASS_DEV_MODE`       | boolean | `false`           | Enable developer mode. This should only be used if you are developing hyperglass under specific circumstances.     |
+| `HYPERGLASS_DISABLE_UI`     | boolean | `false`           | If set to `true`, the hyperglass UI is not built or served. The only way to access hyperglass is via REST API.     |
+| `HYPERGLASS_APP_PATH`       | string  | `/etc/hyperglass` | Directory where hyperglass configuration files and static web UI files are contained.                              |
+| `HYPERGLASS_REDIS_HOST`     | string  | `localhost`       | Host on which Redis is running.                                                                                    |
+| `HYPERGLASS_REDIS_PASSWORD` | string  | —                 | Redis password, if any.                                                                                            |
+| `HYPERGLASS_REDIS_DB`       | number  | `1`               | Redis database number.                                                                                             |
+| `HYPERGLASS_REDIS_DSN`      | string  | —                 | Redis DSN. If supplied, overrides `HYPERGLASS_REDIS_HOST`, `HYPERGLASS_REDIS_DB`, and `HYPERGLASS_REDIS_PASSWORD`. |
+| `HYPERGLASS_HOST`           | string  | `[::1]`           | Address on which hyperglass listens for requests.                                                                  |
+| `HYPERGLASS_PORT`           | number  | `8001`            | TCP port on which hyperglass listens for requests.                                                                 |
+| `HYPERGLASS_CA_CERT`        | string  | —                 | Path to CA certificate file for validating HTTPS certificates. If not supplied, system CAs are used.               |