Homepage

https://gethomepage.dev/
Admin
A modern, fully static, fast, secure, and highly customizable application dashboard with...
Tokens:81,353
Snippets:985
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies and build production bundle

Source: https://gethomepage.dev/installation/source

Installs dependencies and builds the production bundle.

```bash
pnpm install
pnpm build
```

--------------------------------

### Start development server with pnpm dev

Source: https://gethomepage.dev/widgets/authoring/getting-started

Starts the development server. Open http://localhost:3000 to view the application.

```bash
pnpm dev

```

--------------------------------

### Example MCP tools/list request

Source: https://gethomepage.dev/configs/mcp

Example curl request to list available MCP tools.

```bash
curl -s http://localhost:3000/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-token' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

```

--------------------------------

### bookmarks.yaml example

Source: https://gethomepage.dev/configs/bookmarks

Example configuration for the bookmarks.yaml file. Groups and lists work like Services, but bookmarks only contain a link. The abbr field is expected to be 2 letters, but not enforced. If both icon and abbreviation are supplied, the icon takes precedence. The description defaults to the hostname of the link unless overridden.

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

```

--------------------------------

### add_info_widget tool example

Source: https://gethomepage.dev/configs/mcp

Example payload for the add_info_widget tool to append an information widget to widgets.yaml when HOMEPAGE_MCP_ALLOW_WRITE=true.

```json
{
  "type": "openmeteo",
  "options": {
    "label": "Current",
    "latitude": 36.66,
    "longitude": -117.51,
    "cache": 5
  }
}

```

--------------------------------

### Install pnpm globally

Source: https://gethomepage.dev/installation/source

Installs pnpm globally if it is not already installed.

```bash
npm install -g pnpm
```

--------------------------------

### Set startUrl in settings.yaml

Source: https://gethomepage.dev/configs/settings

Customizes the start_url for installable apps. The default is "/".

```yaml
startUrl: https://custom.url
```

--------------------------------

### add_service tool example

Source: https://gethomepage.dev/configs/mcp

Example payload for the add_service tool to append a service to a group in services.yaml when HOMEPAGE_MCP_ALLOW_WRITE=true.

```json
{
  "group": "Media",
  "name": "Plex",
  "service": {
    "href": "https://plex.example.com",
    "icon": "plex.png",
    "description": "Movies and TV",
    "widget": {
      "type": "plex",
      "url": "https://plex.example.com",
      "key": "your-api-key"
    }
  }
}

```

--------------------------------

### homepage_docs

Source: https://gethomepage.dev/configs/mcp

Returns focused Homepage documentation links for common setup topics.

```APIDOC
## MCP Tool: homepage_docs

### Description
Returns focused Homepage documentation links for common setup topics.

### Method
MCP Tool

### Parameters
None
```

--------------------------------

### Wg-Easy Widget Configuration Example

Source: https://gethomepage.dev/widgets/services/wgeasy

Basic configuration for the Wg-Easy widget. Requires a URL, credentials for API v15+, and supports optional threshold settings.

```yaml
widget:
  type: wgeasy
  url: http://wg.easy.or.ip
  version: 2 # optional, default is 1
  username: yourwgusername # required for v15 and above
  password: yourwgeasypassword
  threshold: 2 # optional
```

--------------------------------

### Basic widget metadata example

Source: https://gethomepage.dev/widgets/authoring/metadata

Shows the minimal structure of a widget metadata object using the generic proxy handler and a single mapping.

```javascript
import genericProxyHandler from "utils/proxy/handlers/generic";

const widgetExample = {
  api: "{url}/api/{endpoint}",
  proxyHandler: genericProxyHandler,

  mappings: {
    stats: { endpoint: "stats" }
  },
};

```

--------------------------------

### Install dependencies with pnpm

Source: https://gethomepage.dev/widgets/authoring/getting-started

Installs NPM packages using pnpm, the package manager used by this project.

```bash
pnpm install

