dominik/homepage-plus
1
0
Fork 0
mirror of https://github.com/DI0IK/homepage-plus.git synced 2025-07-20 11:39:49 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

add mkdocs

Browse source
This commit is contained in:
Ben Phelps 2023-09-29 21:01:11 +03:00
parent b215843b26
commit 47765ee05e
144 changed files with 4219 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/configs/bookmarks.md Normal file
View file

@ -0,0 +1,32 @@
---
title: Bookmarks
description: Bookmark Configuration
---
Bookmarks function much the same as [Services](services.md), in how groups and lists work. They're just much simpler, smaller, and contain no extra features other than being a link out.
The design of homepage expects `abbr` to be 2 letters, but is not otherwise forced.
You can also use an icon for bookmarks similar to the [options for service icons](services.md#icons). If both icon and abbreviation are supplied, the icon takes precedence.
By default, the description will use the hostname of the link, but you can override it with a custom description.
```yaml
- Developer:
- Github:
- abbr: GH
href: https://github.com/
- Social:
- Reddit:
- icon: reddit.png
href: https://reddit.com/
description: The front page of the internet
- Entertainment:
- YouTube:
- abbr: YT
href: https://youtube.com/
```
<img width="1000" alt="Bookmarks" src="https://user-images.githubusercontent.com/19408/269307009-d7e45885-230f-4e07-b421-9822017ae878.png">

17
docs/configs/custom-css-js.md Normal file
View file

@ -0,0 +1,17 @@
---
title: Custom CSS & JS
description: Adding Custom CSS or JS
---
As of version v0.6.30 homepage supports adding your own custom css & javascript. Please do so **at your own risk**.
To add custom css simply edit the `custom.css` file under your config directory, similarly for javascript you would edit `custom.js`. You can then target elements in homepage with various classes / ids to customize things to your liking.
You can also set a specific `id` for a service or bookmark to target with your custom css or javascript, e.g.
```yaml
Service:
id: myserviceid
icon: icon.png
...
```

205
docs/configs/docker.md Normal file
View file

@ -0,0 +1,205 @@
---
title: Docker
description: Docker Configuration
---
Docker instances are configured inside the `docker.yaml` file. Both IP:PORT and Socket connections are supported.
For IP:PORT, simply make sure your Docker instance [has been configured](https://gist.github.com/styblope/dc55e0ad2a9848f2cc3307d4819d819f) to accept API traffic over the HTTP API.
```yaml
my-remote-docker:
host: 192.168.0.101
port: 2375
```
## Using Docker TLS
Since Docker supports connecting with TLS and client certificate authentication, you can include TLS details when connecting to the HTTP API. Further details of setting up Docker to accept TLS connections, and generation of the keys and certs can be found [in the Docker documentation](https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket). The file entries are relative to the `config` directory (location of `docker.yaml` file).
```yaml
my-remote-docker:
host: 192.168.0.101
port: 275
tls:
keyFile: tls/key.pem
caFile: tls/ca.pem
certFile: tls/cert.pem
```
## Using Docker Socket Proxy
Due to security concerns with exposing the docker socket directly, you can use a [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) container to expose the docker socket on a more restricted and secure API.
Here is an example docker-compose file that will expose the docker socket, and then connect to it from the homepage container:
```yaml
dockerproxy:
image: ghcr.io/tecnativa/docker-socket-proxy:latest
container_name: dockerproxy
environment:
- CONTAINERS=1 # Allow access to viewing containers
- SERVICES=1 # Allow access to viewing services (necessary when using Docker Swarm)
- TASKS=1 # Allow access to viewing tasks (necessary when using Docker Swarm)
- POST=0 # Disallow any POST operations (effectively read-only)
ports:
- 127.0.0.1:2375:2375
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro # Mounted as read-only
restart: unless-stopped
homepage:
image: ghcr.io/benphelps/homepage:latest
container_name: homepage
volumes:
- /path/to/config:/app/config
ports:
- 3000:3000
restart: unless-stopped
```
Then, inside of your `docker.yaml` settings file, you'd configure the docker instance like so:
```yaml
my-docker:
host: dockerproxy
port: 2375
```
## Using Socket Directly
If you'd rather use the socket directly, first make sure that you're passing the local socket into the Docker container.
!!! note
In order to use the socket directly homepage must be running as root
```yaml
homepage:
image: ghcr.io/benphelps/homepage:latest
container_name: homepage
volumes:
- /path/to/config:/app/config
- /var/run/docker.sock:/var/run/docker.sock # pass local proxy
ports:
- 3000:3000
restart: unless-stopped
```
If you're using `docker run`, this would be `-v /var/run/docker.sock:/var/run/docker.sock`.
Then, inside of your `docker.yaml` settings file, you'd configure the docker instance like so:
```yaml
my-docker:
socket: /var/run/docker.sock
```
## Services
Once you've configured your docker instances, you can then apply them to your services, to get stats and status reporting shown.
Inside of the service you'd like to connect to docker:
```yaml
- Emby:
icon: emby.png
href: "http://emby.home/"
description: Media server
server: my-docker # The docker server that was configured
container: emby # The name of the container you'd like to connect
```
## Automatic Service Discovery
Homepage features automatic service discovery for containers with the proper labels attached, all configuration options can be applied using dot notation, beginning with `homepage`.
Below is an example of the same service entry shown above, as docker labels.
```yaml
services:
emby:
image: lscr.io/linuxserver/emby:latest
container_name: emby
ports:
- 8096:8096
restart: unless-stopped
labels:
- homepage.group=Media
- homepage.name=Emby
- homepage.icon=emby.png
- homepage.href=http://emby.home/
- homepage.description=Media server
```
When your Docker instance has been properly configured, this service will be automatically discovered and added to your Homepage. **You do not need to specify the `server` or `container` values, as they will be automatically inferred.**
**When using docker swarm use _deploy/labels_**
## Widgets
You may also configure widgets, along with the standard service entry, again, using dot notation.
```yaml
labels:
- homepage.group=Media
- homepage.name=Emby
- homepage.icon=emby.png
- homepage.href=http://emby.home/
- homepage.description=Media server
- homepage.widget.type=emby
- homepage.widget.url=http://emby.home
- homepage.widget.key=yourembyapikeyhere
- homepage.widget.fields=["field1","field2"] # optional
```
## Docker Swarm
Docker swarm is supported and Docker services are specified with the same `server` and `container` notation. To enable swarm support you will need to include a `swarm` setting in your docker.yaml, e.g.
```yaml
my-docker:
socket: /var/run/docker.sock
swarm: true
```
For the automatic service discovery to discover all services it is important that homepage should be deployed on a manager node. Set deploy requirements to the master node in your stack yaml config, e.g.
```yaml
....
deploy:
placement:
constraints:
- node.role == manager
...
```
In order to detect every service within the Docker swarm it is necessary that service labels should be used and not container labels. Specify the homepage labels as:
```yaml
....
deploy:
labels:
- homepage.icon=foobar
...
```
## Ordering
As of v0.6.4 discovered services can include an optional `weight` field to determine sorting such that:
- Default weight for discovered services is 0
- Default weight for configured services is their index within their group scaled by 100, i.e. (index + 1) \* 100
- If two items have the same weight value, then they will be sorted by name
## Show stats
You can show the docker stats by clicking the status indicator but this can also be controlled per-service with:
```yaml
- Example Service:
...
showStats: true
```
Also see the settings for [show docker stats](docker.md#show-docker-stats).

16
docs/configs/index.md Normal file
View file

@ -0,0 +1,16 @@
---
title: Configuration
description: Homepage Configuration
---
Homepage uses YAML for configuration, YAML stands for "YAML Ain't Markup Language.". It's a human-readable data serialization format that's a superset of JSON. Great for config files, easy to read and write. Supports complex data types like lists and objects. **Indentation matters.** If you already use Docker Compose, you already use YAML.
Here are some tips when writing YAML:
1. **Use Indentation Carefully**: YAML relies on indentation, not brackets.
2. Avoid Tabs: Stick to spaces for indentation to avoid parsing errors. 2 spaces are common.
3. Quote Strings: Use single or double quotes for strings with special characters, this is especially important for API keys.
4. Key-Value Syntax: Use key: value format. Colon must be followed by a space.
5. Validate: Always validate your YAML with a linter before deploying.
You can find tons of online YAML validators, here's one: [https://codebeautify.org/yaml-validator](https://codebeautify.org/yaml-validator), heres another: [https://jsonformatter.org/yaml-validator](https://jsonformatter.org/yaml-validator).

138
docs/configs/kubernetes.md Normal file
View file

@ -0,0 +1,138 @@
---
title: Kubernetes
description: Kubernetes Configuration
---
The Kubernetes connectivity has the following requirements:
- Kubernetes 1.19+
- Metrics Service
- An Ingress controller
The Kubernetes connection is configured in the `kubernetes.yaml` file. There are 3 modes to choose from:
- **disabled** - disables kubernetes connectivity
- **default** - uses the default kubeconfig [resolution](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
- **cluster** - uses a service account inside the cluster
```yaml
mode: default
```
## Services
Once the Kubernetes connection is configured, individual services can be configured to pull statistics. Only CPU and Memory are currently supported.
Inside of the service you'd like to connect to a pod:
```yaml
- Emby:
icon: emby.png
href: "http://emby.home/"
description: Media server
namespace: media # The kubernetes namespace the app resides in
app: emby # The name of the deployed app
```
The `app` field is used to create a label selector, in this example case it would match pods with the label: `app.kubernetes.io/name=emby`.
Sometimes this is insufficient for complex or atypical application deployments. In these cases, the `podSelector` field can be used. Any field selector can be used with it, so it allows for some very powerful selection capabilities.
For instance, it can be utilized to roll multiple underlying deployments under one application to see a high-level aggregate:
```yaml
- Element Chat:
icon: matrix-light.png
href: https://chat.example.com
description: Matrix Synapse Powered Chat
app: matrix-element
namespace: comms
podSelector: >-
app.kubernetes.io/instance in (
matrix-element,
matrix-media-repo,
matrix-media-repo-postgresql,
matrix-synapse
)
```
!!! note
A blank string as a podSelector does not deactivate it, but will actually select all pods in the namespace. This is a useful way to capture the resource usage of a complex application siloed to a single namespace, like Longhorn.
## Automatic Service Discovery
Homepage features automatic service discovery by Ingress annotations. All configuration options can be applied using typical annotation syntax, beginning with `gethomepage.dev/`.
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: emby
annotations:
gethomepage.dev/enabled: "true"
gethomepage.dev/description: Media Server
gethomepage.dev/group: Media
gethomepage.dev/icon: emby.png
gethomepage.dev/name: Emby
gethomepage.dev/widget.type: "emby"
gethomepage.dev/widget.url: "https://emby.example.com"
gethomepage.dev/podSelector: ""
gethomepage.dev/weight: 10 # optional
spec:
rules:
- host: emby.example.com
http:
paths:
- backend:
service:
name: emby
port:
number: 8080
path: /
pathType: Prefix
```
When the Kubernetes cluster connection has been properly configured, this service will be automatically discovered and added to your Homepage. **You do not need to specify the `namespace` or `app` values, as they will be automatically inferred.**
### Traefik IngressRoute support
Homepage can also read ingresses defined using the Traefik IngressRoute custom resource definition. Due to the complex nature of Traefik routing rules, it is required for the `gethomepage.dev/href` annotation to be set:
```yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: emby
annotations:
gethomepage.dev/href: "https://emby.example.com"
gethomepage.dev/enabled: "true"
gethomepage.dev/description: Media Server
gethomepage.dev/group: Media
gethomepage.dev/icon: emby.png
gethomepage.dev/name: Emby
gethomepage.dev/widget.type: "emby"
gethomepage.dev/widget.url: "https://emby.example.com"
gethomepage.dev/podSelector: ""
gethomepage.dev/weight: 10 # optional
spec:
entryPoints:
- websecure
routes:
- kind: Rule
match: Host(`emby.example.com`)
services:
- kind: Service
name: emby
namespace: emby
port: 8080
scheme: http
strategy: RoundRobin
weight: 10
```
If the `href` attribute is not present, Homepage will ignore the specific IngressRoute.
## Caveats
Similarly to Docker service discovery, there currently is no rigid ordering to discovered services and discovered services will be displayed above those specified in the `services.yaml`.

40
docs/configs/service-widgets.md Normal file
View file

@ -0,0 +1,40 @@
---
title: Service Widgets
description: Service Widget Configuration
---
Unless otherwise noted, URLs should not end with a `/` or other API path. Each widget will handle the path on its own.
Each service can have one widget attached to it (often matching the service type, but thats not forced).
In addition to the href of the service, you can also specify the target location in which to open that link. See [Link Target](settings.md#link-target) for more details.
Using Emby as an example, this is how you would attach the Emby service widget.
```yaml
- Emby:
icon: emby.png
href: http://emby.host.or.ip/
description: Movies & TV Shows
widget:
type: emby
url: http://emby.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
```
## Field Visibility
Each widget can optionally provide a list of which fields should be visible via the `fields` widget property. If no fields are specified, then all fields will be displayed. The `fields` property must be a valid YAML array of strings. As an example, here is the entry for Sonarr showing only a couple of fields.
**In all cases a widget will work and display all fields without specifying the `fields` property.**
```yaml
- Sonarr:
icon: sonarr.png
href: http://sonarr.host.or.ip
widget:
type: sonarr
fields: ["wanted", "queued"]
url: http://sonarr.host.or.ip
key: apikeyapikeyapikeyapikeyapikey
```

190
docs/configs/services.md Normal file
View file

@ -0,0 +1,190 @@
---
title: Services
description: Service Configuration
---
Services are configured inside the `services.yaml` file. You can have any number of groups, and any number of services per group.
## Groups
Groups are defined as top-level array entries.
```yaml
- Group A:
- Service A:
href: http://localhost/
- Group B:
- Service B:
href: http://localhost/
```
<img width="1038" alt="Service Groups" src="https://user-images.githubusercontent.com/82196/187040754-28065242-4534-4409-881c-93d1921c6141.png">
## Services
Services are defined as array entries on groups,
```yaml
- Group A:
- Service A:
href: http://localhost/
- Service B:
href: http://localhost/
- Service C:
href: http://localhost/
- Group B:
- Service D:
href: http://localhost/
```
<img width="1038" alt="Service Services" src="https://user-images.githubusercontent.com/82196/187040763-038023a2-8bee-4d87-b5cc-13447e7365a4.png">
## Descriptions
Services may have descriptions,
```yaml
- Group A:
- Service A:
href: http://localhost/
description: This is my service
- Group B:
- Service B:
href: http://localhost/
description: This is another service
```
<img width="1038" alt="Service Descriptions" src="https://user-images.githubusercontent.com/82196/187040817-11a3d0eb-c997-4ef9-8f06-2d03a11332b6.png">
## Icons
Services may have an icon attached to them, you can use icons from [Dashboard Icons](https://github.com/walkxcode/dashboard-icons) automatically, by passing the name of the icon, with, or without `.png` or with `.svg` to use the svg version.
You can also specify prefixed icons from [Material Design Icons](https://materialdesignicons.com) with `mdi-XX` or [Simple Icons](https://simpleicons.org/) with `si-XX`.
You can specify a custom color by adding a hex color code as suffix e.g. `mdi-XX-#f0d453` or `si-XX-#a712a2`.
To use a remote icon, use the absolute URL (e.g. `https://...`).
To use a local icon, first create a Docker mount to `/app/public/icons` and then reference your icon as `/icons/myicon.png`. You will need to restart the container when adding new icons.
!!! warning
Material Design Icons for **brands** were deprecated and may be removed in the future. Using Simple Icons for brand icons will prevent any issues if / when the Material Design Icons are removed.
```yaml
- Group A:
- Sonarr:
icon: sonarr.png
href: http://sonarr.host/
description: Series management
- Group B:
- Radarr:
icon: radarr.png
href: http://radarr.host/
description: Movie management
- Group C:
- Service:
icon: mdi-flask-outline
href: http://service.host/
description: My cool service
```
<img width="1038" alt="Service Icons" src="https://user-images.githubusercontent.com/82196/187040777-da1361d7-f0c4-4531-95db-136cd00a1611.png">
## Ping
Services may have an optional `ping` property that allows you to monitor the availability of an endpoint you chose and have the response time displayed. You do not need to set your ping URL equal to your href URL.
!!! note
The ping feature works by making an http `HEAD` request to the URL, and falls back to `GET` in case that fails. It will not, for example, login if the URL requires auth or is behind e.g. Authelia. In the case of a reverse proxy and/or auth this usually requires the use of an 'internal' URL to make the ping feature correctly display status.
```yaml
- Group A:
- Sonarr:
icon: sonarr.png
href: http://sonarr.host/
ping: http://sonarr.host/
- Group B:
- Radarr:
icon: radarr.png
href: http://radarr.host/
ping: http://some.other.host/
```
<img width="1038" alt="Ping" src="https://github.com/benphelps/homepage/assets/88257202/7bc13bd3-0d0b-44e3-888c-a20e069a3233">
You can also apply different styles to the ping indicator by using the `statusStyle` property. The default is no value, and displays the response time in ms, but you can also use `dot` or `simple`. `dot` showing a green dot for a successful ping, and `simple` showing either ONLINE or OFFLINE to match the status style of Docker containers.
<!-- TODO: Insert images of the new status styles there -->
## Docker Integration
Services may be connected to a Docker container, either running on the local machine, or a remote machine.
```yaml
- Group A:
- Service A:
href: http://localhost/
description: This is my service
server: my-server
container: my-container
- Group B:
- Service B:
href: http://localhost/
description: This is another service
server: other-server
container: other-container
```
<img width="1038" alt="Service Containers" src="https://github.com/benphelps/homepage/assets/88257202/4c685783-52c6-4e55-afb3-affe9baac09b">
**Clicking on the status label of a service with Docker integration enabled will expand the container stats, where you can see CPU, Memory, and Network activity.**
!!! note
This can also be controlled with `showStats`. See [show docker stats](docker.md#show-docker-stats) for more information
<img width="1038" alt="Docker Stats Expanded" src="https://github.com/benphelps/homepage/assets/88257202/f95fd595-449e-48ae-af67-fd89618904ec">
## Service Integrations
Services may also have a service widget (or integration) attached to them, this works independently of the Docker integration.
You can find information and configuration for each of the supported integrations on the [Service Widgets](service-widgets.md) page.
Here is an example of a Radarr & Sonarr service, with their respective integrations.
```yaml
- Group A:
- Sonarr:
icon: sonarr.png
href: http://sonarr.host/
description: Series management
widget:
type: sonarr
url: http://sonarr.host
key: apikeyapikeyapikeyapikeyapikey
- Group B:
- Radarr:
icon: radarr.png
href: http://radarr.host/
description: Movie management
widget:
type: radarr
url: http://radarr.host
key: apikeyapikeyapikeyapikeyapikey
```
<img width="1038" alt="Service Integrations" src="https://user-images.githubusercontent.com/82196/187040838-6cd518c2-4f08-41ef-8aa6-364df5e2660e.png">

401
docs/configs/settings.md Normal file
View file

@ -0,0 +1,401 @@
---
title: Settings
description: Service Configuration
---
The `settings.yaml` file allows you to define application level options. For changes made to this file to take effect, you will need to regenerate the static HTML, this can be done by clicking the refresh icon in the bottom right of the page.
## Title
You can customize the title of the page if you'd like.
```yaml
title: My Awesome Homepage
```
## Start URL
You can customize the start_url as required for installable apps. The default is "/".
```yaml
startUrl: https://custom.url
```
## Background Image
!!! warning "Heads Up!"
You will need to restart the container any time you add new images, this is a limitation of the Next.js static site server.
!!! warning "Heads Up!"
Do not create a bind mount to the entire `/app/public/` directory.
If you'd like to use a background image instead of the solid theme color, you may provide a full URL to an image of your choice.
```yaml
background: https://images.unsplash.com/photo-1502790671504-542ad42d5189?auto=format&fit=crop&w=2560&q=80
```
Or you may pass the path to a local image relative to e.g. `/app/public/images` directory.
For example, inside of your Docker Compose file, mount a path to where your images are kept:
```yaml
volumes:
- /my/homepage/images:/app/public/images
```
and then reference that image:
```yaml
background: /images/background.png
```
### Background Opacity & Filters
You can specify filters to apply over your background image for blur, saturation and brightness as well as opacity to blend with the background color. The first three filter settings use tailwind CSS classes, see notes below regarding the options for each. You do not need to specify all options.
```yaml
background:
image: /images/background.png
blur: sm # sm, "", md, xl... see https://tailwindcss.com/docs/backdrop-blur
saturate: 50 # 0, 50, 100... see https://tailwindcss.com/docs/backdrop-saturate
brightness: 50 # 0, 50, 75... see https://tailwindcss.com/docs/backdrop-brightness
opacity: 50 # 0-100
```
### Card Background Blur
You can apply a blur filter to the service & bookmark cards. Note this option is incompatible with the backround blur, saturate and brightness filters.
```yaml
cardBlur: sm # sm, "", md, etc... see https://tailwindcss.com/docs/backdrop-blur
```
## Favicon
If you'd like to use a custom favicon instead of the included one, you may provide a full URL to an image of your choice.
```yaml
favicon: https://www.google.com/favicon.ico
```
Or you may pass the path to a local image relative to the `/app/public` directory. See [Background Image](#background-image) for more detailed information on how to provide your own files.
## Theme
You can configure a fixed them (and disable the theme switcher) by passing the `theme` option, like so:
```yaml
theme: dark # or light
```
## Color Palette
You can configured a fixed color palette (and disable the palette switcher) by passing the `color` option, like so:
```yaml
color: slate
```
Supported colors are: `slate`, `gray`, `zinc`, `neutral`, `stone`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `red`, `white`
## Layout
You can configure service and bookmarks sections to be either "column" or "row" based layouts, like so:
Assuming you have a group named `Media` in your `services.yaml` or `bookmarks.yaml` file,
```yaml
layout:
Media:
style: row
columns: 4
```
As an example, this would produce the following layout:
<img width="1260" alt="Screenshot 2022-09-15 at 8 03 57 PM" src="https://user-images.githubusercontent.com/82196/190466646-8ca94505-0fcf-4964-9687-3a6c7cd3144f.png">
### Sorting
Service groups and bookmark groups can be mixed in order, **but should use different group names**. If you do not specify any bookmark groups they will all show at the bottom of the page.
**_Using the same name for a service and bookmark group can cause unexpected behavior like a bookmark group being hidden_**
Groups will sort based on the order in the layout block. You can also mix in groups defined by docker labels, e.g.
```yaml
layout:
- Auto-Discovered1:
- Configured1:
- Configured2:
- Auto-Discovered2:
- Configured3:
style: row
columns: 3
```
### Headers
You can hide headers for each section in the layout as well by passing `header` as false, like so:
```yaml
layout:
Section A:
header: false
Section B:
style: row
columns: 3
header: false
```
### Category Icons
You can also add an icon to a category under the `layout` setting similar to the [options for service icons](services.md#icons), e.g.
```yaml
Home Management & Info:
icon: home-assistant.png
Server Tools:
icon: https://cdn-icons-png.flaticon.com/512/252/252035.png
...
```
### Icon Style
The default style for icons (e.g. `icon: mdi-XXXX`) is a gradient, or you can specify that prefixed icons match your theme with a 'flat' style using the setting below.
More information about prefixed icons can be found in [options for service icons](services.md#icons).
```yaml
iconStyle: theme # optional, defaults to gradient
```
### Tabs
Version 0.6.30 introduced a tabbed view to layouts which can be optionally specified in the layout. Tabs is only active if you set the `tab` field on at least one layout group.
Tabs are sorted based on the order in the layout block. If a group has no tab specified (and tabs are set on other groups), services and bookmarks will be shown on all tabs.
Every tab can be accessed directly by visiting Homepage URL with `#Group` (name lowercase and URI-encoded) at the end of the URL.
For example, the following would create four tabs:
```yaml
layout:
...
Bookmark Group on First Tab:
tab: First
First Service Group:
tab: First
style: row
columns: 4
Second Service Group:
tab: Second
columns: 4
Third Service Group:
tab: Third
style: row
Bookmark Group on Fourth Tab:
tab: Fourth
Service Group on every Tab:
style: row
columns: 4
```
### Five Columns
You can add a fifth column (when `style: columns` which is default) by adding:
```yaml
fiveColumns: true
```
By default homepage will max out at 4 columns for column style
### Collapsible sections
You can disable the collapsible feature of services & bookmarks by adding:
```yaml
disableCollapse: true
```
By default the feature is enabled.
## Header Style
There are currently 4 options for header styles, you can see each one below.
<img width="1000" alt="underlined" src="https://user-images.githubusercontent.com/82196/194725622-39ce271c-34e5-414d-be53-62d221811f88.png">
```yaml
headerStyle: underlined # default style
```
---
<img width="1000" alt="boxed" src="https://user-images.githubusercontent.com/82196/194725645-abcb8ed9-d017-416f-9e74-cc5642fa982c.png">
```yaml
headerStyle: boxed
```
---
<img width="1000" alt="clean" src="https://user-images.githubusercontent.com/82196/194725650-7a86e818-172d-4d0f-9861-5eae7fecb50a.png">
```yaml
headerStyle: clean
```
---
<img width="1000" alt="boxedWidgets" src="https://user-images.githubusercontent.com/5442891/232258758-ed5262d6-f940-462c-b39e-00e54c19b9ce.png">
```yaml
headerStyle: boxedWidgets
```
## Base URL
In some proxy configurations, it may be necessary to set the documents base URL. You can do this by providing a `base` value, like so:
```yaml
base: http://host.local/homepage
```
**_The URL must be a full, absolute URL, or it will be ignored by the browser._**
## Language
Set your desired language using:
```yaml
language: fr
```
Currently supported languages: ca, de, en, es, fr, he, hr, hu, it, nb-NO, nl, pt, ru, sv, vi, zh-CN, zh-Hant
You can also specify locales e.g. for the DateTime widget, e.g. en-AU, en-GB, etc.
## Link Target
Changes the behaviour of links on the homepage,
```yaml
target: _blank # Possible options include _blank, _self, and _top
```
Use `_blank` to open links in a new tab, `_self` to open links in the same tab, and `_top` to open links in a new window.
This can also be set for individual services. Note setting this at the service level overrides any setting in settings.json, e.g.:
```yaml
- Example Service:
href: https://example.com/
...
target: _self
```
## Providers
The `providers` section allows you to define shared API provider options and secrets. Currently this allows you to define your weather API keys in secret and is also the location of the Longhorn URL and credentials.
```yaml
providers:
openweathermap: openweathermapapikey
weatherapi: weatherapiapikey
longhorn:
url: https://longhorn.example.com
username: admin
password: LonghornPassword
```
You can then pass `provider` instead of `apiKey` in your widget configuration.
```yaml
- weather:
latitude: 50.449684
longitude: 30.525026
provider: weatherapi
```
## Quick Launch
You can use the 'Quick Launch' feature to search services, perform a web search or open a URL. To use Quick Launch, just start typing while on your homepage (as long as the search widget doesnt have focus).
<img width="1000" alt="quicklaunch" src="https://user-images.githubusercontent.com/4887959/216880811-90ff72cb-2990-4475-889b-7c3a31e6beef.png">
There are a few optional settings for the Quick Launch feature:
- `searchDescriptions`: which lets you control whether item descriptions are included in searches. This is off by default. When enabled, results that match the item name will be placed above those that only match the description.
- `hideInternetSearch`: disable automatically including the currently-selected web search (e.g. from the widget) as a Quick Launch option. This is false by default, enabling the feature.
- `hideVisitURL`: disable detecting and offering an option to open URLs. This is false by default, enabling the feature.
```yaml
quicklaunch:
searchDescriptions: true
hideInternetSearch: true
hideVisitURL: true
```
## Homepage Version
By default the release version is displayed at the bottom of the page. To hide this, use the `hideVersion` setting, like so:
```yaml
hideVersion: true
```
## Log Path
By default the homepage logfile is written to the a `logs` subdirectory of the `config` folder. In order to customize this path, you can set the `logpath` setting. A `logs` folder will be created in that location where the logfile will be written.
```yaml
logpath: /logfile/path
```
## Show Docker Stats
You can show all docker stats expanded in `settings.yaml`:
```yaml
showStats: true
```
or per-service (`services.yaml`) with:
```yaml
- Example Service:
...
showStats: true
```
If you have both set the per-service settings take precedence.
## Hide Widget Error Messages
Hide the visible API error messages either globally in `settings.yaml`:
```yaml
hideErrors: true
```
or per service widget (`services.yaml`) with:
```yaml
- Example Service:
...
widget:
...
hideErrors: true
```
If either value is set to true, the errror message will be hidden.