Update config docs
This commit is contained in:
Svilen Markov
parent
e495fbfd99
commit
24a6107171
16 changed files with 584 additions and 186 deletions
|
|
@ -1,8 +1,12 @@
|
|||
# Configuration
|
||||
# Configuring Glance
|
||||
|
||||
- [Intro](#intro)
|
||||
- [Preconfigured page](#preconfigured-page)
|
||||
- [The config file](#the-config-file)
|
||||
- [Auto reload](#auto-reload)
|
||||
- [Environment variables](#environment-variables)
|
||||
- [Including other config files](#including-other-config-files)
|
||||
- [Server](#server)
|
||||
- [Document](#document)
|
||||
- [Branding](#branding)
|
||||
- [Theme](#theme)
|
||||
- [Themes](#themes)
|
||||
|
|
@ -21,10 +25,13 @@
|
|||
- [Weather](#weather)
|
||||
- [Monitor](#monitor)
|
||||
- [Releases](#releases)
|
||||
- [Docker Containers](#docker-containers)
|
||||
- [DNS Stats](#dns-stats)
|
||||
- [Server Stats](#server-stats)
|
||||
- [Repository](#repository)
|
||||
- [Bookmarks](#bookmarks)
|
||||
- [Calendar](#calendar)
|
||||
- [Calendar (legacy)](#calendar-legacy)
|
||||
- [ChangeDetection.io](#changedetectionio)
|
||||
- [Clock](#clock)
|
||||
- [Markets](#markets)
|
||||
|
|
@ -32,90 +39,115 @@
|
|||
- [Twitch Top Games](#twitch-top-games)
|
||||
- [iframe](#iframe)
|
||||
- [HTML](#html)
|
||||
- [Docker](#docker)
|
||||
|
||||
## Intro
|
||||
<!-- TODO: update -->
|
||||
Configuration is done via a single YAML file and a server restart is required in order for any changes to take effect. Trying to start the server with an invalid config file will result in an error.
|
||||
|
||||
## Preconfigured page
|
||||
If you don't want to spend time reading through all the available configuration options and just want something to get you going quickly you can use the following `glance.yml` and make changes as you see fit:
|
||||
|
||||
```yaml
|
||||
pages:
|
||||
- name: Home
|
||||
columns:
|
||||
- size: small
|
||||
widgets:
|
||||
- type: calendar
|
||||
|
||||
- type: rss
|
||||
limit: 10
|
||||
collapse-after: 3
|
||||
cache: 3h
|
||||
feeds:
|
||||
- url: https://ciechanow.ski/atom.xml
|
||||
- url: https://www.joshwcomeau.com/rss.xml
|
||||
title: Josh Comeau
|
||||
- url: https://samwho.dev/rss.xml
|
||||
- url: https://awesomekling.github.io/feed.xml
|
||||
- url: https://ishadeed.com/feed.xml
|
||||
title: Ahmad Shadeed
|
||||
|
||||
- type: twitch-channels
|
||||
channels:
|
||||
- theprimeagen
|
||||
- cohhcarnage
|
||||
- christitustech
|
||||
- blurbs
|
||||
- asmongold
|
||||
- jembawls
|
||||
|
||||
- size: full
|
||||
widgets:
|
||||
- type: hacker-news
|
||||
|
||||
- type: videos
|
||||
channels:
|
||||
- UCR-DXc1voovS8nhAvccRZhg # Jeff Geerling
|
||||
- UCv6J_jJa8GJqFwQNgNrMuww # ServeTheHome
|
||||
- UCOk-gHyjcWZNj3Br4oxwh0A # Techno Tim
|
||||
|
||||
- type: reddit
|
||||
subreddit: selfhosted
|
||||
|
||||
- size: small
|
||||
widgets:
|
||||
- type: weather
|
||||
location: London, United Kingdom
|
||||
|
||||
- type: markets
|
||||
markets:
|
||||
- symbol: SPY
|
||||
name: S&P 500
|
||||
- symbol: BTC-USD
|
||||
name: Bitcoin
|
||||
- symbol: NVDA
|
||||
name: NVIDIA
|
||||
- symbol: AAPL
|
||||
name: Apple
|
||||
- symbol: MSFT
|
||||
name: Microsoft
|
||||
- symbol: GOOGL
|
||||
name: Google
|
||||
- symbol: AMD
|
||||
name: AMD
|
||||
- symbol: RDDT
|
||||
name: Reddit
|
||||
```
|
||||
|
||||
This will give you a page that looks like the following:
|
||||
If you don't want to spend time reading through all the available configuration options and just want something to get you going quickly you can use [this `glance.yml` file](glance.yml) and make changes to it as you see fit. It will give you a page that looks like the following:
|
||||
|
||||
|
||||
|
||||
Configure the widgets, add more of them, add extra pages, etc. Make it your own!
|
||||
|
||||
<!-- TODO: update - add information about top level document key -->
|
||||
## The config file
|
||||
|
||||
### Auto reload
|
||||
Automatic config reload is supported, meaning that you can make changes to the config file and have them take effect on save without having to restart the container/service. Making changes to environment variables does not trigger a reload and requires manual restart. Deleting a config file will stop that file from being watched, even if it is recreated.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> If you attempt to start Glance with an invalid config it will exit with an error outright. If you successfully started Glance with a valid config and then made changes to it which result in an error, you'll see that error in the console and Glance will continue to run with the old configuration. You can then continue to make changes and when there are no errors the new configuration will be loaded.
|
||||
|
||||
> [!CAUTION]
|
||||
>
|
||||
> Reloading the configuration file clears your cached data, meaning that you have to request the data anew each time you do this. This can lead to rate limiting for some APIs if you do it too frequently. Having a cache that persists between reloads will be added in the future.
|
||||
|
||||
### Environment variables
|
||||
Inserting environment variables is supported anywhere in the config. This is done via the `${ENV_VAR}` syntax. Attempting to use an environment variable that doesn't exist will result in an error and Glance will either not start or load your new config on save. Example:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
host: ${HOST}
|
||||
port: ${PORT}
|
||||
```
|
||||
|
||||
Can also be in the middle of a string:
|
||||
|
||||
```yaml
|
||||
- type: rss
|
||||
title: ${RSS_TITLE}
|
||||
feeds:
|
||||
- url: http://domain.com/rss/${RSS_CATEGORY}.xml
|
||||
```
|
||||
|
||||
Works with any type of value, not just strings:
|
||||
|
||||
```yaml
|
||||
- type: rss
|
||||
limit: ${RSS_LIMIT}
|
||||
```
|
||||
|
||||
If you need to use the syntax `${NAME}` in your config without it being interpreted as an environment variable, you can escape it by prefixing with a backslash `\`:
|
||||
|
||||
```yaml
|
||||
something: \${NOT_AN_ENV_VAR}
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```yaml
|
||||
pages:
|
||||
!include home.yml
|
||||
!include videos.yml
|
||||
!include homelab.yml
|
||||
```
|
||||
|
||||
The file you are including should not have any additional indentation, its values should be at the top level and the appropriate amount of indentation will be added automatically depending on where the file is included. Example:
|
||||
|
||||
`glance.yml`
|
||||
|
||||
```yaml
|
||||
pages:
|
||||
- name: Home
|
||||
columns:
|
||||
- size: full
|
||||
widgets:
|
||||
!include rss.yml
|
||||
- name: News
|
||||
columns:
|
||||
- size: full
|
||||
widgets:
|
||||
- type: group
|
||||
widgets:
|
||||
!include rss.yml
|
||||
- type: reddit
|
||||
subreddit: news
|
||||
```
|
||||
|
||||
`rss.yml`
|
||||
|
||||
```yaml
|
||||
- type: rss
|
||||
title: News
|
||||
feeds:
|
||||
- url: ${RSS_URL}
|
||||
```
|
||||
|
||||
The `!include` directive can be used anywhere in the config file, not just in the `pages` property, however it must be on its own line and have the appropriate indentation.
|
||||
|
||||
If you encounter YAML parsing errors when using the `!include` directive, the reported line numbers will likely be incorrect. This is because the inclusion of files is done before the YAML is parsed, as YAML itself does not support file inclusion. To help with debugging in cases like this, you can use the `config:print` command and pipe it into `less -N` to see the full config file with includes resolved and line numbers added:
|
||||
|
||||
```sh
|
||||
glance --config /path/to/glance.yml config:print | less -N
|
||||
```
|
||||
|
||||
This is a bit more convoluted when running Glance inside a Docker container:
|
||||
|
||||
```sh
|
||||
docker run --rm -v ./glance.yml:/app/config/glance.yml glanceapp/glance config:print | less -N
|
||||
```
|
||||
|
||||
This assumes that the config you want to print is in your current working directory and is named `glance.yml`.
|
||||
|
||||
## Server
|
||||
Server configuration is done through a top level `server` property. Example:
|
||||
|
|
@ -185,6 +217,15 @@ To be able to point to an asset from your assets path, use the `/assets/` path l
|
|||
icon: /assets/gitea-icon.png
|
||||
```
|
||||
|
||||
## Document
|
||||
If you want to insert custom HTML into the `<head>` of the document for all pages, you can do so by using the `document` property. Example:
|
||||
|
||||
```yaml
|
||||
document:
|
||||
head: |
|
||||
<script src="/assets/custom.js"></script>
|
||||
```
|
||||
|
||||
## Branding
|
||||
You can adjust the various parts of the branding through a top level `branding` property. Example:
|
||||
|
||||
|
|
@ -1016,65 +1057,261 @@ Example:
|
|||
```
|
||||
|
||||
### Split Column
|
||||
<!-- TODO: update -->
|
||||
Splits a full sized column in half, allowing you to place widgets side by side. This is converted to a single column on mobile devices or if not enough width is available. Widgets are defined using a `widgets` property exactly as you would on a page column.
|
||||
Splits a full sized column in half, allowing you to place widgets side by side horizontally. This is converted to a single column on mobile devices or if not enough width is available. Widgets are defined using a `widgets` property exactly as you would on a page column.
|
||||
|
||||
Example of a full page with an effective 4 column layout using two split column widgets inside of two full sized columns:
|
||||
Two widgets side by side in a `full` column:
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>View config</summary>
|
||||
<summary>View <code>glance.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
shared:
|
||||
- &reddit-props
|
||||
type: reddit
|
||||
collapse-after: 4
|
||||
show-thumbnails: true
|
||||
# ...
|
||||
- size: full
|
||||
widgets:
|
||||
- type: split-column
|
||||
widgets:
|
||||
- type: hacker-news
|
||||
collapse-after: 3
|
||||
- type: lobsters
|
||||
collapse-after: 3
|
||||
|
||||
- type: videos
|
||||
# ...
|
||||
```
|
||||
</details>
|
||||
<br>
|
||||
|
||||
You can also achieve a number of different full page layouts using just this widget, such as:
|
||||
|
||||
3 column layout where all columns have equal width:
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>View <code>glance.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
pages:
|
||||
- name: Split Column Demo
|
||||
- name: Home
|
||||
columns:
|
||||
- size: full
|
||||
widgets:
|
||||
- type: split-column
|
||||
max-columns: 3
|
||||
widgets:
|
||||
- type: reddit
|
||||
subreddit: selfhosted
|
||||
collapse-after: 15
|
||||
- type: reddit
|
||||
subreddit: homelab
|
||||
collapse-after: 15
|
||||
- type: reddit
|
||||
subreddit: sysadmin
|
||||
collapse-after: 15
|
||||
```
|
||||
</details>
|
||||
<br>
|
||||
|
||||
4 column layout where all columns have equal width (and the page is set to `width: wide`):
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>View <code>glance.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
pages:
|
||||
- name: Home
|
||||
width: wide
|
||||
columns:
|
||||
- size: full
|
||||
widgets:
|
||||
- type: split-column
|
||||
max-columns: 4
|
||||
widgets:
|
||||
- subreddit: gaming
|
||||
<<: *reddit-props
|
||||
- subreddit: worldnews
|
||||
<<: *reddit-props
|
||||
- subreddit: lifeprotips
|
||||
<<: *reddit-props
|
||||
show-thumbnails: false
|
||||
- subreddit: askreddit
|
||||
<<: *reddit-props
|
||||
show-thumbnails: false
|
||||
- type: reddit
|
||||
subreddit: selfhosted
|
||||
collapse-after: 15
|
||||
- type: reddit
|
||||
subreddit: homelab
|
||||
collapse-after: 15
|
||||
- type: reddit
|
||||
subreddit: linux
|
||||
collapse-after: 15
|
||||
- type: reddit
|
||||
subreddit: sysadmin
|
||||
collapse-after: 15
|
||||
```
|
||||
</details>
|
||||
<br>
|
||||
|
||||
Masonry layout with up to 5 columns where all columns have equal width (and the page is set to `width: wide`):
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>View <code>glance.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
define:
|
||||
- &subreddit-settings
|
||||
type: reddit
|
||||
collapse-after: 5
|
||||
|
||||
pages:
|
||||
- name: Home
|
||||
width: wide
|
||||
columns:
|
||||
- size: full
|
||||
widgets:
|
||||
- type: split-column
|
||||
max-columns: 5
|
||||
widgets:
|
||||
- subreddit: todayilearned
|
||||
<<: *reddit-props
|
||||
collapse-after: 2
|
||||
- subreddit: aww
|
||||
<<: *reddit-props
|
||||
- subreddit: science
|
||||
<<: *reddit-props
|
||||
- subreddit: showerthoughts
|
||||
<<: *reddit-props
|
||||
show-thumbnails: false
|
||||
- subreddit: selfhosted
|
||||
<<: *subreddit-settings
|
||||
- subreddit: homelab
|
||||
<<: *subreddit-settings
|
||||
- subreddit: linux
|
||||
<<: *subreddit-settings
|
||||
- subreddit: sysadmin
|
||||
<<: *subreddit-settings
|
||||
- subreddit: DevOps
|
||||
<<: *subreddit-settings
|
||||
- subreddit: Networking
|
||||
<<: *subreddit-settings
|
||||
- subreddit: DataHoarding
|
||||
<<: *subreddit-settings
|
||||
- subreddit: OpenSource
|
||||
<<: *subreddit-settings
|
||||
- subreddit: Privacy
|
||||
<<: *subreddit-settings
|
||||
- subreddit: FreeSoftware
|
||||
<<: *subreddit-settings
|
||||
```
|
||||
</details>
|
||||
<br>
|
||||
|
||||
Just like the `group` widget, you can insert any widget type, you can even insert a `group` widget inside of a `split-column` widget, but you can't insert a `split-column` widget inside of a `group` widget.
|
||||
|
||||
|
||||
### Custom API
|
||||
|
||||
Display data from a JSON API using a custom template.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> The configuration of this widget requires some basic knowledge of programming, HTML, CSS, the Go template language and Glance-specific concepts.
|
||||
|
||||
Examples:
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>View <code>glance.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
title: Random Fact
|
||||
cache: 6h
|
||||
url: https://uselessfacts.jsph.pl/api/v2/facts/random
|
||||
template: |
|
||||
<p class="size-h4 color-paragraph">{{ .JSON.String "text" }}</p>
|
||||
```
|
||||
</details>
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>View <code>glance.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
title: Immich stats
|
||||
cache: 1d
|
||||
url: https://${IMMICH_URL}/api/server/statistics
|
||||
headers:
|
||||
x-api-key: ${IMMICH_API_KEY}
|
||||
Accept: application/json
|
||||
template: |
|
||||
<div class="flex justify-between text-center">
|
||||
<div>
|
||||
<div class="color-highlight size-h3">{{ .JSON.Int "photos" | formatNumber }}</div>
|
||||
<div class="size-h6">PHOTOS</div>
|
||||
</div>
|
||||
<div>
|
||||
<div class="color-highlight size-h3">{{ .JSON.Int "videos" | formatNumber }}</div>
|
||||
<div class="size-h6">VIDEOS</div>
|
||||
</div>
|
||||
<div>
|
||||
<div class="color-highlight size-h3">{{ div (.JSON.Int "usage" | toFloat) 1073741824 | toInt | formatNumber }}GB</div>
|
||||
<div class="size-h6">USAGE</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
</details>
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>View <code>glance.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
- type: custom-api
|
||||
title: Steam Specials
|
||||
cache: 12h
|
||||
url: https://store.steampowered.com/api/featuredcategories?cc=us
|
||||
template: |
|
||||
<ul class="list list-gap-10 collapsible-container" data-collapse-after="5">
|
||||
{{ range .JSON.Array "specials.items" }}
|
||||
<li>
|
||||
<a class="size-h4 color-highlight block text-truncate" href="https://store.steampowered.com/app/{{ .Int "id" }}/">{{ .String "name" }}</a>
|
||||
<ul class="list-horizontal-text">
|
||||
<li>{{ div (.Int "final_price" | toFloat) 100 | printf "$%.2f" }}</li>
|
||||
{{ $discount := .Int "discount_percent" }}
|
||||
<li{{ if ge $discount 40 }} class="color-positive"{{ end }}>{{ $discount }}% off</li>
|
||||
</ul>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
</details>
|
||||
|
||||
<br>
|
||||
#### Properties
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| url | string | yes | |
|
||||
| headers | key (string) & value (string) | no | |
|
||||
| frameless | boolean | no | false |
|
||||
| template | string | yes | |
|
||||
|
||||
Preview:
|
||||
##### `url`
|
||||
The URL to fetch the data from. It must be accessible from the server that Glance is running on.
|
||||
|
||||
|
||||
##### `headers`
|
||||
Optionally specify the headers that will be sent with the request. Example:
|
||||
|
||||
### Custom API
|
||||
<!-- TODO -->
|
||||
```yaml
|
||||
headers:
|
||||
x-api-key: your-api-key
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
##### `frameless`
|
||||
When set to `true`, removes the border and padding around the widget.
|
||||
|
||||
##### `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://pkg.go.dev/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).
|
||||
|
||||
### Extension
|
||||
Display a widget provided by an external source (3rd party). If you want to learn more about developing extensions, checkout the [extensions documentation](extensions.md) (WIP).
|
||||
|
|
@ -1393,6 +1630,112 @@ The maximum number of releases to show.
|
|||
#### `collapse-after`
|
||||
How many releases are visible before the "SHOW MORE" button appears. Set to `-1` to never collapse.
|
||||
|
||||
### Docker Containers
|
||||
|
||||
Display the status of your Docker containers along with an icon and an optional short description.
|
||||
|
||||
|
||||
|
||||
```yaml
|
||||
- type: docker-containers
|
||||
hide-by-default: false
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> The widget requires access to `docker.sock`. If you're running Glance inside a container, this can be done by mounting the socket as a volume:
|
||||
>
|
||||
> ```yaml
|
||||
> services:
|
||||
> glance:
|
||||
> image: glanceapp/glance
|
||||
> volumes:
|
||||
> - /var/run/docker.sock:/var/run/docker.sock
|
||||
> ```
|
||||
|
||||
Configuration of the containers is done via labels applied to each container:
|
||||
|
||||
```yaml
|
||||
jellyfin:
|
||||
image: jellyfin/jellyfin:latest
|
||||
labels:
|
||||
glance.name: Jellyfin
|
||||
glance.icon: si:jellyfin
|
||||
glance.url: https://jellyfin.domain.com
|
||||
glance.description: Movies & shows
|
||||
```
|
||||
|
||||
For services with multiple containers you can specify a `glance.id` on the "main" container and `glance.parent` on each "child" container:
|
||||
|
||||
<details>
|
||||
<summary>View <code>docker-compose.yml</code></summary>
|
||||
<br>
|
||||
|
||||
```yaml
|
||||
servies:
|
||||
immich-server:
|
||||
image: ghcr.io/immich-app/immich-server
|
||||
labels:
|
||||
glance.name: Immich
|
||||
glance.icon: si:immich
|
||||
glance.url: https://immich.domain.com
|
||||
glance.description: Image & video management
|
||||
glance.id: immich
|
||||
|
||||
redis:
|
||||
image: docker.io/redis:6.2-alpine
|
||||
labels:
|
||||
glance.parent: immich
|
||||
glance.name: Redis
|
||||
|
||||
database:
|
||||
image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0
|
||||
labels:
|
||||
glance.parent: immich
|
||||
glance.name: DB
|
||||
|
||||
proxy:
|
||||
image: nginx:stable
|
||||
labels:
|
||||
glance.parent: immich
|
||||
glance.name: Proxy
|
||||
```
|
||||
</details>
|
||||
<br>
|
||||
|
||||
This will place all child containers under the `Immich` container when hovering over its icon:
|
||||
|
||||
|
||||
|
||||
If any of the child containers are down, their status will propagate up to the parent container:
|
||||
|
||||
|
||||
|
||||
#### Properties
|
||||
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| hide-by-default | boolean | no | false |
|
||||
| sock-path | string | no | /var/run/docker.sock |
|
||||
|
||||
##### `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.
|
||||
|
||||
##### `sock-path`
|
||||
The path to the Docker socket.
|
||||
|
||||
#### Labels
|
||||
| Name | Description |
|
||||
| ---- | ----------- |
|
||||
| glance.name | The name displayed in the UI. If not specified, the name of the container will be used. |
|
||||
| glance.icon | The icon displayed in the UI. Can be an external URL or an icon prefixed with si:, sh: or di: like with the bookmarks and monitor widgets |
|
||||
| glance.url | The URL that the user will be redirected to when clicking on the container. |
|
||||
| glance.same-tab | Whether to open the link in the same or a new tab. Default is `false`. |
|
||||
| glance.description | A short description displayed in the UI. Default is empty. |
|
||||
| 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. |
|
||||
|
||||
### DNS Stats
|
||||
Display statistics from a self-hosted ad-blocking DNS resolver such as AdGuard Home or Pi-hole.
|
||||
|
||||
|
|
@ -1455,6 +1798,106 @@ Whether to hide the list of top blocked domains.
|
|||
##### `hour-format`
|
||||
Whether to display the relative time in the graph in `12h` or `24h` format.
|
||||
|
||||
### Server Stats
|
||||
Display statistics such as CPU usage, memory usage and disk usage of the server Glance is running on or other servers.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
- type: server-stats
|
||||
servers:
|
||||
- type: local
|
||||
name: Services
|
||||
```
|
||||
|
||||
Preview:
|
||||
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> This widget is currently under development, some features might not function as expected or may change.
|
||||
|
||||
To display data from a remote server you need to have the Glance Agent running on that server. You can download the agent from [here](https://github.com/glanceapp/agent), though keep in mind that it is still in development and may not work as expected. Support for other providers such as Glances will be added in the future.
|
||||
|
||||
In the event that the CPU temperature goes over 80°C, a flame icon will appear next to the CPU. The progress indicators will also turn red (or the equivalent of your negative color) to hopefully grab your attention if anything is unusually high:
|
||||
|
||||
|
||||
|
||||
#### Properties
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| servers | array | no | |
|
||||
|
||||
##### `servers`
|
||||
If not provided it will display the statistics of the server Glance is running on.
|
||||
|
||||
##### Properties for both `local` and `remote` servers
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| type | string | yes | |
|
||||
| name | string | no | |
|
||||
| hide-swap | boolean | no | false |
|
||||
|
||||
###### `type`
|
||||
Whether to display statistics for the local server or a remote server. Possible values are `local` and `remote`.
|
||||
|
||||
###### `name`
|
||||
The name of the server which will be displayed on the widget. If not provided it will default to the server's hostname.
|
||||
|
||||
###### `hide-swap`
|
||||
Whether to hide the swap usage.
|
||||
|
||||
##### Properties for the `local` server
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| cpu-temp-sensor | string | no | |
|
||||
| mountpoints | map\[string\]object | no | |
|
||||
|
||||
###### `cpu-temp-sensor`
|
||||
The name of the sensor to use for the CPU temperature. When not provided the widget will attempt to find the correct one, if it fails to do so the temperature will not be displayed. To view the available sensors you can use `sensors` command.
|
||||
|
||||
###### `mountpoints`
|
||||
A map of mountpoints to display disk usage for. The key is the path to the mountpoint and the value is an object with optional properties. Example:
|
||||
|
||||
```yaml
|
||||
mountpoints:
|
||||
"/":
|
||||
name: Root
|
||||
"/mnt/data":
|
||||
name: Data
|
||||
"/boot/efi":
|
||||
hide: true
|
||||
```
|
||||
|
||||
##### Properties for each `mountpoint`
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| name | string | no | |
|
||||
| hide | boolean | no | false |
|
||||
|
||||
###### `name`
|
||||
The name of the mountpoint which will be displayed on the widget. If not provided it will default to the mountpoint's path.
|
||||
|
||||
###### `hide`
|
||||
Whether to hide this mountpoint from the widget.
|
||||
|
||||
##### Properties for `remote` servers
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| url | string | yes | |
|
||||
| token | string | no | |
|
||||
| timeout | string | no | 3s |
|
||||
|
||||
###### `url`
|
||||
The URL and port of the server to fetch the statistics from.
|
||||
|
||||
###### `token`
|
||||
The authentication token to use when fetching the statistics.
|
||||
|
||||
###### `timeout`
|
||||
The maximum time to wait for a response from the server. The value is a string and must be a number followed by one of s, m, h, d. Example: `10s` for 10 seconds, `1m` for 1 minute, etc
|
||||
|
||||
### Repository
|
||||
Display general information about a repository as well as a list of the latest open pull requests and issues.
|
||||
|
||||
|
|
@ -1699,7 +2142,7 @@ Example:
|
|||
|
||||
```yaml
|
||||
- type: calendar
|
||||
start-sunday: false
|
||||
first-day-of-week: monday
|
||||
```
|
||||
|
||||
Preview:
|
||||
|
|
@ -1708,6 +2151,33 @@ Preview:
|
|||
|
||||
#### Properties
|
||||
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| first-day-of-week | string | no | monday |
|
||||
|
||||
##### `first-day-of-week`
|
||||
The day of the week that the calendar starts on. All week days are available as possible values.
|
||||
|
||||
### Calendar (legacy)
|
||||
Display a calendar.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
- type: calendar-legacy
|
||||
start-sunday: false
|
||||
```
|
||||
|
||||
Preview:
|
||||
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> This widget is deprecated and may be removed in a future version.
|
||||
|
||||
#### Properties
|
||||
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| start-sunday | boolean | no | false |
|
||||
|
|
@ -1907,75 +2377,3 @@ Example:
|
|||
```
|
||||
|
||||
Note the use of `|` after `source:`, this allows you to insert a multi-line string.
|
||||
|
||||
### Docker Containers
|
||||
<!-- TODO: update -->
|
||||
The Docker widget allows you to monitor your Docker containers.
|
||||
To enable this feature, ensure that your setup provides access to the **docker.sock** file (also you may use a TCP connection).
|
||||
|
||||
Add the following to your `docker-compose` or `docker run` command to enable the Docker widget:
|
||||
|
||||
**Docker Example:**
|
||||
```bash
|
||||
docker run -d -p 8080:8080 \
|
||||
-v ./glance.yml:/app/glance.yml \
|
||||
-v /etc/timezone:/etc/timezone:ro \
|
||||
-v /etc/localtime:/etc/localtime:ro \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock:ro \
|
||||
glanceapp/glance
|
||||
```
|
||||
|
||||
**Docker Compose Example:**
|
||||
```yaml
|
||||
services:
|
||||
glance:
|
||||
image: glanceapp/glance
|
||||
volumes:
|
||||
- ./glance.yml:/app/glance.yml
|
||||
- /etc/timezone:/etc/timezone:ro
|
||||
- /etc/localtime:/etc/localtime:ro
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
ports:
|
||||
- 8080:8080
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
#### Configuration
|
||||
To integrate the Docker widget into your dashboard, include the following snippet in your `glance.yml` file:
|
||||
|
||||
```yaml
|
||||
- type: docker
|
||||
host-url: tcp://localhost:2375
|
||||
cache: 1m
|
||||
```
|
||||
|
||||
#### Properties
|
||||
|
||||
| Name | Type | Required | Default |
|
||||
| ---- | ---- | -------- | ------- |
|
||||
| host-url | string | no | `unix:///var/run/docker.sock` |
|
||||
|
||||
#### Leveraging Container Labels
|
||||
You can use container labels to control visibility, URLs, icons, and titles within the Docker widget. Add the following labels to your container configuration for enhanced customization:
|
||||
|
||||
```yaml
|
||||
labels:
|
||||
- "glance.enable=true" # Enable or disable visibility of the container (default: true)
|
||||
- "glance.title=Glance" # Optional friendly name (defaults to container name)
|
||||
- "glance.url=https://app.example.com" # Optional URL associated with the container
|
||||
- "glance.iconUrl=si:docker" # Optional URL to an image which will be used as the icon for the site
|
||||
|
||||
```
|
||||
|
||||
**Default Values:**
|
||||
|
||||
| Name | Default |
|
||||
|----------------|------------|
|
||||
| glance.enable | true |
|
||||
| glance.title | Container name |
|
||||
| glance.url | (none) |
|
||||
| glance.iconUrl | si:docker |
|
||||
|
||||
Preview:
|
||||
|
||||
|
||||
|
|
|
|||
BIN
docs/images/calendar-legacy-widget-preview.png
Normal file
BIN
docs/images/calendar-legacy-widget-preview.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 13 KiB |
BIN
docs/images/custom-api-preview-1.png
Normal file
BIN
docs/images/custom-api-preview-1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.9 KiB |
BIN
docs/images/custom-api-preview-2.png
Normal file
BIN
docs/images/custom-api-preview-2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 5.7 KiB |
BIN
docs/images/custom-api-preview-3.png
Normal file
BIN
docs/images/custom-api-preview-3.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
BIN
docs/images/docker-container-parent.png
Normal file
BIN
docs/images/docker-container-parent.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
BIN
docs/images/docker-container-parent2.png
Normal file
BIN
docs/images/docker-container-parent2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
BIN
docs/images/docker-containers-preview.png
Normal file
BIN
docs/images/docker-containers-preview.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 343 KiB After Width: | Height: | Size: 362 KiB |
BIN
docs/images/server-stats-flame-icon.png
Normal file
BIN
docs/images/server-stats-flame-icon.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 9.6 KiB |
BIN
docs/images/server-stats-preview.gif
Normal file
BIN
docs/images/server-stats-preview.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 200 KiB |
BIN
docs/images/split-column-widget-3-columns.png
Normal file
BIN
docs/images/split-column-widget-3-columns.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 146 KiB |
BIN
docs/images/split-column-widget-4-columns.png
Normal file
BIN
docs/images/split-column-widget-4-columns.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 181 KiB |
BIN
docs/images/split-column-widget-masonry.png
Normal file
BIN
docs/images/split-column-widget-masonry.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 325 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 328 KiB After Width: | Height: | Size: 339 KiB |
Loading…
Add table
Reference in a new issue