```

--------------------------------

### useWidgetAPI

Source: https://gethomepage.dev/widgets/authoring/api

Documentation for the useWidgetAPI hook, including its parameters and usage examples.

```APIDOC
## useWidgetAPI(widget, endpoint, params)

### Description
Fetches data from an API endpoint using a proxy. The hook ensures data is fetched securely through the proxy.

### Method
Hook (function call)

### Endpoint
N/A (hook invocation)

### Parameters
- **widget** (object) - Required - The widget metadata object containing API endpoint, proxy handler, and mappings.
- **endpoint** (string) - Required - The name of the endpoint to fetch data from, as defined in the widget metadata object.
- **params** (object) - Optional - Query parameters to pass to the API. Must be whitelisted in the widget metadata object.

### Request Example
```javascript
import useWidgetAPI from "utils/proxy/use-widget-api";

export default function Component({ service }) {
  const { data, error } = useWidgetAPI(widget, "stats");
}
```

### Response
#### Success Response
- **data** (any) - The data returned from the API.
- **error** (any) - Any error encountered during the fetch.

#### Response Example
```javascript
const { data, error } = useWidgetAPI(widget, "stats");
```
```

--------------------------------

### api property example

Source: https://gethomepage.dev/widgets/authoring/metadata

Shows the api property with placeholders that are replaced at runtime.

```javascript
const widgetExample = {
  api: "{url}/api/{endpoint}",
};

```

--------------------------------

### Configure a QEMU VM service

Source: https://gethomepage.dev/configs/proxmox

Example service configuration for a QEMU VM. The proxmoxType is optional and defaults to qemu, so it can be omitted. Only CPU and Memory statistics are supported.

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

```

--------------------------------

### Example API response for dynamic list

Source: https://gethomepage.dev/widgets/services/customapi

Example API response that works with the dynamic-list configuration. Contains a data array with objects having id, name, and ip_address fields.

```json
{
  "data": [
    { "id": "server1", "name": "Server 1", "ip_address": "192.168.0.1" },
    { "id": "server2", "name": "Server 2", "ip_address": "192.168.0.2" }
  ]
}
```

--------------------------------

### Docker run command for Homepage

Source: https://gethomepage.dev/installation/docker

Docker run command to start Homepage with port mapping, required environment variable, and volume mounts for config and Docker socket.

```bash
docker run -p 3000:3000 -e HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev -v /path/to/config:/app/config -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/gethomepage/homepage:latest

```

--------------------------------

### useWidgetAPI with params

Source: https://gethomepage.dev/widgets/authoring/api

Example of using the useWidgetAPI hook with query parameters for filtering data.

```APIDOC
## useWidgetAPI(widget, endpoint, params)

### Description
Fetches data from an API endpoint with query parameters. The params object is passed directly as query parameters to the API endpoint.

### Method
Hook (function call)

### Endpoint
N/A (hook invocation)

### Parameters
- **widget** (object) - Required - The widget metadata object.
- **endpoint** (string) - Required - The name of the endpoint to fetch data from.
- **params** (object) - Optional - Query parameters to pass to the API. Must be whitelisted in the widget metadata object.

### Request Example
```javascript
import useWidgetAPI from "utils/proxy/use-widget-api";

export default function Component({ service }) {
  const { data, error } = useWidgetAPI(widget, "stats", { start: "2021-01-01", end: "2021-12-31" });
}
```

### Response
#### Success Response
- **data** (any) - The data returned from the API.
- **error** (any) - Any error encountered during the fetch.

#### Response Example
```javascript
const { data, error } = useWidgetAPI(widget, "stats", { start: "2021-01-01", end: "2021-12-31" });
```
```

--------------------------------

### Speedtest Tracker Widget Configuration

Source: https://gethomepage.dev/widgets/services/speedtest-tracker

