## File: README.md

# Features

With features like quick search, bookmarks, weather support, a wide range of integrations and widgets, an elegant and modern design, and a focus on performance, Homepage is your ideal start to the day and a handy companion throughout it.

- **Fast** - The site is statically generated at build time for instant load times.
- **Secure** - All API requests to backend services are proxied, keeping your API keys hidden. Constantly reviewed for security by the community.
- **For Everyone** - Images built for AMD64, ARM64.
- **Full i18n** - Support for over 40 languages.
- **Service & Web Bookmarks** - Add custom links to the homepage.
- **Docker Integration** - Container status and stats. Automatic service discovery via labels.
- **Service Integration** - Over 100 service integrations, including popular starr and self-hosted apps.
- **Information & Utility Widgets** - Weather, time, date, search, and more.
- **And much more...**

## Docker Integration

Homepage has built-in support for Docker, and can automatically discover and add services to the homepage based on labels. See the [Docker Service Discovery](https://gethomepage.dev/configs/docker/#automatic-service-discovery) page for more information.

## Service Widgets

Homepage also has support for hundreds of 3rd-party services, including all popular \*arr apps, and most popular self-hosted apps. Some examples include: Radarr, Sonarr, Lidarr, Bazarr, Ombi, Tautulli, Plex, Jellyfin, Emby, Transmission, qBittorrent, Deluge, Jackett, NZBGet, SABnzbd, etc. As well as service integrations, Homepage also has a number of information providers, sourcing information from a variety of external 3rd-party APIs. See the [Service](https://gethomepage.dev/widgets/) page for more information.

## Information Widgets

Homepage has built-in support for a number of information providers, including weather, time, date, search, glances and more. System and status information presented at the top of the page. See the [Information Providers](https://gethomepage.dev/widgets/) page for more information.

## Customization

Homepage is highly customizable, with support for custom themes, custom CSS & JS, custom layouts, formatting, localization and more. See the [Settings](https://gethomepage.dev/configs/settings/) page for more information.

# Getting Started

For configuration options, examples and more, [please check out the homepage documentation](http://gethomepage.dev).

## Security Notice 🔒

Please note that when using features such as widgets, Homepage can access personal information (for example from your home automation system). To keep your information private, if Homepage is reachable from any untrusted network, it:

1. **must** sit behind a reverse proxy (and/or VPN) that enforces authentication, TLS, and strictly validates Host headers.
2. An optional built-in OIDC login flow or simple password login is available (opt-in) offering a simple “authenticated or not” guard.

## With Docker

Using docker compose:

```yaml
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev # required, may need port. See gethomepage.dev/installation/#homepage_allowed_hosts
      PUID: 1000 # optional, your user id
      PGID: 1000 # optional, your group id
    ports:
      - 3000:3000
    volumes:
      - /path/to/config:/app/config # Make sure your local config directory exists
      - /var/run/docker.sock:/var/run/docker.sock:ro # optional, for docker integrations
    restart: unless-stopped
```

or docker run:

```bash
docker run --name homepage \
  -e HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev \
  -e PUID=1000 \
  -e PGID=1000 \
  -p 3000:3000 \
  -v /path/to/config:/app/config \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  ghcr.io/gethomepage/homepage:latest
```

## From Source

First, clone the repository:

```bash
git clone https://github.com/gethomepage/homepage.git
```

Then install dependencies and build the production bundle:

```bash
pnpm install
pnpm build
```

If this is your first time starting, copy the `src/skeleton` directory to `config/` to populate initial example config files.

Finally, run the server in production mode:

```bash
HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev:1234 pnpm start
```

# Configuration

Please refer to the [homepage documentation website](https://gethomepage.dev/) for more information. Everything you need to know about configuring Homepage is there. Please read everything carefully before asking for help, as most questions are answered there or are simple YAML configuration issues.

# Development

Install NPM packages, this project uses [pnpm](https://pnpm.io/) (and so should you!):

```bash
pnpm install
```

Start the development server:

```bash
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000) to start.

This is a [Next.js](https://nextjs.org/) application, see their documentation for more information.

# Documentation

The homepage documentation is available at [https://gethomepage.dev/](https://gethomepage.dev/).

Homepage uses Zensical for documentation. To run the documentation locally, first install the dependencies:

```bash
uv sync
```

Then run the development server:

```bash
uv run zensical serve # or build, to build the static site
```

# Support & Suggestions

If you have any questions, suggestions, or general issues, please start a discussion on the [Discussions](https://github.com/gethomepage/homepage/discussions) page.

## Troubleshooting

In addition to the docs, the [troubleshooting guide](https://gethomepage.dev/troubleshooting/) can help reveal many basic config or network issues. If you're having a problem, it's a good place to start.

## Contributing & Contributors

Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.

Thanks to the over 200 contributors who have helped make this project what it is today!

Especially huge thanks to [@shamoon](https://github.com/shamoon), who has been the backbone of this community from the very start.

---

## File: docs/configs/bookmarks.md

---
title: Bookmarks
---

Bookmarks are configured in the `bookmarks.yaml` file. They 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/
- Entertainment:
    - YouTube:
        - abbr: YT
          href: https://youtube.com/
```

which renders to (depending on your theme, etc.):



The default [bookmarks.yaml](https://github.com/gethomepage/homepage/blob/main/src/skeleton/bookmarks.yaml) is a working example.

---

## File: docs/configs/custom-css-js.md

---
title: Custom CSS & 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.

!!! warning

    When Homepage authentication is enabled, `custom.css` remains publicly accessible so it can style the sign-in page. Do not include secrets or sensitive internal URLs in this file. `custom.js` remains protected and is only loaded after authentication.

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
    ...
```

---

## File: docs/configs/docker.md

---
title: Docker
---

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: 2375
  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/gethomepage/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
```

Use `protocol: https` if you’re connecting through a reverse proxy (e.g., Traefik) that serves the Docker API over HTTPS:

```yaml
my-docker:
  host: dockerproxy
  port: 443
  protocol: https
```

!!! note

    Note: This does not require TLS certificates if the proxy handles encryption. Do not use `protocol: https` unless you’re sure the target host supports HTTPS.

You can also include `headers` for the connection, for example, if you are using a reverse proxy that requires authentication:

```yaml
my-docker:
  host: dockerproxy
  port: 443
  protocol: https
  headers:
    Authorization: Basic 
```

## 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/gethomepage/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/"
  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
```

!!! note

    If you use mapping syntax (`:`) for labels instead of list syntax (`-`), array values like `fields` must be wrapped in single quotes so they are passed as a string:

    ```yaml
    labels:
      ...
      homepage.widget.fields: '["field1","field2"]'
    ```

Multiple widgets can be specified by incrementing the index, e.g.

```yaml
labels: ...
  - homepage.widgets[0].type=emby
  - homepage.widgets[0].url=http://emby.home
  - homepage.widgets[0].key=yourembyapikeyhere
  - homepage.widgets[1].type=uptimekuma
  - homepage.widgets[1].url=http://uptimekuma.home
  - homepage.widgets[1].slug=youreventslughere
```

To pass custom HTTP headers with a widget request when using labels, use the same dot-notation: `homepage.widget.headers.X-Auth-Key=secret` (or `homepage.widgets[0].headers.X-Auth-Key=secret` when multiple widgets are present).

You can add specify fields for e.g. the [CustomAPI](../widgets/services/customapi.md) widget by using array-style 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=customapi
  - homepage.widget.url=http://argus.service/api/v1/service/summary/emby
  - homepage.widget.mappings[0].label=Deployed Version
  - homepage.widget.mappings[0].field.status=deployed_version
  - homepage.widget.mappings[1].label=Latest Version
  - homepage.widget.mappings[1].field.status=latest_version
```

## 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
...
```

## Multiple Homepage Instances

The optional field `instanceName` can be configured in [settings.yaml](settings.md#instance-name) to differentiate between multiple homepage instances.

To limit a label to an instance, insert `.instance.{{instanceName}}` after the `homepage` prefix.

```yaml
labels:
  - homepage.group=Media
  - homepage.name=Emby
  - homepage.icon=emby.png
  - homepage.instance.internal.href=http://emby.lan/
  - homepage.instance.public.href=https://emby.mydomain.com/
  - homepage.description=Media server
```

## 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](settings.md#show-container-stats).

---

## File: docs/configs/index.md

---
title: Configuration
icon: material/cog
---

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).

---

## File: docs/configs/info-widgets.md

---
title: Information Widgets
---

Information widgets are widgets that provide information about your system or environment and are displayed at the top of the homepage. You can find a list of all available info widgets under the [Info Widgets](../widgets/info/index.md) section.

Info widgets are defined in the widgets.yaml

Each widget has its own configuration options, which are detailed in the widget's documentation.

## Layout

Info widgets are displayed in the order they are defined in the `widgets.yaml` file. You can change the order by moving the widgets around in the file. However, some widgets (weather, search and datetime) are aligned to the right side of the screen which can affect the layout of the widgets.

## Adding A Link

You can add a link to an info widget such as the logo or text widgets by adding an `href` option, for example:

```yaml
logo:
  href: https://example.com
  target: _blank # Optional, can be set in settings
```

---

## File: docs/configs/kubernetes.md

---
title: Kubernetes
---

The Kubernetes connectivity has the following requirements:

- Kubernetes 1.19+
- Metrics Service
- An Ingress controller
  - Optionally: Gateway-API

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
```

To configure Kubernetes gateway-api, ingress or ingressRoute service discovery, add one or multiple of the following settings.

Example settings:

```yaml
ingress: true # default, enable ingress only
```

or

```yaml
ingress: true # default, enable ingress
traefik: true # enable traefik ingressRoute
gateway: true # enable gateway-api
```

## 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/"
  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
    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/widget.headers.X-Auth-Key: "your-secret-here"
    gethomepage.dev/pod-selector: ""
    gethomepage.dev/weight: 10 # optional
    gethomepage.dev/instance: "public" # 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.**

If you are using multiple instances of homepage, an `instance` annotation can be specified to limit services to a specific instance. If no instance is provided, the service will be visible on all instances.

If you have a single service that needs to be shown on multiple specific instances of homepage (but not on all of them), the service can be annotated by multiple `instance.name` annotations, where `name` can be the names of your specific multiple homepage instances. For example, a service that is annotated with `gethomepage.dev/instance.public: ""` and `gethomepage.dev/instance.internal: ""` will be shown on `public` and `internal` homepage instances.

Use the `gethomepage.dev/pod-selector` selector to specify the pod used for the health check. For example, a service that is annotated with `gethomepage.dev/pod-selector: app.kubernetes.io/name=deployment` would link to a pod with the label `app.kubernetes.io/name: deployment`.

### Traefik IngressRoute support

If enabled (with `traefik: true` in kubernetes.yaml), 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/app: emby-app # optional, may be needed if app.kubernetes.io/name != ingress metadata.name
    gethomepage.dev/name: Emby
    gethomepage.dev/widget.type: "emby"
    gethomepage.dev/widget.url: "https://emby.example.com"
    gethomepage.dev/pod-selector: ""
    gethomepage.dev/weight: 10 # optional
    gethomepage.dev/instance: "public" # 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.

### Gateway API HttpRoute support

Homepage also features automatic service discovery for Gateway API. Service definitions are read by annotating the HttpRoute custom resource definition and are indentical to the Ingress example as defined in [Automatic Service Discovery](#automatic-service-discovery).

To enable Gateway API HttpRoute update `kubernetes.yaml` to include:

```
gateway: true # enable gateway-api
```

#### Using the unoffocial helm chart?

If you are using the unofficial helm chart ensure that the `ClusterRole` has required permissions for `gateway.networking.k8s.io`.

See [ClusterRole and ClusterRoleBinding](../installation/k8s.md#clusterrole-and-clusterrolebinding)

## 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`.

## Adding extra configuration files

Some Homepage features (for example, [Proxmox](../configs/proxmox.md)) require additional configuration files such as `proxmox.yaml`.
When running Homepage on Kubernetes, these files must be provided via a `ConfigMap` and mounted into the container at `/app/config`.

### ConfigMap example

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: homepage
data:
  proxmox.yaml: |
    pve:
      url: https://proxmox.host.or.ip:8006
      token: username@pam!Token ID
      secret: secret
```

Mount the file into `/app/config` by updating the `Deployment`:

```yaml
volumeMounts:
  - mountPath: /app/config/proxmox.yaml
    name: homepage-config
    subPath: proxmox.yaml
```

---

## File: docs/configs/proxmox.md

---
title: Proxmox
---

The Proxmox connection is configured in the `proxmox.yaml` file. See [Create token](#create-token) section below for details on how to generate the required API token.
To configure multiple nodes, ensure the key name in the `proxmox.yaml` matches the `proxmoxNode` field used in your service configuration.

```yaml
pve: # must match your actual Proxmox node name
  url: https://proxmox.host.or.ip:8006
  token: username@pam!Token ID
  secret: secret
```

## Services

Once the Proxmox connection is configured, individual services can be configured to pull statistics of VMs or LXCs. Only CPU and Memory are currently supported.

### Configuration Options

- `proxmoxNode`: The name of the Proxmox node where your VM/LXC is running, must match with a node configured in the `proxmox.yaml`
- `proxmoxVMID`: The ID of the Proxmox VM or LXC container
- `proxmoxType`: (Optional) The type of Proxmox virtual machine. Defaults to `qemu` for VMs, but can be set to `lxc` for LXC containers

#### Examples

For a QEMU VM (default):

```yaml
- HomeAssistant:
  icon: home-assistant.png
  href: http://homeassistant.local/
  proxmoxNode: pve
  proxmoxVMID: 101
  # proxmoxType: qemu # This is the default, so it can be omitted
```

For an LXC container:

```yaml
- Nginx:
  icon: nginx.png
  href: http://nginx.local/
  proxmoxNode: pve
  proxmoxVMID: 200
  proxmoxType: lxc
```

## Create token

You will need to generate an API Token for new or an existing user. Here is an example of how to do this for a new user.

1.  Navigate to the Proxmox portal, click on Datacenter
2.  Expand Permissions, click on Groups
3.  Click the Create button
4.  Name the group something informative, like api-ro-users
5.  Click on the Permissions "folder"
6.  Click Add -> Group Permission
    - Path: /
    - Group: group from bullet 4 above
    - Role: PVEAuditor
    - Propagate: Checked
7.  Expand Permissions, click on Users
8.  Click the Add button
    - User name: something informative like `api`
    - Realm: Linux PAM standard authentication
    - Group: group from bullet 4 above
9.  Expand Permissions, click on API Tokens
10. Click the Add button
    - User: user from bullet 8 above
    - Token ID: something informative like the application or purpose like `homepage`
    - Privilege Separation: Checked
11. Go back to the "Permissions" menu
12. Click Add -> API Token Permission
    - Path: /
    - API Token: select the Token ID created in Step 10
    - Role: PVE Auditor
    - Propagate: Checked

---

## File: docs/configs/services.md

---
title: Services
---

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/
```



### Nested Groups

Groups can be nested by using the same format as the top-level groups.

```yaml
- Group A:
    - Service A:
        href: http://localhost/

    - Group B:
        - Service B:
            href: http://localhost/

        - Service C:
            href: http://localhost/
```

## 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/
```



### Service Widgets

Each service can have widgets attached to it (often matching the service type, but that's 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/
    widget:
      type: emby
      url: http://emby.host.or.ip
      key: apikeyapikeyapikeyapikeyapikey
```

#### Multiple Widgets

Each service can have multiple widgets attached to it, for example:

```yaml
- Emby:
    icon: emby.png
    href: http://emby.host.or.ip/
    widgets:
      - type: emby
        url: http://emby.host.or.ip
        key: apikeyapikeyapikeyapikeyapikey
      - type: uptimekuma
        url: http://uptimekuma.host.or.ip:port
        slug: statuspageslug
```

!!! note

      Multiple widgets per service are not yet supported with Kubernetes ingress annotations.

#### Custom HTTP headers

Widgets that make HTTP calls support extra request headers via `headers`. This is useful when a reverse proxy expects a secret header.

```yaml
- UptimeRobot:
    icon: uptimekuma.png
    href: https://uptimerobot.com/
    widget:
      type: uptimerobot
      url: https://api.uptimerobot.com
      key: ${UPTIMEROBOT_API_KEY}
      headers:
        User-Agent: homepage
        X-Auth-Key: your-secret-here
```

If you define services via Docker labels or Kubernetes annotations, use the same key with dot-notation (for example `homepage.widget.headers.X-Auth-Key=secret` or `gethomepage.dev/widget.headers.X-Auth-Key: "secret"`).

#### 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
```

### Block Highlighting

Widgets can tint their metric block text automatically based on rules defined alongside the service. Attach a `highlight` section to the widget configuration and map each block to one or more numeric or string rules using the field key (for example, `queued`, `lan_users`). The custom api widget does not support highlighting.

```yaml
- Sonarr:
    icon: sonarr.png
    href: http://sonarr.host.or.ip
    widget:
      type: sonarr
      url: http://sonarr.host.or.ip
      key: ${SONARR_API_KEY}
      highlight:
        queued:
          numeric:
            - level: danger
              when: gte
              value: 20
            - level: warn
              when: gte
              value: 5
            - level: good
              when: eq
              value: 0
        status:
          string:
            - level: danger
              when: regex
              value: "(failed|import) pending"
            - level: good
              when: equals
              value: "All good"
        status_code:
          string:
            - level: warn
              when: regex
              value: "^5\\d{2}$"
```

Supported numeric operators for the `when` property are `gt`, `gte`, `lt`, `lte`, `eq`, `ne`, `between`, and `outside`. String rules support `equals`, `includes`, `startsWith`, `endsWith`, and `regex`. Each rule can be inverted with `negate: true`, and string rules may pass `caseSensitive: true` or custom regex `flags`. The highlight engine does its best to coerce formatted values, but you will get the most reliable results when you pass plain numbers or strings into ``.

#### Value Only Highlighting

You can optionally apply highlighting only to the value portion of a block (not the label) by setting `valueOnly: true` on the field configuration. This keeps the label visible while highlighting only the metric value itself.

```yaml
- Sonarr:
    ...
      highlight:
        queued:
          valueOnly: true
          ...
```

## Descriptions

Services may have descriptions,

```yaml
- Group A:
    - Service A:
        href: http://localhost/
- Group B:
    - Service B:
        href: http://localhost/
```



## Icons

Services may have an icon attached to them, you can use icons from [Dashboard Icons](https://github.com/homarr-labs/dashboard-icons) automatically, by passing the name of the icon, with, or without `.png`, `.webp` or `.svg` to specify the desired version.

You can also specify prefixed icons from:

- [Material Design Icons](https://pictogrammers.com/library/mdi/) with `mdi-XX`
- [Simple Icons](https://simpleicons.org/) with `si-XX`
- [selfh.st/icons](https://selfh.st/icons/) with `sh-XX` to use the png version or `sh-XX.svg/png/webp` for a specific version

You can specify a custom color for `mdi` and `si` icons by adding a hex color code as a suffix e.g. `mdi-XX-#f0d453` or `si-XX-#a712a2`.

Note that these icon sets are not bundled with Homepage, they are fetched in the browser from remote CDN servers. To use the icons offline you may download the icons and serve them locally, or rely on browser caching when applicable.

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/
- Group B:
    - Radarr:
        icon: radarr.png
        href: http://radarr.host/
- Group C:
    - Service:
        icon: mdi-flask-outline
        href: http://service.host/
```



## Ping

Services may have an optional `ping` property that allows you to monitor the availability of an external host. As of v0.8.0, the ping feature attempts to use a true (ICMP) ping command on the underlying host. Currently, only IPv4 is supported.

!!! note

      Because ping uses the ping command on the underlying host, in some cases you may need to install e.g. the `iputils-ping` package on the host system.

```yaml
- Group A:
    - Sonarr:
        icon: sonarr.png
        href: http://sonarr.host/
        ping: sonarr.host

- Group B:
    - Radarr:
        icon: radarr.png
        href: http://radarr.host/
        ping: some.other.host
```



You can also apply different styles to the ping indicator by using the `statusStyle` property, see [settings](settings.md#status-style).

## Site Monitor

Services may have an optional `siteMonitor` property (formerly `ping`) that allows you to monitor the availability of a URL you chose and have the response time displayed. You do not need to set your monitor URL equal to your href or ping URL.

!!! note

    The site monitor 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 site monitor feature correctly display status.

```yaml
- Group A:
    - Sonarr:
        icon: sonarr.png
        href: http://sonarr.host/
        siteMonitor: http://sonarr.host/

- Group B:
    - Radarr:
        icon: radarr.png
        href: http://radarr.host/
        siteMonitor: http://some.other.host/
```

You can also apply different styles to the site monitor indicator by using the `statusStyle` property, see [settings](settings.md#status-style).

## 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/
        server: my-server
        container: my-container

- Group B:
    - Service B:
        href: http://localhost/
        server: other-server
        container: other-container
```



**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-stats) for more information



## 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 [Widgets](../widgets/index.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/
        widget:
          type: sonarr
          url: http://sonarr.host
          key: apikeyapikeyapikeyapikeyapikey

- Group B:
    - Radarr:
        icon: radarr.png
        href: http://radarr.host/
        widget:
          type: radarr
          url: http://radarr.host
          key: apikeyapikeyapikeyapikeyapikey
```

---

## File: docs/configs/settings.md

---
title: Settings
---

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
```

## Description

You can customize the description of the page if you'd like.

```yaml
```

## 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 background blur, saturate and brightness filters.

```yaml
cardBlur: xs # xs, 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 theme (and disable the theme switcher) by passing the `theme` option, like so:

```yaml
theme: dark # or light
```

## Color Palette

You can configure 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`

## Block Highlight Levels

You can override the default Tailwind classes applied when a widget highlight rule resolves to the `good`, `warn`, or `danger` level.

```yaml
blockHighlights:
  levels:
    good: "bg-emerald-500/40 text-emerald-950 dark:bg-emerald-900/60 dark:text-emerald-400"
    warn: "bg-amber-300/30 text-amber-900 dark:bg-amber-900/30 dark:text-amber-200"
    danger: "bg-rose-700/45 text-rose-200 dark:bg-rose-950/70 dark:text-rose-400"
```

Any unspecified level falls back to the built-in defaults.

## Progressive Web App (PWA)

A progressive web app is an app that can be installed on a device and provide user experience like a native app. Homepage comes with built-in support for PWA with some default configurations, but you can customize them.

More information on PWAs can be found in [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps).

### App icons

You can set custom icons for installable apps. More information about how you can set them can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons).

The default value is the Homepage icon in sizes 192x192 and 512x512.

```yaml
pwa:
  icons:
    - src: https://developer.mozilla.org/favicon-192x192.png
      type: image/png
      sizes: 192x192
    - src: https://developer.mozilla.org/favicon-512x512.png
      type: image/png
      sizes: 512x512
```

For icon `src` you can pass either full URL or a local path relative to the `/app/public` directory. See [Background Image](#background-image) for more detailed information on how to provide your own files.

### Shortcuts

Shortcuts can be used to specify links to tabs, to be preselected when the homepage is opened as an app.
More information about how you can set them can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts).

```yaml
pwa:
  shortcuts:
    - name: First
      url: "/#first" # opens the first tab
    - name: Second
      url: "/#second" # opens the second tab
    - name: Third
      url: "/#third" # opens the third tab
```

### Other PWA configurations

Homepage sets few other PWA configurations, that are based on global settings in `settings.yaml`:

- `name`, `short_name` - Both equal to the [`title`](#title) setting.
- `theme_color`, `background_color` - Both based on the [`color`](#color-palette) and [`theme`](#theme) settings.
- `display` - It is always set to "standalone".
- `start_url` - Equal to the [`startUrl`](#start-url) setting.

More information for wach of the PWA configurations can be found in the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference).

## 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:



### Icons-Only Layout

You can also specify the an icon-only layout for bookmarks, either like so:

```yaml
layout:
  Media:
    iconsOnly: true
```

or globally:

```yaml
bookmarksStyle: icons
```

### 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
```

### Nested Groups

If your services config has nested groups, you can apply settings to these groups by nesting them in the layout block
and using the same settings. For example

```yaml
layout:
  Group A:
    style: row
    columns: 4
  Group C:
    style: row
    columns: 2
    Nested Group A:
      style: row
      columns: 2
    Nested Group B:
      style: row
      columns: 2
```

### 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
```

### Full Width

You can make homepage take up the entire window width by adding:

```yaml
fullWidth: true
```

### Maximum Group Columns

You can set the maximum number of columns of groups on larger screen sizes (note this is only for groups with the default `style: columns`, not groups with `style: row`) by adding:

```yaml
maxGroupColumns: 8 # default is 4 for services, 6 for bookmarks, max 8
```

By default homepage will max out at 4 columns for services and 6 for bookmarks, thus the minimum for this setting is _5_. Of course, if you're setting this to higher numbers, you may want to consider enabling the [fullWidth](#full-width) option as well.

If you want to set the maximum columns for bookmark groups separately, you can do so by adding:

```yaml
maxBookmarkGroupColumns: 6 # default is 6, max 8
```

### Collapsible sections

You can disable the collapsible feature of services & bookmarks by adding:

```yaml
disableCollapse: true
```

By default the feature is enabled.

### Initially collapsed sections

You can initially collapse sections by adding the `initiallyCollapsed` option to the layout group.

```yaml
layout:
  Section A:
    initiallyCollapsed: true
```

This can also be set globaly using the `groupsInitiallyCollapsed` option.

```yaml
groupsInitiallyCollapsed: true
```

The value set on a group will overwrite the global setting.

By default the feature is disabled.

### Use Equal Height Cards

You can enable equal height cards for groups of services, this will make all cards in a row the same height.

Global setting in `settings.yaml`:

```yaml
useEqualHeights: true
```

Per layout group in `settings.yaml`:

```yaml
useEqualHeights: false
layout:
  ...
  Group Name:
    useEqualHeights: true # overrides global setting
```

By default the feature is disabled

## Header Style

There are currently 4 options for header styles, you can see each one below.



```yaml
headerStyle: underlined # default style
```

---



```yaml
headerStyle: boxed
```

---



```yaml
headerStyle: clean
```

---



```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-Hans (Simplified), zh-Hant (Traditional)

`zh-CN` will still work and is automatically mapped to `zh-Hans` for backwards compatibility.

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.

```yaml
providers:
  openweathermap: openweathermapapikey
  finnhub: yourfinnhubapikeyhere
  longhorn:
    url: https://longhorn.example.com
    username: admin
    password: LonghornPassword
```

You can then pass `provider` instead of `apiKey` in your widget configuration.

```yaml
- openweathermap:
    latitude: 50.449684
    longitude: 30.525026
    provider: openweathermap
```

## 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 doesn't have focus).



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 false 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.
- `showSearchSuggestions`: show search suggestions for the internet search. If this is not specified then the setting will be inherited from the search widget. If it is not specified there either, it will default to false. For custom providers the `suggestionUrl` needs to be set in order for this to work.
- `provider`: search engine provider. If none is specified it will try to use the provider set for the Search Widget, if neither are present then internet search will be disabled.
- `hideVisitURL`: disable detecting and offering an option to open URLs. This is false by default, enabling the feature.
- `mobileButtonPosition`: enables and sets the position of the mobile quicklaunch button. Options are `top-left`, `top-right`, `bottom-left`, `bottom-right`. This is empty by default, disabling the feature.

```yaml
quicklaunch:
  searchDescriptions: true
  hideInternetSearch: true
  showSearchSuggestions: true
  hideVisitURL: true
  provider: google # google, duckduckgo, bing, baidu, brave or custom
```

or for a custom search:

```yaml
quicklaunch:
  provider: custom
  url: https://www.ecosia.org/search?q=
  target: _blank
  suggestionUrl: https://ac.ecosia.org/autocomplete?type=list&q=
```

## Homepage Version & Update Checking

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
```

You can disable checking for new versions from GitHub (enabled by default) with:

```yaml
disableUpdateCheck: 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
```

By default, logs are sent both to `stdout` and to a file at the path specified. This can be changed by setting the `LOG_TARGETS` environment variable to one of `both` (default), `stdout` or `file`.

## Show Container Stats

You can show all docker or proxmox 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.

## Status Style

You can choose from the following styles for docker or k8s status, site monitor and ping: `dot` or `basic`

- The default is no value, and displays the monitor and ping response time in ms and the docker / k8s container status
- `dot` shows a green dot for a successful monitor ping or healthy status.
- `basic` shows either UP or DOWN for monitor & ping

For example:

```yaml
statusStyle: "dot"
```

or per-service (`services.yaml`) with:

```yaml
- Example Service:
    ...
    statusStyle: 'dot'
```

If you have both set, the per-service settings take precedence.

## Instance Name

Name used by automatic docker service discovery to differentiate between multiple homepage instances.

For example:

```yaml
instanceName: public
```

## 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 error message will be hidden.

## Disable Search Engine Indexing

You can request that search engines not to index your Homepage instance by enabling the `disableIndexing` setting.

```yaml
disableIndexing: true
```

When enabled, this will:

- Disallow all crawlers in `robots.txt`
- Add `<meta name="robots" content="noindex, nofollow">` tags to prevent indexing

By default this feature is disabled.