xevion/glance
1
0
Fork 0
mirror of https://github.com/Xevion/glance.git synced 2025-12-05 23:15:06 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'dev' into Add-support-configure-docker-containers-yaml

Browse Source
This commit is contained in:
Svilen Markov
2025-04-26 17:44:34 +01:00
committed by GitHub
parent bba2c5b20c 18436e91e0
commit 306c28f203
65 changed files with 3752 additions and 2458 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
docs/configuration.md
View File

@@ -4,12 +4,13 @@
- [The config file](#the-config-file)
- [Auto reload](#auto-reload)
- [Environment variables](#environment-variables)
- [Other ways of providing tokens/passwords/secrets](#other-ways-of-providing-tokenspasswordssecrets)
- [Including other config files](#including-other-config-files)
- [Server](#server)
- [Document](#document)
- [Branding](#branding)
- [Theme](#theme)
- [Themes](#themes)
- [Available themes](#available-themes)
- [Pages & Columns](#pages--columns)
- [Widgets](#widgets)
- [RSS](#rss)
@@ -92,6 +93,38 @@ If you need to use the syntax `${NAME}` in your config without it being interpre
something: \${NOT_AN_ENV_VAR}
```
#### Other ways of providing tokens/passwords/secrets
You can use [Docker secrets](https://docs.docker.com/compose/how-tos/use-secrets/) with the following syntax:
```yaml
# This will be replaced with the contents of the file /run/secrets/github_token
# so long as the secret `github_token` is provided to the container
token: ${secret:github_token}
```
Alternatively, you can load the contents of a file who's path is provided by an environment variable:
`docker-compose.yml`
```yaml
services:
glance:
image: glanceapp/glance
environment:
- TOKEN_FILE=/home/user/token
volumes:
- /home/user/token:/home/user/token
```
`glance.yml`
```yaml
token: ${readFileFromEnv:TOKEN_FILE}
```
> [!NOTE]
>
> The contents of the file will be stripped of any leading/trailing whitespace before being used.
### Including other config files
Including config files from within your main config file is supported. This is done via the `$include` directive along with a relative or absolute path to the file you want to include. If the path is relative, it will be relative to the main config file. Additionally, environment variables can be used within included files, and changes to the included files will trigger an automatic reload. Example:
@@ -235,6 +268,9 @@ branding:
<p>Powered by <a href="https://github.com/glanceapp/glance">Glance</a></p>
logo-url: /assets/logo.png
favicon-url: /assets/logo.png
app-name: "My Dashboard"
app-icon-url: "/assets/app-icon.png"
app-background-color: "#151519"
```
### Properties
@@ -246,6 +282,9 @@ branding:
| logo-text | string | no | G |
| logo-url | string | no | |
| favicon-url | string | no | |
| app-name | string | no | Glance |
| app-icon-url | string | no | Glance's default icon |
| app-background-color | string | no | Glance's default background color |
#### `hide-footer`
Hides the footer when set to `true`.
@@ -262,6 +301,15 @@ Specify a URL to a custom image to use instead of the "G" found in the navigatio
#### `favicon-url`
Specify a URL to a custom image to use for the favicon.
#### `app-name`
Specify the name of the web app shown in browser tab and PWA.
#### `app-icon-url`
Specify URL for PWA and browser tab icon (512x512 PNG).
#### `app-background-color`
Specify background color for PWA. Must be a valid CSS color.
## Theme
Theming is done through a top level `theme` property. Values for the colors are in [HSL](https://giggster.com/guide/basics/hue-saturation-lightness/) (hue, saturation, lightness) format. You can use a color picker [like this one](https://hslpicker.com/) to convert colors from other formats to HSL. The values are separated by a space and `%` is not required for any of the numbers.
@@ -274,7 +322,7 @@ theme:
contrast-multiplier: 1.1
```
### Themes
### Available themes
If you don't want to spend time configuring your own theme, there are [several available themes](themes.md) which you can simply copy the values for.
### Properties
@@ -359,22 +407,28 @@ pages:
| name | string | yes | |
| slug | string | no | |
| width | string | no | |
| desktop-navigation-width | string | no | |
| center-vertically | boolean | no | false |
| hide-desktop-navigation | boolean | no | false |
| expand-mobile-page-navigation | boolean | no | false |
| show-mobile-header | boolean | no | false |
| columns | array | yes | |
#### `title`
#### `name`
The name of the page which gets shown in the navigation bar.
#### `slug`
The URL friendly version of the title which is used to access the page. For example if the title of the page is "RSS Feeds" you can make the page accessible via `localhost:8080/feeds` by setting the slug to `feeds`. If not defined, it will automatically be generated from the title.
#### `width`
The maximum width of the page on desktop. Possible values are `slim` and `wide`.
The maximum width of the page on desktop. Possible values are `default`, `slim` and `wide`.
* default: `1600px` (when no value is specified)
#### `desktop-navigation-width`
The maximum width of the desktop navigation. Useful if you have a few pages that use a different width than the rest and don't want the navigation to jump abruptly when going to and away from those pages. Possible values are `default`, `slim` and `wide`.
Here are the pixel equivalents for each value:
* default: `1600px`
* slim: `1100px`
* wide: `1920px`
@@ -958,6 +1012,7 @@ Preview:
| search-engine | string | no | duckduckgo |
| new-tab | boolean | no | false |
| autofocus | boolean | no | false |
| target | string | no | _blank |
| placeholder | string | no | Type here to search… |
| bangs | array | no | |
@@ -968,6 +1023,10 @@ Either a value from the table below or a URL to a custom search engine. Use `{QU
| ---- | --- |
| duckduckgo | `https://duckduckgo.com/?q={QUERY}` |
| google | `https://www.google.com/search?q={QUERY}` |
| bing | `https://www.bing.com/search?q={QUERY}` |
| perplexity | `https://www.perplexity.ai/search?q={QUERY}` |
| kagi | `https://kagi.com/search?q={QUERY}` |
| startpage | `https://www.startpage.com/search?q={QUERY}` |
##### `new-tab`
When set to `true`, swaps the shortcuts for showing results in the same or new tab, defaulting to showing results in a new tab.
@@ -975,6 +1034,9 @@ When set to `true`, swaps the shortcuts for showing results in the same or new t
##### `autofocus`
When set to `true`, automatically focuses the search input on page load.
##### `target`
The target to use when opening the search results in a new tab. Possible values are `_blank`, `_self`, `_parent` and `_top`.
##### `placeholder`
When set, modifies the text displayed in the input field before typing.
@@ -1292,7 +1354,12 @@ Examples:
| ---- | ---- | -------- | ------- |
| url | string | yes | |
| headers | key (string) & value (string) | no | |
| method | string | no | GET |
| body-type | string | no | json |
| body | any | no | |
| frameless | boolean | no | false |
| allow-insecure | boolean | no | false |
| skip-json-validation | boolean | no | false |
| template | string | yes | |
| parameters | key (string) & value (string|array) | no | |
| subrequests | map of requests | no | |
@@ -1309,9 +1376,40 @@ headers:
Accept: application/json
```
##### `method`
The HTTP method to use when making the request. Possible values are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS` and `HEAD`.
##### `body-type`
The type of the body that will be sent with the request. Possible values are `json`, and `string`.
##### `body`
The body that will be sent with the request. It can be a string or a map. Example:
```yaml
body-type: json
body:
key1: value1
key2: value2
multiple-items:
- item1
- item2
```
```yaml
body-type: string
body: |
key1=value1&key2=value2
```
##### `frameless`
When set to `true`, removes the border and padding around the widget.
##### `allow-insecure`
Whether to ignore invalid/self-signed certificates.
##### `skip-json-validation`
When set to `true`, skips the JSON validation step. This is useful when the API returns JSON Lines/newline-delimited JSON, which is a format that consists of several JSON objects separated by newlines.
##### `template`
The template that will be used to display the data. It relies on Go's `html/template` package so it's recommended to go through [its documentation](https://pkg.go.dev/text/template) to understand how to do basic things such as conditionals, loops, etc. In addition, it also uses [tidwall's gjson](https://github.com/tidwall/gjson) package to parse the JSON data so it's worth going through its documentation if you want to use more advanced JSON selectors. You can view additional examples with explanations and function definitions [here](custom-api.md).
@@ -1381,6 +1479,7 @@ Display a widget provided by an external source (3rd party). If you want to lear
| url | string | yes | |
| fallback-content-type | string | no | |
| allow-potentially-dangerous-html | boolean | no | false |
| headers | key & value | no | |
| parameters | key & value | no | |
##### `url`
@@ -1389,6 +1488,14 @@ The URL of the extension. **Note that the query gets stripped from this URL and
##### `fallback-content-type`
Optionally specify the fallback content type of the extension if the URL does not return a valid `Widget-Content-Type` header. Currently the only supported value for this property is `html`.
##### `headers`
Optionally specify the headers that will be sent with the request. Example:
```yaml
headers:
x-api-key: ${SECRET_KEY}
```
##### `allow-potentially-dangerous-html`
Whether to allow the extension to display HTML.
@@ -1793,6 +1900,8 @@ If any of the child containers are down, their status will propagate up to the p
| hide-by-default | boolean | no | false |
| format-container-names | boolean | no | false |
| sock-path | string | no | /var/run/docker.sock |
| category | string | no | |
| running-only | boolean | no | false |
##### `hide-by-default`
Whether to hide the containers by default. If set to `true` you'll have to manually add a `glance.hide: false` label to each container you want to display. By default all containers will be shown and if you want to hide a specific container you can add a `glance.hide: true` label.
@@ -1801,7 +1910,59 @@ Whether to hide the containers by default. If set to `true` you'll have to manua
When set to `true`, automatically converts container names such as `container_name_1` into `Container Name 1`.
##### `sock-path`
The path to the Docker socket.
The path to the Docker socket. This can also be a [remote socket](https://docs.docker.com/engine/daemon/remote-access/) or proxied socket using something like [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy).
###### `category`
Filter to only the containers which have this category specified via the `glance.category` label. Useful if you want to have multiple containers widgets, each showing a different set of containers.
<details>
<summary>View example</summary>
<br>
```yaml
services:
jellyfin:
image: jellyfin/jellyfin:latest
labels:
glance.name: Jellyfin
glance.icon: si:jellyfin
glance.url: https://jellyfin.domain.com
glance.category: media
gitea:
image: gitea/gitea:latest
labels:
glance.name: Gitea
glance.icon: si:gitea
glance.url: https://gitea.domain.com
glance.category: dev-tools
vaultwarden:
image: vaultwarden/server:latest
labels:
glance.name: Vaultwarden
glance.icon: si:vaultwarden
glance.url: https://vaultwarden.domain.com
glance.category: dev-tools
```
Then you can use the `category` property to filter the containers:
```yaml
- type: docker-containers
title: Dev tool containers
category: dev-tools
- type: docker-containers
title: Media containers
category: media
```
</details>
##### `running-only`
Whether to only show running containers. If set to `true` only containers that are currently running will be displayed. If set to `false` all containers will be displayed regardless of their state.
#### Labels
| Name | Description |
@@ -1814,6 +1975,7 @@ The path to the Docker socket.
| glance.hide | Whether to hide the container. If set to `true` the container will not be displayed. Defaults to `false`. |
| glance.id | The custom ID of the container. Used to group containers under a single parent. |
| glance.parent | The ID of the parent container. Used to group containers under a single parent. |
| glance.category | The category of the container. Used to filter containers by category. |
### DNS Stats
Display statistics from a self-hosted ad-blocking DNS resolver such as AdGuard Home, Pi-hole, or Technitium.
@@ -1844,14 +2006,14 @@ Preview:
| allow-insecure | bool | no | false |
| url | string | yes | |
| username | string | when service is `adguard` | |
| password | string | when service is `adguard` | |
| password | string | when service is `adguard` or `pihole-v6` | |
| token | string | when service is `pihole` | |
| hide-graph | bool | no | false |
| hide-top-domains | bool | no | false |
| hour-format | string | no | 12h |
##### `service`
Either `adguard`, `pihole`, or `technitium`.
Either `adguard`, `technitium`, or `pihole` (major version 5 and below) or `pihole-v6` (major version 6 and above).
##### `allow-insecure`
Whether to allow invalid/self-signed certificates when making the request to the service.
@@ -1863,10 +2025,14 @@ The base URL of the service.
Only required when using AdGuard Home. The username used to log into the admin dashboard.
##### `password`
Only required when using AdGuard Home. The password used to log into the admin dashboard.
Required when using AdGuard Home, where the password is the one used to log into the admin dashboard.
Also required when using Pi-hole major version 6 and above, where the password is the one used to log into the admin dashboard or the application password, which can be found in `Settings -> Web Interface / API -> Configure app password`.
##### `token`
Only required when using Pi-hole or Technitium. For Pi-hole, the API token which can be found in `Settings -> API -> Show API token`; for Technitium, an API token can be generated at `Administration -> Sessions -> Create Token`.
Required when using Pi-hole major version 5 or earlier. The API token which can be found in `Settings -> API -> Show API token`.
Also required when using Technitium, an API token can be generated at `Administration -> Sessions -> Create Token`.
##### `hide-graph`
Whether to hide the graph showing the number of queries over time.
@@ -1931,7 +2097,7 @@ Whether to hide the swap usage.
| Name | Type | Required | Default |
| ---- | ---- | -------- | ------- |
| cpu-temp-sensor | string | no | |
| hide-mointpoints-by-default | boolean | no | false |
| hide-mountpoints-by-default | boolean | no | false |
| mountpoints | map\[string\]object | no | |
###### `cpu-temp-sensor`

73
docs/custom-api.md
View File

@@ -226,10 +226,10 @@ JSON response:
}
```
Calculations can be performed, however all numbers must be converted to floats first if they are not already:
Calculations can be performed on either ints or floats. If both numbers are ints, an int will be returned, otherwise a float will be returned. If you try to divide by zero, 0 will be returned. If you provide non-numeric values, `NaN` will be returned.
```html
<div>{{ sub (.JSON.Int "price" | toFloat) (.JSON.Int "discount" | toFloat) }}</div>
<div>{{ sub (.JSON.Int "price") (.JSON.Int "discount") }}</div>
```
Output:
@@ -309,6 +309,55 @@ You can also access the response headers:
<div>{{ .Response.Header.Get "Content-Type" }}</div>
```
<hr>
JSON response:
```json
{"name": "Steve", "age": 30}
{"name": "Alex", "age": 25}
{"name": "John", "age": 35}
```
The above format is "[ndjson](https://docs.mulesoft.com/dataweave/latest/dataweave-formats-ndjson)" or "[JSON Lines](https://jsonlines.org/)", where each line is a separate JSON object. To parse this format, you must first disable the JSON validation check in your config, since by default the response is expected to be a single valid JSON object:
```yaml
- type: custom-api
skip-json-validation: true
```
Then, to iterate over each object you can use `.JSONLines`:
```html
{{ range .JSONLines }}
<p>{{ .String "name" }} is {{ .Int "age" }} years old</p>
{{ end }}
```
Output:
```html
<p>Steve is 30 years old</p>
<p>Alex is 25 years old</p>
<p>John is 35 years old</p>
```
For other ways of selecting data from a JSON Lines response, have a look at the docs for [tidwall/gjson](https://github.com/tidwall/gjson/tree/master?tab=readme-ov-file#json-lines). For example, to get an array of all names, you can use the following:
```html
{{ range .JSON.Array "..#.name" }}
<p>{{ .String "" }}</p>
{{ end }}
```
Output:
```html
<p>Steve</p>
<p>Alex</p>
<p>John</p>
```
## Functions
The following functions are available on the `JSON` object:
@@ -325,13 +374,31 @@ The following helper functions provided by Glance are available:
- `toFloat(i int) float`: Converts an integer to a float.
- `toInt(f float) int`: Converts a float to an integer.
- `toRelativeTime(t time.Time) template.HTMLAttr`: Converts Time to a relative time such as 2h, 1d, etc which dynamically updates. **NOTE:** the value of this function should be used as an attribute in an HTML tag, e.g. `<span {{ toRelativeTime .Time }}></span>`.
- `parseTime(layout string, s string) time.Time`: Parses a string into time.Time. The layout must be provided in Go's [date format](https://pkg.go.dev/time#pkg-constants). You can alternatively use these values instead of the literal format: "RFC3339", "RFC3339Nano", "DateTime", "DateOnly", "TimeOnly".
- `now() time.Time`: Returns the current time.
- `offsetNow(offset string) time.Time`: Returns the current time with an offset. The offset can be positive or negative and must be in the format "3h" "-1h" or "2h30m10s".
- `duration(str string) time.Duration`: Parses a string such as `1h`, `24h`, `5h30m`, etc into a `time.Duration`.
- `parseTime(layout string, s string) time.Time`: Parses a string into time.Time. The layout must be provided in Go's [date format](https://pkg.go.dev/time#pkg-constants). You can alternatively use these values instead of the literal format: "unix", "RFC3339", "RFC3339Nano", "DateTime", "DateOnly".
- `parseLocalTime(layout string, s string) time.Time`: Same as the above, except in the absence of a timezone, it will use the local timezone instead of UTC.
- `parseRelativeTime(layout string, s string) time.Time`: A shorthand for `{{ .String "date" | parseTime "rfc3339" | toRelativeTime }}`.
- `add(a, b float) float`: Adds two numbers.
- `sub(a, b float) float`: Subtracts two numbers.
- `mul(a, b float) float`: Multiplies two numbers.
- `div(a, b float) float`: Divides two numbers.
- `formatApproxNumber(n int) string`: Formats a number to be more human-readable, e.g. 1000 -> 1k.
- `formatNumber(n float|int) string`: Formats a number with commas, e.g. 1000 -> 1,000.
- `trimPrefix(prefix string, str string) string`: Trims the prefix from a string.
- `trimSuffix(suffix string, str string) string`: Trims the suffix from a string.
- `trimSpace(str string) string`: Trims whitespace from a string on both ends.
- `replaceAll(old string, new string, str string) string`: Replaces all occurrences of a string in a string.
- `replaceMatches(pattern string, replacement string, str string) string`: Replaces all occurrences of a regular expression in a string.
- `findMatch(pattern string, str string) string`: Finds the first match of a regular expression in a string.
- `findSubmatch(pattern string, str string) string`: Finds the first submatch of a regular expression in a string.
- `sortByString(key string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by a string key in either ascending or descending order.
- `sortByInt(key string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by an integer key in either ascending or descending order.
- `sortByFloat(key string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by a float key in either ascending or descending order.
- `sortByTime(key string, layout string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by a time key in either ascending or descending order. The format must be provided in Go's [date format](https://pkg.go.dev/time#pkg-constants).
- `concat(strings ...string) string`: Concatenates multiple strings together.
- `unique(key string, arr []JSON) []JSON`: Returns a unique array of JSON objects based on the given key.
The following helper functions provided by Go's `text/template` are available:

3
docs/extensions.md
View File

@@ -26,6 +26,9 @@ If you know how to setup an HTTP server and a bit of HTML and CSS you're ready t
### `Widget-Title`
Used to specify the title of the widget. If not provided, the widget's title will be "Extension".
### `Widget-Title-URL`
Used to specify the URL that will be opened when the widget's title is clicked. If the user has specified a `title-url` in their config, it will take precedence over this header.
### `Widget-Content-Type`
Used to specify the content type that will be returned by the extension. If not provided, the content will be shown as plain text.

3
docs/glance.yml
View File

@@ -66,9 +66,6 @@ pages:
# hide-location: true
- type: markets
# The link to go to when clicking on the symbol in the UI,
# {SYMBOL} will be substituded with the symbol for each market
symbol-link-template: https://www.tradingview.com/symbols/{SYMBOL}/news
markets:
- symbol: SPY
name: S&P 500

BIN
docs/images/themes/dracula.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

11
docs/themes.md
View File

@@ -82,6 +82,17 @@ theme:
negative-color: 209 88 54
```
### Dracula
![screenshot](images/themes/dracula.png)
```yaml
theme:
background-color: 231 15 21
primary-color: 265 89 79
contrast-multiplier: 1.2
positive-color: 135 94 66
negative-color: 0 100 67
```
## Light
### Catppuccin Latte