Example configuration for the speedtest widget. Version 2 requires an API key, while version 1 is the default.

```yaml
widget:
  type: speedtest
  url: http://speedtest.host.or.ip
  version: 1 # optional, default is 1
  key: speedtestapikey # required for version 2
  bitratePrecision: 3 # optional, default is 0
```

--------------------------------

### Docker integration service entry with container parameter

Source: https://gethomepage.dev/installation/unraid

Example service entry showing the `container:` parameter for Docker integration. No server parameter is needed.

```yaml
    - Plex:
        icon: /icons/plex.png
        href: https://app.plex.com
        container: plex
```

--------------------------------

### Advanced widget metadata example

Source: https://gethomepage.dev/widgets/authoring/metadata

Shows a more complex widget metadata object using the credentialed proxy handler, with validation, parameters, and custom mapping functions.

```javascript
import credentialedProxyHandler from "utils/proxy/handlers/credentialed";
import { asJson, jsonArrayFilter } from "utils/proxy/api-helpers";

const widgetExample = {
  api: "{url}/api/{endpoint}",
  proxyHandler: credentialedProxyHandler,

  mappings: {
    stats: {
      endpoint: "stats",
      validate: ["total", "average"],
      params: ["start", "end"],
    },
    notices: {
      endpoint: "notices",
      map: (data) => {
        total: asJson(data).length;
      },
    },
    warnings: {
      endpoint: "notices",
      map: (data) => {
        total: jsonArrayFilter(data, (alert) => alert.type === "warning").length;
      },
    },
  },
};

```

--------------------------------

### Frigate widget configuration

Source: https://gethomepage.dev/widgets/services/frigate

Example YAML configuration for the Frigate widget. The url is required, while enableRecentEvents (defaults to false), username, and password are optional.

```yaml
widget:
  type: frigate
  url: http://frigate.host.or.ip:port
  enableRecentEvents: true # Optional, defaults to false
  username: username # optional
  password: password # optional

```

--------------------------------

### Configure Coin Market Cap widget with slugs

Source: https://gethomepage.dev/widgets/services/coin-market-cap

Example configuration using the 'slugs' field instead of symbols. Slugs are used because symbols aren't guaranteed to be unique. If both symbols and slugs are supplied, slugs take precedence.

```yaml
widget:
  type: coinmarketcap
  slugs: [chia-network, uniswap]
  key: apikeyapikeyapikeyapikeyapikey

```

--------------------------------

### Generic proxy handler example

Source: https://gethomepage.dev/widgets/authoring/metadata

Shows a widget metadata object using the generic proxy handler for unauthenticated requests.

```javascript
const widgetExample = {
  api: "{url}/api/{endpoint}",
  proxyHandler: genericProxyHandler,
};

```

--------------------------------

### Docker labels for automatic service discovery

Source: https://gethomepage.dev/configs/docker

Use labels starting with 'homepage.' to configure services automatically. For Docker Swarm, use _deploy/labels_ instead.

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

```

--------------------------------

### Attach a service widget (Emby example)

Source: https://gethomepage.dev/configs/services

Attaches a single widget to a service. The widget type matches the service type, but that is not forced. The href is the service link, and the widget has its own url and key.

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

```

--------------------------------

### Short date and time with hour12

Source: https://gethomepage.dev/widgets/info/datetime

Example combining dateStyle: short and timeStyle: short with hour12: true to display date and time in short formats.

```yaml
# 1/23/22, 1:37 PM
format:
  dateStyle: short
  timeStyle: short
  hour12: true

```

--------------------------------

### Configure an LXC container service

Source: https://gethomepage.dev/configs/proxmox

Example service configuration for an LXC container. Set proxmoxType to lxc to pull statistics for LXC containers. Only CPU and Memory are supported.

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

