From 1d845981b705859c1e809436422c115ce5c252f2 Mon Sep 17 00:00:00 2001 From: thcrt <110127860+thcrt@users.noreply.github.com> Date: Sun, 24 Nov 2024 22:37:56 +0100 Subject: [PATCH] Improve documentation --- README.md | 110 ++---------------- docs/configuration.md | 80 +++++++++++++ .../examples/blobdash.example.toml | 25 ++-- docs/examples/compose.example.yaml | 22 ++++ 4 files changed, 128 insertions(+), 109 deletions(-) create mode 100644 docs/configuration.md rename blobdash.example.toml => docs/examples/blobdash.example.toml (80%) create mode 100644 docs/examples/compose.example.yaml diff --git a/README.md b/README.md index a340241..8b6e461 100644 --- a/README.md +++ b/README.md @@ -10,112 +10,22 @@ ![GitHub Release](https://img.shields.io/github/v/release/thcrt/blobdash?style=for-the-badge) ![Free Palestine Badge](https://img.shields.io/badge/Free%20-%20Palestine%20-%20red?style=for-the-badge) - + ## Installation -Designed to be used with Docker and docker-compose. An example `compose.yaml`: +Designed to be used with Docker and docker-compose. An example `compose.yaml` file can be found at [`docs/examples/compose.example.yaml`](docs/examples/compose.example.yaml). -```yaml -services: - blobdash: - image: ghcr.io/thcrt/blobdash:latest # You should pin a version! - restart: unless-stopped - container_name: blobdash +## Configuration - volumes: - - ./blobdash.toml:/blobdash.toml - ports: # If using a reverse proxy, put it in the same network instead - - '80:8080' -``` +Blobdash uses [TOML](https://toml.io/) for configuration. It checks for a file named `blobdash.toml` +both in its working directory (in the Docker image, this is at `/app/blobdash.toml`) and in the root +directory (`/blobdash.toml`). If both are present, values in `/blobdash.toml` will override those +set in `/app/blobdash.toml`. -## Configuration reference - -Blobdash uses [TOML](https://toml.io/) for configuration. It checks for a file named `blobdash.toml` both in its working -directory (in the Docker image, this is at `/app/blobdash.toml`) and in the root directory -(`/blobdash.toml`). If both are present, values in `/blobdash.toml` will override those set in -`/app/blobdash.toml`. - -An example configuration file is present in this repository at [`blobdash.example.toml`](blobdash.example.toml). - -### `name` -The name of the dashboard, displayed throughout the application. - -### `logo` -The URL to fetch a logo from. Ensure it's properly formed, including an `https://` prefix. - -### `accent_color` -The color used as a secondary accent for various UI elements, including the title and graphs. This can be any [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value), such as `#ff00ff`, `oklch(70% 0.3 330)` or `magenta`. - -### `service_domain` -The base domain name at which you host your services. This is used on larger viewports to display the full domain name for each service. - -It can be overridden on a per-service level using `services..domain`. - -This does not have any functional effect, and is only for appearance purposes. If you don't want full domain names to show up, you can set it to the empty string `""`. - -### `about` -The HTML that will be shown to users who click the 'about' link in the sidebar. The TOML specification allows strings to span multiple lines by using three double-quotes (`"""`) at the beginning and end of the string, which may be useful for longer about sections. - -### `auth` -Blobdash is built to play nicely behind an authentication system that operates a reverse proxy, such as Authentik. Such a reverse proxy can provide blobdash with an HTTP header to identify a logged-in user. - -#### `auth.header` -The name of a header that is passed by the reverse proxy, which should be set to the username or display name of the user currently logged in. - -#### `auth.logout_url` -The URL to which users should be redirected when logging out, in order to invalidate their SSO session. - -### `dashdot` -Blobdash can integrate status dashboards from an existing [dashdot](https://getdashdot.com/) instance, displaying graphs on resource usage and availability. - -Note that graphs are displayed [using `iframe`s](https://getdashdot.com/docs/integration/widgets), and are not proxied, meaning that the user's device must be able to connect to the dashdot instance independently. Running a dashdot instance locally on your server in a way that only makes it available to blobdash and not externally visible will not work. - -#### `dashdot.enabled` -Whether to enable dashdot integration. - -#### `dashdot.host` -The hostname of the running dashdot instance. - -By default, this is set to `"https://dash.mauz.dev"`, a demo instance run by the developer of dashdot. Obviously, it doesn't reflect the actual status of your system when unchanged. - -#### `show_values` -Whether to display numerical values on the graphs. - -#### `widgets` -A list of the statistics that should be displayed as graphs. Allowed values can be seen at [dashdot's documentation](https://getdashdot.com/docs/integration/widgets#graph). At the time of writing, the list can contain: -- `"cpu"` -- `"storage"` -- `"ram"` -- `"network"` -- `"gpu"` - -Because these values are passed directly to your dashdot instance, and future updates to dashdot may result in new options becoming available, this option is deliberately not validated by blobdash itself. - -### `services` -The core of blobdash is that it lets you display links to the various services you host. These links are displayed as wide 'cards' on desktop viewports, but scaled down to 'apps' on small mobile viewports. Clicking on one will redirect the user to the URL of the service. - -Each service is its own entry under this top-level `services` key, where the key is an arbitrary identifier for the service and the value is another set of entries described below. - -#### `services..name` -The display name fo the service. - -#### `services..desc` -A description of the service, shown on larger viewports. - -#### `services..icon` -The URL to an icon representing the service. - -#### `services..url` -The URL at which the service is hosted, to which the user will be redirected when clicking it. - -#### `services..domain` **(Optional)** - -The base domain at which the service is hosted. For instance, if you host an instance of Paperless-ngx at `https://paperless.example.com`, you could set `services.paperless-ngx.name` to `"paperless"` and `services.paperless-ngx.domain` to `"example.com"`. - -This functionality is quite specific to my personal setup and may be subject to change in the future to make it more generally useful. - -This will default to the value `service_domain`, but can be overridden here. If you don't want to display a full domain name, you can set it to the empty string `""`. +An example configuration file is present in this repository at +[`docs/examples/blobdash.example.toml`](docs/examples/blobdash.example.toml). Documentation on the +configuration file is present at [`docs/configuration.md`](docs/configuration.md). diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..e224c59 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,80 @@ +# `blobdash.toml` + +## `name` +The name of the dashboard, displayed throughout the application. + +## `logo` +The URL to fetch a logo from. Ensure it's properly formed, including an `https://` prefix. + +## `accent_color` +The color used as a secondary accent for various UI elements, including the title and graphs. This can be any [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value), such as `#ff00ff`, `oklch(70% 0.3 330)` or `magenta`. + +## `service_domain` +The base domain name at which you host your services. This is used on larger viewports to display the full domain name for each service. + +It can be overridden on a per-service level using `services..domain`. + +This does not have any functional effect, and is only for appearance purposes. If you don't want full domain names to show up, you can set it to the empty string `""`. + +## `about` +The HTML that will be shown to users who click the 'about' link in the sidebar. The TOML specification allows strings to span multiple lines by using three double-quotes (`"""`) at the beginning and end of the string, which may be useful for longer about sections. + +## `auth` +Blobdash is built to play nicely behind an authentication system that operates a reverse proxy, such as Authentik. Such a reverse proxy can provide blobdash with an HTTP header to identify a logged-in user. + +### `auth.header` +The name of a header that is passed by the reverse proxy, which should be set to the username or display name of the user currently logged in. + +### `auth.logout_url` +The URL to which users should be redirected when logging out, in order to invalidate their SSO session. + +## `dashdot` +Blobdash can integrate status dashboards from an existing [dashdot](https://getdashdot.com/) instance, displaying graphs on resource usage and availability. + +Note that graphs are displayed [using `iframe`s](https://getdashdot.com/docs/integration/widgets), and are not proxied, meaning that the user's device must be able to connect to the dashdot instance independently. Running a dashdot instance locally on your server in a way that only makes it available to blobdash and not externally visible will not work. + +### `dashdot.enabled` +Whether to enable dashdot integration. + +### `dashdot.host` +The hostname of the running dashdot instance. + +By default, this is set to `"https://dash.mauz.dev"`, a demo instance run by the developer of dashdot. Obviously, it doesn't reflect the actual status of your system when unchanged. + +### `show_values` +Whether to display numerical values on the graphs. + +### `widgets` +A list of the statistics that should be displayed as graphs. Allowed values can be seen at [dashdot's documentation](https://getdashdot.com/docs/integration/widgets#graph). At the time of writing, the list can contain: +- `"cpu"` +- `"storage"` +- `"ram"` +- `"network"` +- `"gpu"` + +Because these values are passed directly to your dashdot instance, and future updates to dashdot may result in new options becoming available, this option is deliberately not validated by blobdash itself. + +## `services` +The core of blobdash is that it lets you display links to the various services you host. These links are displayed as wide 'cards' on desktop viewports, but scaled down to 'apps' on small mobile viewports. Clicking on one will redirect the user to the URL of the service. + +Each service is its own entry under this top-level `services` key, where the key is an arbitrary identifier for the service and the value is another set of entries described below. + +### `services..name` +The display name fo the service. + +### `services..desc` +A description of the service, shown on larger viewports. + +### `services..icon` +The URL to an icon representing the service. + +### `services..url` +The URL at which the service is hosted, to which the user will be redirected when clicking it. + +### `services..domain` **(Optional)** + +The base domain at which the service is hosted. For instance, if you host an instance of Paperless-ngx at `https://paperless.example.com`, you could set `services.paperless-ngx.name` to `"paperless"` and `services.paperless-ngx.domain` to `"example.com"`. + +This functionality is quite specific to my personal setup and may be subject to change in the future to make it more generally useful. + +This will default to the value `service_domain`, but can be overridden here. If you don't want to display a full domain name, you can set it to the empty string `""`. diff --git a/blobdash.example.toml b/docs/examples/blobdash.example.toml similarity index 80% rename from blobdash.example.toml rename to docs/examples/blobdash.example.toml index bd3b52d..273608c 100644 --- a/blobdash.example.toml +++ b/docs/examples/blobdash.example.toml @@ -1,5 +1,12 @@ +# blobdash.example.toml +# +# This is an example configuration file for blobdash (https://github.com/thcrt/blobdash). +# +# To get started quickly, copy it to `blobdash.toml`, make edits and bind mount it to your blobdash +# container. + name = "mydash" -logo = "https://www.pngmart.com/files/11/Rickrolling-PNG-Pic.png" +logo = "https://raw.githubusercontent.com/thcrt/blobdash/refs/heads/main/src/blobdash/static/blobcat.png" accent_color = "#dc2626" service_domain = "example.com" @@ -16,7 +23,7 @@ about = """ [auth] header = "X-App-User" -logout_url = "https://example.com" +logout_url = "#" [dashdot] enabled = true @@ -32,42 +39,42 @@ widgets = [ name = "librarian" desc = "read ebooks" icon = "https://cdn.jsdelivr.net/gh/selfhst/icons/png/calibre-web.png" -url = "https://google.com" +url = "#" [services.drawio] name = "draw" desc = "create drawings and diagrams" icon = "https://cdn.jsdelivr.net/gh/selfhst/icons/png/draw-io.png" -url = "https://google.com" +url = "#" [services.grocy] name = "food" desc = "plan meals and track ingredients" icon = "https://cdn.jsdelivr.net/gh/selfhst/icons/png/grocy.png" -url = "https://google.com" +url = "#" [services.homeassistant] name = "home" domain = "internal.example.com" desc = "control heaters, curtains and lights" icon = "https://cdn.jsdelivr.net/gh/selfhst/icons/png/home-assistant.png" -url = "https://google.com" +url = "#" [services.immich] name = "photos" desc = "maintain a photo library" icon = "https://cdn.jsdelivr.net/gh/selfhst/icons/png/immich.png" -url = "https://google.com" +url = "#" [services.jellyfin] name = "flix" domain = "seedbox.example.com" desc = "watch movies and tv" icon = "https://cdn.jsdelivr.net/gh/selfhst/icons/png/jellyfin.png" -url = "https://google.com" +url = "#" [services.paperless-ngx] name = "paper" desc = "archive important documents" icon = "https://cdn.jsdelivr.net/gh/selfhst/icons/png/paperless-ngx.png" -url = "https://google.com" +url = "#" diff --git a/docs/examples/compose.example.yaml b/docs/examples/compose.example.yaml new file mode 100644 index 0000000..65b617c --- /dev/null +++ b/docs/examples/compose.example.yaml @@ -0,0 +1,22 @@ +services: + server: + image: ghcr.io/thcrt/blobdash:latest # Pin a version! + restart: unless-stopped + + volumes: + - ./blobdash.toml:/blobdash.toml + ports: + - '80:8080' + + # Example of dashdot integration + dashdot: + image: mauricenino/dashdot:latest + restart: unless-stopped + privileged: true + + volumes: + - /:/mnt/host:ro + ports: + - '8080:3001' + environment: + DASHDOT_ALWAYS_SHOW_PERCENTAGES: "true"