```

--------------------------------

### Apply scale, prefix, and suffix transformations to metric values

Source: https://gethomepage.dev/widgets/services/prometheusmetric

Shows the data transformation options for metric values: scale (multiplies by a number or fraction string), prefix (prepends a string), and suffix (appends a string). Each example uses format.type: number.

```yaml
- query: my_custom_metric{}
  label: Metric 1
  format:
    type: number
    scale: 1000 # multiplies value by a number or fraction string e.g. 1/16
- query: my_custom_metric{}
  label: Metric 2
  format:
    type: number
    prefix: "$" # prefixes value with given string
- query: my_custom_metric{}
  label: Metric 3
  format:
    type: number
    suffix: "€" # suffixes value with given string

```

--------------------------------

### Configure Coin Market Cap widget with symbols

Source: https://gethomepage.dev/widgets/services/coin-market-cap

Example configuration using the 'symbols' field to specify cryptocurrencies. The 'currency' and 'defaultinterval' fields are optional. Requires an API key from your CoinMarketCap Pro Dashboard.

```yaml
widget:
  type: coinmarketcap
  currency: GBP # Optional
  symbols: [BTC, LTC, ETH]
  key: apikeyapikeyapikeyapikeyapikey
  defaultinterval: 7d # Optional

```

--------------------------------

### Quick Launch configuration with standard provider

Source: https://gethomepage.dev/configs/settings

Configures Quick Launch with search descriptions, internet search, search suggestions, and URL hiding enabled, using Google as the provider. The provider can be google, duckduckgo, bing, baidu, brave, or custom.

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

```

--------------------------------

### Example API JSON object

Source: https://gethomepage.dev/widgets/services/customapi

Example JSON object from an API response used to illustrate how to define the mappings section for the Custom API widget. It contains nested fields and an array of locations.

```json
{
  "id": 1,
  "name": "Rick Sanchez",
  "status": "Alive",
  "species": "Human",
  "gender": "Male",
  "origin": {
    "name": "Earth (C-137)"
  },
  "locations": [
    {
      "name": "Earth (C-137)"
    },
    {
      "name": "Citadel of Ricks"
    }
  ]
}
```

--------------------------------

### Lint code with pnpm lint

Source: https://gethomepage.dev/widgets/authoring/getting-started

Lints the code after dependencies are installed.

```bash
pnpm lint

```

--------------------------------

### qBittorrent widget configuration

Source: https://gethomepage.dev/widgets/services/qbittorrent

Configure the Homepage qBittorrent widget. Authenticate with either the WebUI username/password or an API Key (qBittorrent ≥ v5.2.0) located in Options > WebUI > Authentication > API Key. Allowed fields are leech, download, seed, and upload; enableLeechProgress and enableLeechSize are optional and default to false.

```yaml
widget:
  type: qbittorrent
  url: http://qbittorrent.host.or.ip
  username: username
  password: password
  key: qbt_apikey # required if using API key instead of username/password
  enableLeechProgress: true # optional, defaults to false
  enableLeechSize: true # optional, defaults to false
```

--------------------------------

### Configure resources widget with all options

Source: https://gethomepage.dev/widgets/info/resources

Configures the resources widget with all available options: cpu, memory, disk, cputemp, uptime, units, refresh, diskUnits, and network. The disk path must be the mount point reported by df, and any disk must be mounted to the container as a volume. The cpu and memory values reflect container usage, while glances shows host statistics.

```yaml
- resources:
    cpu: true
    memory: true
    disk: /disk/mount/path
    cputemp: true
    tempmin: 0 # optional, minimum cpu temp
    tempmax: 100 # optional, maximum cpu temp
    uptime: true
    units: imperial # only used by cpu temp, options: 'imperial' or 'metric'
    refresh: 3000 # optional, in ms
    diskUnits: bytes # optional, bytes (default) or bbytes. Only applies to disk
    network: true # optional, uses 'default' if true or specify a network interface name
```

--------------------------------

### Widget configuration in services.yaml

Source: https://gethomepage.dev/widgets/authoring/metadata

Shows how to configure a widget in the services.yaml file, including the widget type, URL, and other properties.

```yaml
- Services:
    - Your Widget:
        icon: yourwidget.svg
        href: https://example.com/
        widget:
          type: yourwidget
          url: http://127.0.0.1:1337

```

--------------------------------

### component.jsx - useTranslation hook

Source: https://gethomepage.dev/widgets/authoring/tutorial

Gets the translation helper function t from the useTranslation hook.

```javascript
const { t } = useTranslation();
```

--------------------------------

### Run the server with HOMEPAGE_ALLOWED_HOSTS

Source: https://gethomepage.dev/installation/source

Runs the server with the HOMEPAGE_ALLOWED_HOSTS environment variable set to gethomepage.dev:1234.

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

--------------------------------

### list_config_files

Source: https://gethomepage.dev/configs/mcp

Lists supported config files, whether they exist, and links to the related docs.

```APIDOC
## MCP Tool: list_config_files

### Description
Lists supported config files, whether they exist, and links to the related documentation.

### Method
MCP Tool

### Parameters
None

### Response
- **files** (array) - List of config files with existence status and documentation links.
```

--------------------------------

### Configure greeting widget with text_size and text

Source: https://gethomepage.dev/widgets/info/greeting

YAML configuration for the greeting widget. Set text_size to one of the valid sizes (4xl, 3xl, 2xl, xl, md, sm, xs) and text to the desired greeting text.

```yaml
- greeting:
    text_size: xl
    text: Greeting Text

```

--------------------------------

### 24-hour time format with hourCycle h23

Source: https://gethomepage.dev/widgets/info/datetime

Example using hourCycle: h23 to display time in 24-hour format (13:37).

```yaml
# 13:37
format:
  timeStyle: short
  hourCycle: h23

```

--------------------------------

### Docker Compose MCP environment block

Source: https://gethomepage.dev/configs/mcp

Example Docker Compose environment block to enable MCP with authentication and a token.

```yaml
environment:
  HOMEPAGE_MCP_ENABLED: "true"
  HOMEPAGE_AUTH_ENABLED: "true"
  HOMEPAGE_MCP_TOKEN: "generate-with-openssl-rand-base64-32"

```

--------------------------------

### Configure Your Spotify widget

Source: https://gethomepage.dev/widgets/services/yourspotify

Configure the Your Spotify widget in Homepage. Set the server URL (add /api/ if using the lsio image), your API key, and optionally set the interval to one of day, week, month, year, or all; it defaults to week.

```yaml
widget:
  type: yourspotify
  url: http://your-spotify-server.host.or.ip # if using lsio image, add /api/
  key: apikeyapikeyapikeyapikeyapikey
  interval: month # optional, defaults to week

```

--------------------------------

### Dutch locale with long date and time

Source: https://gethomepage.dev/widgets/info/datetime

Example using locale: nl to display date and time in Dutch long formats.

```yaml
# 4 januari 2023 om 13:51:25 PST
locale: nl
format:
  dateStyle: long
  timeStyle: long

```

--------------------------------

### 12-hour time format with hour12 true

Source: https://gethomepage.dev/widgets/info/datetime

Example using hour12: true to display time in 12-hour format with AM/PM (1:37 PM).

```yaml
# 1:37 PM
format:
  timeStyle: short
  hour12: true

```

--------------------------------

### Gotify widget configuration

Source: https://gethomepage.dev/widgets/services/gotify

Configure the Gotify widget in Homepage. Requires a client token from the Gotify admin page. The url field should be the Gotify host or IP, and key is the client token. Allowed fields are apps, clients, and messages.

```yaml
widget:
  type: gotify
  url: http://gotify.host.or.ip
  key: clientoken

```

--------------------------------

### headers property example

Source: https://gethomepage.dev/widgets/authoring/metadata

Adds custom headers to the API request using the `headers` property. Include this when your endpoint requires specific headers.

```javascript
const widgetExample = {
  api: "{url}/api/{endpoint}",
  mappings: {
    // `/api/stats`
    stats: {
      endpoint: "stats",
      headers: {
        "Content-Type": "application/json",
      },
    },
  },
};

```

--------------------------------

### Quick Launch configuration with custom search provider

Source: https://gethomepage.dev/configs/settings

Configures Quick Launch to use a custom search provider with a custom URL, target, and suggestion URL. The suggestionUrl is required for search suggestions to work with custom providers.

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

```

--------------------------------

### Fake API response for v1/info

Source: https://gethomepage.dev/widgets/authoring/tutorial

Example JSON response from the fake API when called with the v1/info endpoint. It shows the data structure that the widget will receive.

```json
{ "key1": 123, "key2": 456, "key3": 789 }
```

--------------------------------

### Configure slskd API key for Homepage widget

Source: https://gethomepage.dev/widgets/services/slskd

Add this to the `web > authentication > api_keys` section of your `path/to/config/slskd.yml` to grant the Homepage widget read-only access. The `key` must match the generated API key, and `cidr` should be your Homepage subnet.

```yaml
homepage_widget:
  key: <generated key>
  role: readonly
  cidr: <homepage subnet>

```

--------------------------------

### endpoint property example

Source: https://gethomepage.dev/widgets/authoring/metadata

Defines a single endpoint mapping using the `endpoint` property. The value of `endpoint` replaces the `{endpoint}` placeholder in the `api` property.

```javascript
const widgetExample = {
  api: "{url}/api/{endpoint}",
  mappings: {
    // `/api/stats`
    stats: {
      endpoint: "stats",
    },
  },
};

```

--------------------------------

### Enable full width layout

Source: https://gethomepage.dev/configs/settings

Makes the homepage take up the entire window width. This is a global setting.

```yaml
fullWidth: true

```

--------------------------------

### Define nested groups in services.yaml

Source: https://gethomepage.dev/configs/services

Groups can be nested by using the same format as top-level groups. This example shows a nested group within Group A.

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

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

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

```

--------------------------------

### Basic widget configuration with dot notation

Source: https://gethomepage.dev/configs/docker

Configure a single widget (e.g., Emby) using dot notation in service labels. The 'fields' array is optional and uses list syntax.

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

```

--------------------------------

### JDownloader widget configuration

Source: https://gethomepage.dev/widgets/services/jdownloader

Basic widget configuration for JDownloader. Requires the JDownloader username, password, and the name of the JDownloader instance. Displays download count, total bytes, remaining bytes, and speed.

```yaml
widget:
  type: jdownloader
  username: JDownloader Username
  password: JDownloader Password
  client: Name of JDownloader Instance

```

--------------------------------

### Service configuration: Connect to Docker container

Source: https://gethomepage.dev/configs/docker

Inside a service entry, specify the configured Docker server and container name to get stats and status.

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

```

--------------------------------

### docker.yaml: Configure Docker instance with socket

Source: https://gethomepage.dev/configs/docker

Defines a Docker instance named 'my-docker' using the local Docker socket.

```yaml
my-docker:
  socket: /var/run/docker.sock

```

--------------------------------

### Configure Synology Download Station widget

Source: https://gethomepage.dev/widgets/services/downloadstation

Configure the Synology Download Station widget in Homepage. Requires the Download Station URL, username, and password. The widget is not compatible with 2FA. Allowed fields are leech, download, seed, and upload.

```yaml
widget:
  type: downloadstation
  url: http://downloadstation.host.or.ip:port
  username: username
  password: password

```

--------------------------------

### NextDNS widget configuration

Source: https://gethomepage.dev/widgets/services/nextdns

YAML configuration for the NextDNS widget. Requires the profile ID from Setup > Endpoints > ID and the API key from Account > API.

```yaml
widget:
  type: nextdns
  profile: profileid
  key: yourapikeyhere

```

--------------------------------

### ConfigMap manifest for Homepage configuration

Source: https://gethomepage.dev/installation/k8s

ConfigMap that holds Homepage configuration files. It includes example bookmarks, services, widgets, and a commented-out settings.yaml for Longhorn provider.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: homepage
  namespace: default
  labels:
    app.kubernetes.io/name: homepage
data:
  kubernetes.yaml: |
    mode: cluster
  settings.yaml: ""
  #settings.yaml: |
  #  providers:
  #    longhorn:
  #      url: https://longhorn.my.network
  custom.css: ""
  custom.js: ""
  bookmarks.yaml: |
    - Developer:
        - Github:
            - abbr: GH
              href: https://github.com/
  services.yaml: |
    - My First Group:
        - My First Service:
            href: http://localhost/
            description: Homepage is awesome

    - My Second Group:
        - My Second Service:
            href: http://localhost/
            description: Homepage is the best

    - My Third Group:
        - My Third Service:
            href: http://localhost/
            description: Homepage is 😎
  widgets.yaml: |
    - kubernetes:
        cluster:
          show: true
          cpu: true
          memory: true
          showLabel: true
          label: "cluster"
        nodes:
          show: true
          cpu: true
          memory: true
          showLabel: true
    - resources:
        backend: resources
        expanded: true
        cpu: true
        memory: true
        network: default
    - search:
        provider: duckduckgo
        target: _blank
  docker.yaml: ""

```

--------------------------------

### Set permissions and ownership for Homepage config folders

Source: https://gethomepage.dev/installation/unraid

Run these commands in the Homepage container console to set folder permissions and ownership so you can edit configuration files.

```bash
chmod -R u-x,go-rwx,go+u,ugo+X /app/config
```

```bash
chmod -R u-x,go-rwx,go+u,ugo+X /app/public/icons
```

```bash
chown -R nobody:users /app/config
```

```bash
chown -R nobody:users /app/public/icons
```

--------------------------------

### ruTorrent widget configuration

Source: https://gethomepage.dev/widgets/services/rutorrent

Configure the ruTorrent widget in Homepage. Requires the httprpc plugin to be installed and enabled. The username and password fields are optional; set to false if not used.

```yaml
widget:
  type: rutorrent
  url: http://rutorrent.host.or.ip
  username: username # optional, false if not used
  password: password # optional, false if not used

```

--------------------------------

### Custom Proxy Handler Example

Source: https://gethomepage.dev/widgets/authoring/proxies

A simple proxy handler that fetches data from an API and passes it to the widget. It uses the httpProxy utility and returns the response status and data.

```javascript
import createLogger from "utils/logger";
import { httpProxy } from "utils/proxy/http";

const logger = createLogger("customProxyHandler");

export default async function customProxyHandler(req, res, map) {
  const { url } = req.query;

  const [status, contentType, data] = await httpProxy(url);

  return res.status(status).send(data);
}
```

--------------------------------

### validate property example

Source: https://gethomepage.dev/widgets/authoring/metadata

Uses the `validate` property to require the API response to contain the keys `total` and `average`. If the response does not contain all specified keys, the widget will not render.

```javascript
const widgetExample = {
  api: "{url}/api/{endpoint}",
  mappings: {
    // `/api/stats`
    stats: {
      endpoint: "stats",
      validate: ["total", "average"],
    },
  },
};

```

--------------------------------

### Configure Glances widget with all options

Source: https://gethomepage.dev/widgets/services/glances

Base configuration for the Glances widget. The `url` is required; `username` and `password` are only needed if auth is enabled in Glances. `version` must be set to 4 for Glances v4 or higher (defaults to 3). `metric` selects the data to display (e.g., `cpu`). `diskUnits` applies only to disk metrics, `refreshInterval` defaults to 1000 ms or more depending on the metric, and `pointsLimit` defaults to 15.

```yaml
widget:
  type: glances
  url: http://glances.host.or.ip:port
  username: user # optional if auth enabled in Glances
  password: pass # optional if auth enabled in Glances
  version: 4 # required only if running glances v4 or higher, defaults to 3
  metric: cpu
  diskUnits: bytes # optional, bytes (default) or bbytes. Only applies to disk
  refreshInterval: 5000 # optional - in milliseconds, defaults to 1000 or more, depending on the metric
  pointsLimit: 15 # optional, defaults to 15

```

--------------------------------

### Configure Docker instance with IP and port

Source: https://gethomepage.dev/configs/docker

Basic configuration for connecting to a Docker instance over HTTP API using IP and port.

```yaml
my-remote-docker:
  host: 192.168.0.101
  port: 2375

```

--------------------------------

### Docker Compose configuration for Homepage

Source: https://gethomepage.dev/installation/docker

Basic Docker Compose configuration for running Homepage. Mounts the config directory and optionally the Docker socket for integrations. Requires the HOMEPAGE_ALLOWED_HOSTS environment variable.

```yaml
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    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
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev # required, may need port. See gethomepage.dev/installation/#homepage_allowed_hosts

```

--------------------------------

### genericProxyHandler basic usage

Source: https://gethomepage.dev/widgets/authoring/proxies

Use this handler for unauthenticated GET requests to an API endpoint. The api string uses {url} and {endpoint} placeholders that are replaced from the widget configuration.

```javascript
import genericProxyHandler from "utils/proxy/handlers/generic";

const widgetExample = {
  api: "{url}/api/{endpoint}",
  proxyHandler: genericProxyHandler,
};

```

--------------------------------

### Homebridge widget YAML configuration

Source: https://gethomepage.dev/widgets/services/homebridge

Configure the Homebridge widget with the type, URL, username, and password. The URL should point to the Homebridge instance with the Config UI X plugin installed.

```yaml
widget:
  type: homebridge
  url: http://homebridge.host.or.ip:port
  username: username
  password: password

```

--------------------------------

### Configure DiskStation widget

Source: https://gethomepage.dev/widgets/services/diskstation

Configure the DiskStation widget with the DSM URL, credentials, and an optional volume parameter. The volume value must be in the form volume_N (e.g., volume_2) to display free space for that volume; if omitted, the first returned volume's free space is shown. The account must be a member of the Administrators group to access system metrics.

```yaml
widget:
  type: diskstation
  url: http://diskstation.host.or.ip:port
  username: username
  password: password
  volume: volume_N # optional

```

--------------------------------

### Configure What's Up Docker widget

Source: https://gethomepage.dev/widgets/services/whatsupdocker

Configure the What's Up Docker widget in Homepage. The url is required, while username/password or a bearer token (key) can be used for authentication; key takes precedence over username/password.

```yaml
widget:
  type: whatsupdocker
  url: http://whatsupdocker:port
  username: username # optional
  password: password # optional
  key: bearer-token # optional, takes precedence over username/password

```

--------------------------------

### UrBackup widget configuration

Source: https://gethomepage.dev/widgets/services/urbackup

YAML configuration for the UrBackup widget. Requires username, password, and URL. The maxDays option is optional and defaults to 3. Disk usage is not shown unless totalUsed is included in fields.

```yaml
widget:
  type: urbackup
  username: urbackupUsername
  password: urbackupPassword
  url: http://urbackupUrl:55414
  maxDays: 5 # optional

```

--------------------------------

### Docker Compose for docker-socket-proxy and homepage

Source: https://gethomepage.dev/configs/docker

Docker Compose setup that runs a docker-socket-proxy container and connects it to the homepage container. The proxy restricts access to read-only operations and mounts the Docker socket as read-only.

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

```
Tokens:
Raw