### Start Homepage Server

Source: https://github.com/gethomepage/homepage/blob/dev/README.md

Run the Homepage server in production mode after installation. Ensure HOMEPAGE_ALLOWED_HOSTS is set.

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

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

### Install dependencies and build

Source: https://github.com/gethomepage/homepage/blob/dev/docs/installation/source.md

Install project dependencies and compile the production bundle.

```bash
pnpm install
pnpm build
```

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

### Install Dependencies and Build

Source: https://github.com/gethomepage/homepage/blob/dev/README.md

Install project dependencies and build the production bundle using pnpm.

```bash
pnpm install
pnpm build
```

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

### Configure Start URL

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/settings.md

Defines the start URL for installable PWA applications.

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

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

### Install Documentation Dependencies

Source: https://github.com/gethomepage/homepage/blob/dev/README.md

Installs the necessary dependencies to run the Zensical documentation locally. This command synchronizes the required packages.

```bash
uv sync
```

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

### Install Homepage Helm Chart

Source: https://github.com/gethomepage/homepage/blob/dev/kubernetes.md

Install the Homepage application using the provided Helm chart. Ensure you have Helm installed and the repository added.

```sh
helm repo add jameswynn https://jameswynn.github.io/helm-charts
helm install my-release jameswynn/homepage
```

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

### Start the server

Source: https://github.com/gethomepage/homepage/blob/dev/docs/installation/source.md

Launch the homepage server with the required environment variable.

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

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

### Example Docker Compose Environment

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/mcp.md

This example shows how to configure MCP and authentication in a Docker Compose environment block. Remember to change the default token.

```yaml
environment:
  HOMEPAGE_MCP_ENABLED: "true"
  HOMEPAGE_AUTH_ENABLED: "true"
  HOMEPAGE_MCP_TOKEN: "change-me"
```

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

### Start Homepage Development Server

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/getting-started.md

Starts the local development server for the Homepage project. This allows for real-time development and testing of features. The application will be accessible at http://localhost:3000.

```bash
pnpm dev
```

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

### HDHomerun Widget Configuration Example

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/hdhomerun.md

Example YAML configuration for the HDHomerun widget. Specify the widget type, HDHomerun URL, optional tuner, and desired fields.

```yaml
widget:
  type: hdhomerun
  url: http://hdhomerun.host.or.ip
  tuner: 0 # optional - defaults to 0, used for tuner-specific fields
  fields: ["channels", "hd"] # optional - default fields shown
```

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

### Configure Widget Metadata: Advanced Example (JavaScript)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/metadata.md

An advanced example of widget metadata configuration, utilizing a credentialed proxy handler and more complex mappings with data transformation and filtering.

```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;
      },
    },
  },
};
```

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

### Install Dependencies with pnpm

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/getting-started.md

Installs all necessary project dependencies using the pnpm package manager. This is a prerequisite for running the development server and other project commands.

```bash
pnpm install
```

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

### Serve or Build Documentation

Source: https://github.com/gethomepage/homepage/blob/dev/README.md

Starts the Zensical documentation development server or builds the static documentation site. Use 'serve' for local development and 'build' for creating the static files.

```bash
uv run zensical serve
```

```bash
uv run zensical build
```

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

### Configure Widget Metadata: Basic Example (JavaScript)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/metadata.md

A basic example of a widget's metadata object, defining the API endpoint and a generic proxy handler. It includes a simple mapping for stats.

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

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

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

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

### Install pnpm

Source: https://github.com/gethomepage/homepage/blob/dev/docs/installation/source.md

Install the pnpm package manager globally if it is not already present.

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

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

### Arcane Widget Configuration Example

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/arcane.md

Example configuration for the Arcane widget. Set the widget type, URL, environment, API key, and optionally specify fields to display.

```yaml
widget:
  type: arcane
  url: http://localhost:3552
  env: 0 # required, 0 is Arcane default local environment
  key: your-api-key
  fields: ["running", "stopped", "total", "image_updates"] # optional
```

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

### Configure Info Widgets in widgets.yaml

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/index.md

Demonstrates the configuration of Info widgets within the `widgets.yaml` file. This example shows how to set up an 'openmeteo' widget, including its label, latitude, longitude, and cache duration for displaying weather information.

```yaml
- openmeteo:
    label: Current
    latitude: 36.66
    longitude: -117.51
    cache: 5
```

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

### Configure Docker Service Integration

Source: https://github.com/gethomepage/homepage/blob/dev/docs/installation/unraid.md

Example YAML configuration for adding a service to Homepage using the container parameter for Docker integration.

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

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

### Clone Homepage Repository

Source: https://github.com/gethomepage/homepage/blob/dev/README.md

Clone the official Homepage repository from GitHub to begin installation from source.

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

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

### Gitea Widget Configuration Example (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/gitea.md

This snippet shows a basic YAML configuration for the Gitea widget. It specifies the widget type, the Gitea instance URL, and the API key. Ensure the API key has the required permissions.

```yaml
widget:
  type: gitea
  url: http://gitea.host.or.ip:port
  key: giteaapitoken
```

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

### Configure Widget API Endpoint (JavaScript)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/metadata.md

Example demonstrating the `api` property in widget metadata, which specifies the URL for fetching data and supports runtime placeholders.

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

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

### Unraid Widget Configuration Example (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/unraid.md

This YAML configuration defines the settings for the Unraid widget, specifying the server URL, API key, and optional pool names for detailed monitoring. It allows selection from a predefined list of metrics.

```yaml
widget:
  type: unraid
  url: https://unraid.host.or.ip
  key: api-key
  pool1: pool1name # required only if using pool1 fields
  pool2: pool2name # required only if using pool2 fields
  pool3: pool3name # required only if using pool3 fields
  pool4: pool4name # required only if using pool4 fields
```

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

### Implement Widget Container and Block Components

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/component.md

Examples of using the Container wrapper for layout and the Block component for displaying key-value pairs. These components ensure a consistent look and feel across all widgets.

```jsx
<Container service={service}></Container>
<Container service={service} error={error}></Container>
<Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
<Container service={service}>
  <Block label="yourwidget.key1" />
  <Block label="yourwidget.key2" />
  <Block label="yourwidget.key3" />
</Container>
```

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

### pfSense Widget Configuration (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/pfsense.md

Example YAML configuration for the pfSense widget, showing settings for API URL, authentication, monitored interface, and desired fields. Supports different API versions.

```yaml
widget:
  type: pfsense
  url: http://pfsense.host.or.ip:port
  username: user # optional, or API key
  password: pass # optional, or API key
  headers: # optional, or username/password
    X-API-Key: key
  wan: igb0
  version: 2 # optional, defaults to 1 for api v1
  fields: ["load", "memory", "temp", "wanStatus"] # optional
```

```yaml
headers: # optional, or username/password
  Authorization: client_id client_token # obtained from pfSense API
version: 1
```

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

### Deploy Homepage with Docker Run

Source: https://github.com/gethomepage/homepage/blob/dev/docs/installation/docker.md

A single-line command to start the Homepage container using the docker run utility. It maps ports, mounts volumes, and sets the required environment variables.

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

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

### Configure Multiple Service Widgets in YAML

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/services.md

This YAML example demonstrates configuring multiple widgets for a single service. It shows how to define an array of widgets, each with its own type, URL, and specific parameters like API keys or slugs.

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

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

### Configure Proxmox Services

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/proxmox.md

Examples for defining services that track Proxmox resources. Supports both QEMU VMs and LXC containers by specifying the node name, VM ID, and optional container type.

```yaml
- HomeAssistant:
  icon: home-assistant.png
  href: http://homeassistant.local/
  description: Home automation
  proxmoxNode: pve
  proxmoxVMID: 101

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

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

### Synology Disk Station Widget Configuration Example

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/diskstation.md

This YAML snippet shows the basic configuration for the Synology Disk Station widget. It includes the widget type, the DiskStation's URL, username, password, and an optional volume parameter to specify which volume's free space to display.

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

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

### Configure Sonarr Widget (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/sonarr.md

Example YAML configuration for the Sonarr widget. This includes the Sonarr instance URL, API key, and an optional flag to enable detailed queue listing. Ensure the URL and API key are correctly set for proper functionality.

```yaml
widget:
  type: sonarr
  url: http://sonarr.host.or.ip
  key: apikeyapikeyapikeyapikeyapikey
  enableQueue: true # optional, defaults to false
```

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

### Configure Widget Mappings with Data Processing (JavaScript)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/metadata.md

Example of the `mappings` property in widget metadata, showing how to define API endpoints, validation rules, and data mapping functions.

```javascript
import { asJson } from "utils/proxy/api-helpers";

const widgetExample = {
  api: "{url}/api/{endpoint}",
  mappings: {
    // `/api/stats?start=...&end=...`
    stats: {
      endpoint: "stats",
      validate: ["total", "average"],
      params: ["start", "end"],
    },
    // `/api/notices`
    notices: {
      endpoint: "notices",
      map: (data) => {
        total: asJson(data).length;
      },
    },
  },
};
```

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

### Example MCP List Config Files Request

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/mcp.md

This cURL command demonstrates how to request a list of configuration files using the MCP endpoint. It includes the necessary headers and a JSON-RPC payload.

```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"}'
```

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

### Navidrome Widget Configuration Example (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/navidrome.md

This snippet shows the basic configuration structure for the Navidrome widget. It includes the widget type, server URL, username, and authentication token details. The token is generated using MD5 hashing of the password and a salt.

```yaml
widget:
  type: navidrome
  url: http://navidrome.host.or.ip:port
  user: username
  token: token #md5(password + salt)
  salt: randomsalt
```

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

### Configure Manual Service Widget

Source: https://github.com/gethomepage/homepage/blob/dev/kubernetes.md

Manually configure a Service Widget by specifying the application name and namespace. This example configures a Home Assistant widget.

```yaml
- Home Automation
    - Home-Assistant:
        icon: home-assistant.png
        href: https://home.example.com
        description: Home Automation
        app: home-assistant
        namespace: home
```

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

### Unmanic Widget Configuration Example (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/unmanic.md

This YAML snippet demonstrates the basic configuration for the Unmanic widget. It requires the widget type to be set to 'unmanic' and specifies the URL for the Unmanic instance. Ensure the URL includes the correct host or IP address and port.

```yaml
widget:
  type: unmanic
  url: http://unmanic.host.or.ip:port
```

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

### Wallos Widget Configuration Example (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/wallos.md

This snippet shows a basic YAML configuration for the Wallos widget. It specifies the widget type, the URL for the Wallos service, and an API key for authentication. This configuration is essential for integrating Wallos into your project.

```yaml
widget:
  type: wallos
  url: http://wallos.host.or.ip
  key: apikeyapikeyapikeyapikeyapikey
```

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

### Configure Mailcow Widget

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/mailcow.md

Example configuration for the Mailcow widget. Ensure you replace 'mailcow.host.or.ip' with your Mailcow server's actual address and 'mailcowapikey' with your generated API key.

```yaml
widget:
  type: mailcow
  url: https://mailcow.host.or.ip
  key: mailcowapikey
```

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

### EVCC Widget Configuration Example (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/evcc.md

This snippet shows a basic YAML configuration for the EVCC widget. It specifies the widget type and the URL to connect to the EVCC instance. Ensure the URL points to your running EVCC service.

```yaml
widget:
  type: evcc
  url: http://evcc.host.or.ip:port
```

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

### Assign Docker Instance to a Service

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/docker.md

Example configuration for assigning a previously configured Docker instance to a service within the homepage application for stats and status reporting.

```yaml
- Emby:
  icon: emby.png
  href: "http://emby.home/"
  description: Media server
  server: my-docker
  container: emby
```

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

### Complete Widget Component File (React/JSX)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/tutorial.md

Presents the entire 'component.jsx' file, combining all previously shown code snippets. This provides a full example of the widget component's implementation.

```jsx
import { useTranslation } from "next-i18next";

import Container from "components/services/widget/container";
import Block from "components/services/widget/block";
import useWidgetAPI from "utils/proxy/use-widget-api";

export default function Component({ service }) {
  const { t } = useTranslation();
  const { widget } = service;

```

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

### Pulse Widget Configuration Example

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/pulse.md

This YAML snippet shows the basic configuration for the Pulse widget. Ensure the 'key' field has an API token with the 'monitoring:read' scope. The 'fields' array is optional and specifies which data points to display.

```yaml
widget:
  type: pulse
  url: http://pulse.host.or.ip:7655
  key: your-api-token # `monitoring:read` scope is required
  fields: ["nodes", "vms", "lxcs"] # optional
```

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

### Mikrotik Widget Configuration (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/mikrotik.md

Example configuration for the Mikrotik widget in YAML format. This includes the widget type, the Mikrotik host or IP address, and authentication credentials. HTTPS is recommended for secure communication.

```yaml
widget:
  type: mikrotik
  url: https://mikrotik.host.or.ip
  username: username
  password: password
```

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

### PhotoPrism Widget Configuration (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/photoprism.md

Example YAML configuration for the PhotoPrism widget. It specifies the widget type, PhotoPrism instance URL, and authentication credentials. Authentication can be done using either a username/password pair or an app-specific password.

```yaml
widget:
  type: photoprism
  url: http://photoprism.host.or.ip:port
  username: admin # required only if using username/password
  password: password # required only if using username/password
  key: # required only if using app passwords
```

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

### Configure Quick Launch

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/settings.md

Set global options for the Quick Launch feature, including search providers and behavior.

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

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

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

### Configure Home Assistant Widget via YAML

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/homeassistant.md

This YAML configuration demonstrates how to connect to a Home Assistant instance using a URL and access token. It also shows how to define custom states and templates to monitor specific entities like power sensors, energy usage, and switch counts.

```yaml
widget:
  type: homeassistant
  url: http://homeassistant.host.or.ip:port
  key: access_token
  custom:
    - state: sensor.total_power
    - state: sensor.total_energy_today
      label: energy today
    - template: "{{ states.switch|selectattr('state','equalto','on')|list|length }}"
      label: switches on
    - state: weather.forecast_home
      label: wind speed
      value: "{attributes.wind_speed} {attributes.wind_speed_unit}"
```

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

### Configure Widget Field Visibility in YAML

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/services.md

This YAML example demonstrates how to specify which fields should be visible for a service widget. By using the `fields` property, you can control the displayed information, as shown with the Sonarr service example which limits fields to 'wanted' and 'queued'.

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

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

### Configure Multiple Homepage Instances

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/docker.md

Demonstrates how to scope specific labels to a particular Homepage instance using the instance name in the label key.

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

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

### GET /gethomepage/homepage

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/iframe.md

Configuration schema for the iFrame widget used to embed external content.

```APIDOC
## GET /gethomepage/homepage

### Description
Defines the configuration for an iFrame widget to display external content. Note that requests are made directly from the browser and are not proxied.

### Method
GET

### Endpoint
/gethomepage/homepage

### Request Body
- **widget** (object) - Required - The widget configuration object.
  - **type** (string) - Required - Must be "iframe".
  - **name** (string) - Required - Unique identifier for the widget.
  - **src** (string) - Required - The URL to be displayed in the iFrame.
  - **classes** (string) - Optional - Tailwind CSS height classes.
  - **referrerPolicy** (string) - Optional - Referrer policy for the iFrame.
  - **allowPolicy** (string) - Optional - Permissions policy string.
  - **allowFullscreen** (boolean) - Optional - Whether to allow fullscreen mode (default: true).
  - **loadingStrategy** (string) - Optional - Loading strategy (default: "eager").
  - **allowScrolling** (string) - Optional - Whether to allow scrolling (default: "yes").
  - **refreshInterval** (integer) - Optional - Refresh interval in milliseconds.

### Request Example
```yaml
widget:
  type: iframe
  name: myIframe
  src: http://example.com
  classes: h-60
  allowFullscreen: false
```

### Response
#### Success Response (200)
- **status** (string) - Success message indicating the widget configuration was retrieved.
```

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

### GET /gethomepage/homepage

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/homeassistant.md

Retrieves the current state and custom template data from a configured Home Assistant instance.

```APIDOC
## GET /gethomepage/homepage

### Description
Retrieves status information from Home Assistant based on provided configuration fields or custom state/template queries.

### Method
GET

### Endpoint
/gethomepage/homepage

### Parameters
#### Query Parameters
- **url** (string) - Required - The base URL of the Home Assistant instance (e.g., http://host:port)
- **key** (string) - Required - The long-lived access token for authentication
- **fields** (array) - Optional - Allowed fields: ["people_home", "lights_on", "switches_on"]
- **custom** (array) - Optional - List of custom state or template objects to query

### Request Example
{
  "url": "http://homeassistant.local:8123",
  "key": "ABC123TOKEN",
  "custom": [
    { "state": "sensor.total_power" },
    { "template": "{{ states.switch|list|length }}", "label": "switches on" }
  ]
}

### Response
#### Success Response (200)
- **data** (object) - The requested state values and template results

#### Response Example
{
  "sensor.total_power": "150 W",
  "switches on": "5"
}
```

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

### Configure PWA Icons

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/settings.md

Define custom icons for installable apps using full URLs or local paths relative to /app/public.

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

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

### Clone the repository

Source: https://github.com/gethomepage/homepage/blob/dev/docs/installation/source.md

Initial step to download the source code from GitHub.

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

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

### Lint Code with pnpm

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/getting-started.md

Lints the project's codebase to ensure code quality and consistency. This command should be run after installing dependencies.

```bash
pnpm lint
```

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

### Add Service Example

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/mcp.md

This JSON payload can be sent to the MCP endpoint to add a new service entry to services.yaml. Ensure HOMEPAGE_MCP_ALLOW_WRITE is enabled.

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

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

### Add Info Widget Example

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/mcp.md

This JSON payload can be used with the MCP endpoint to add a new information widget to widgets.yaml. Ensure HOMEPAGE_MCP_ALLOW_WRITE is enabled.

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

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

### Enable Full Width Layout

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/settings.md

Set the homepage to occupy the entire window width.

```yaml
fullWidth: true
```

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

### Kubernetes Ingress for Service Discovery

Source: https://github.com/gethomepage/homepage/blob/dev/kubernetes.md

Define a Kubernetes Ingress resource to enable service discovery for Homepage. This example sets up an Ingress for the Homepage service.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: homepage
  annotations:
    gethomepage.dev/enabled: "true"
    gethomepage.dev/description: Dynamically Detected Homepage
    gethomepage.dev/group: Operations
    gethomepage.dev/icon: homepage.png
    gethomepage.dev/name: Homepage
spec:
  rules:
    - host: homepage.example.com
      http:
        paths:
          - backend:
              service:
                name: homepage
                port:
                  number: 3000
            path: /
            pathType: Prefix
```

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

### Configure Service via Docker Labels

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/docker.md

Demonstrates how to define a service in a Docker Compose file using homepage-specific labels for automatic discovery.

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

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

### Map API JSON Data

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/customapi.md

Example of mapping specific JSON fields from an API response to widget labels using dot notation or array indexing.

```yaml
mappings:
  - field: name
    label: Name
  - field: status
    label: Status
  - field: origin.name
    label: Origin
  - field: locations.1.name
    label: Location
```

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

### GET /gethomepage/homepage (Azure DevOps Widget)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/azuredevops.md

Configures and retrieves data for the Azure DevOps widget, supporting both pipeline status tracking and pull request metrics.

```APIDOC
## GET /gethomepage/homepage

### Description
Retrieves status updates for Azure DevOps pipelines or metrics for pull requests based on the provided configuration parameters.

### Method
GET

### Endpoint
/gethomepage/homepage

### Parameters
#### Request Body (Configuration Object)
- **type** (string) - Required - Must be "azuredevops"
- **organization** (string) - Required - The Azure DevOps organization name
- **project** (string) - Required - The project name
- **definitionId** (string) - Optional - Required for pipeline queries
- **branchName** (string) - Optional - Specific branch for pipeline tracking
- **userEmail** (string) - Optional - Required for pull request queries
- **repositoryId** (string) - Optional - Required for pull request queries
- **key** (string) - Required - Personal Access Token (PAT)

### Request Example
{
  "widget": {
    "type": "azuredevops",
    "organization": "myOrganization",
    "project": "myProject",
    "definitionId": "pipelineDefinitionId",
    "userEmail": "email",
    "repositoryId": "prRepositoryId",
    "key": "personalaccesstoken"
  }
}

### Response
#### Success Response (200)
- **result** (string) - Pipeline status result
- **status** (string) - Pipeline execution status
- **totalPrs** (integer) - Count of open PRs
- **myPrs** (integer) - Count of PRs opened by the user
- **approved** (integer) - Count of user PRs with at least one approval

#### Response Example
{
  "result": "succeeded",
  "status": "completed",
  "totalPrs": 5,
  "myPrs": 2,
  "approved": 1
}
```

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

### JDownloader Widget Configuration (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/jdownloader.md

This YAML configuration sets up the JDownloader widget. It requires user credentials and the client name for the JDownloader instance. The widget can display various download queue metrics.

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

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

### Configure Traefik Widget

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/traefik.md

Example YAML configuration for the Traefik widget. This specifies the widget type, the Traefik instance URL, and optional username and password for authentication if required.

```yaml
widget:
  type: traefik
  url: http://traefik.host.or.ip
  username: username # optional
  password: password # optional
```

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

### Docker Compose for Docker Socket Proxy

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/docker.md

Example docker-compose configuration to set up a docker-socket-proxy container. This proxy exposes the Docker socket with restricted access, enhancing security.

```yaml
dockerproxy:
  image: ghcr.io/tecnativa/docker-socket-proxy:latest
  container_name: dockerproxy
  environment:
    - CONTAINERS=1
    - SERVICES=1
    - TASKS=1
    - POST=0
  ports:
    - 127.0.0.1:2375:2375
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
  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
```

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

### Define Multiple Glances Metrics

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/glances.md

Examples of defining multiple monitoring widgets for different system metrics such as CPU and network usage. Each entry acts as a standalone service block.

```yaml
- CPU Usage:
    widget:
      type: glances
      url: http://glances.host.or.ip:port
      metric: cpu
- Network Usage:
    widget:
      type: glances
      url: http://glances.host.or.ip:port
      metric: network:enp0s25
```

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

### Configure Uptime Kuma Widget (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/uptime-kuma.md

This YAML configuration snippet shows how to set up the Uptime Kuma widget. It requires the widget type, the URL of the Uptime Kuma instance, and the slug of the status page to be monitored. Ensure the URL includes the correct port if it's not the default.

```yaml
widget:
  type: uptimekuma
  url: http://uptimekuma.host.or.ip:port
  slug: statuspageslug
```

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

### Docker Compose for Direct Socket Access

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/docker.md

Example docker-compose configuration for the homepage container to directly access the host's Docker socket. Ensure the socket is mounted as a volume.

```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
  ports:
    - 3000:3000
  restart: unless-stopped
```

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

### Configure Moonraker Widget

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/moonraker.md

Basic configuration for the Moonraker widget using the printer's host URL. This setup allows the widget to retrieve printer status and progress information.

```yaml
widget:
  type: moonraker
  url: http://moonraker.host.or.ip:port
```

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

### qBittorrent Widget Configuration

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/qbittorrent.md

Configure the qBittorrent widget with your WebUI URL, authentication credentials (username/password or API key), and optional fields like leech progress and size.

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

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/services.md

Demonstrates how to assign icons to services using local files, remote URLs, or integrated icon libraries like Material Design Icons and Simple Icons.

```yaml
- Group A:
    - Sonarr:
        icon: sonarr.png
        href: http://sonarr.host/
        description: Series management

- Group B:
    - Radarr:
        icon: radarr.png
        href: http://radarr.host/
        description: Movie management

- Group C:
    - Service:
        icon: mdi-flask-outline
        href: http://service.host/
        description: My cool service
```

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

### Configure Gotify Widget (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/gotify.md

This snippet shows the basic YAML configuration for the Gotify widget. It requires the Gotify server URL and a client access key. Ensure you replace the placeholder values with your actual Gotify server details and client token obtained from the Gotify admin page.

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

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

### SWAG Dashboard Widget YAML Configuration

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/swagdashboard.md

Example YAML configuration for setting up the SWAG Dashboard widget. It specifies the widget type and the URL for the SWAG Dashboard service, including the default port.

```yaml
widget:
  type: swagdashboard
  url: http://swagdashboard.host.or.ip:adminport # default port is 81
```

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

### Configure Your Spotify Widget in YAML

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/yourspotify.md

This YAML configuration block defines the widget type, server URL, API key, and data interval. Ensure the URL includes the /api/ path if using the LinuxServer.io Docker image.

```yaml
widget:
  type: yourspotify
  url: http://your-spotify-server.host.or.ip/api/
  key: apikeyapikeyapikeyapikeyapikey
  interval: month
```

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

### Define Nested Service Groups in YAML

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/services.md

This YAML example illustrates how to create nested service groups. A group can contain other groups, allowing for hierarchical organization of services. Each service requires an `href`.

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

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

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

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

### Configure Homebox Widget

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/homebox.md

This YAML configuration sets up the Homebox widget. It requires the widget type, the Homebox instance URL, and authentication credentials (username and password). Optionally, you can specify which fields to display, with a limit of the first four if more are provided. The `totalValue` field formatting depends on your Homebox currency configuration.

```yaml
widget:
  type: homebox
  url: http://homebox.host.or.ip:port
  username: username
  password: password
  fields: ["items", "locations", "totalValue"] # optional - default fields shown
```

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

### Configure Homepage to Use Docker Socket Directly

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/docker.md

Configure the homepage application to connect directly to the Docker socket. This requires passing the local Docker socket into the homepage container and may require running homepage as root.

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

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

### Configure Service Widget with Pod Selector

Source: https://github.com/gethomepage/homepage/blob/dev/kubernetes.md

Configure a Service Widget using a 'pod-selector' to target specific pods, useful for complex deployments. This example targets multiple Matrix Synapse related deployments.

```yaml
- Comms
    - Element Chat:
        icon: matrix-light.png
        href: https://chat.example.com
        description: Matrix Synapse Powered Chat
        app: matrix-element
        namespace: comms
        pod-selector: >-
            app.kubernetes.io/instance in (
                matrix-element,
                matrix-media-repo,
                matrix-media-repo-postgresql,
                matrix-synapse
            )
```

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

### Configure Headscale Widget

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/headscale.md

Use this YAML configuration to set up the Headscale widget. Ensure you replace placeholders with your actual Headscale URL, node ID, and API access token. API tokens can be generated via the `headscale apikeys create` command.

```yaml
widget:
  type: headscale
  url: http://headscale.host.or.ip:port
  nodeId: nodeid
  key: headscaleapiaccesstoken
```

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

### Define API Parameters for Stats Endpoint

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/authoring/metadata.md

This snippet demonstrates how to define parameters for an API endpoint. The `params` array specifies keys that will be replaced with actual values at runtime. This example uses JavaScript for a widget configuration.

```javascript
const widgetExample = {
  api: "{url}/api/{endpoint}",
  mappings: {
    // `/api/stats?start=...&end=`
    stats: {
      endpoint: "stats",
      params: ["start", "end"],
    },
  },
};
const { data: statsData, error: statsError } = useWidgetAPI(widget, "stats", {
  start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
  end: new Date(),
});
```

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

### Configure NetAlertX Widget in Homepage

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/netalertx.md

This YAML snippet demonstrates how to define the NetAlertX widget in the Homepage configuration file. It requires the base URL, an API token for authentication, and the appropriate version number to match your NetAlertX installation.

```yaml
widget:
  type: netalertx
  url: http://ip:port
  key: yournetalertxapitoken
  version: 2
```

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

### Configure Seerr Widget in YAML

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/seerr.md

This snippet demonstrates the required YAML structure to initialize the Seerr widget. It requires the base URL of your Seerr instance and a valid API key obtained from the application settings.

```yaml
widget:
  type: seerr
  url: http://seerr.host.or.ip
  key: apikeyapikeyapikeyapikeyapikey
```

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

### Deploy Homepage with Docker Compose

Source: https://github.com/gethomepage/homepage/blob/dev/docs/installation/docker.md

Standard configuration for running Homepage using a docker-compose.yml file. It maps ports, mounts configuration volumes, and sets required environment variables.

```yaml
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - /path/to/config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev
```

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

### QNAP Widget Basic Configuration (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/qnap.md

This YAML snippet shows the basic configuration for the QNAP widget. It includes the widget type, the device's URL, and authentication credentials. This configuration is essential for the widget to connect to and retrieve data from the QNAP device.

```yaml
widget:
  type: qnap
  url: http://qnap.host.or.ip:port
  username: user
  password: pass
```

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

### Configure Audiobookshelf Widget

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/audiobookshelf.md

Use this YAML configuration to set up the Audiobookshelf widget. Ensure you replace the placeholder URL and API key with your actual Audiobookshelf instance details.

```yaml
widget:
  type: audiobookshelf
  url: http://audiobookshelf.host.or.ip:port
  key: audiobookshelflapikey
```

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

### Apply Data Transformations

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/customapi.md

Demonstrates how to use transformation tools like remap, scale, prefix, and suffix to modify API data before display.

```yaml
- field: key4
  label: Field 4
  format: text
  remap:
    - value: 0
      to: None
    - value: 1
      to: Connected
    - any: true
      to: Unknown
- field: key5
  label: Power
  format: float
  scale: 0.001
  suffix: "kW"
- field: key6
  label: Price
  format: float
  prefix: "$"
```

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

### Configure Widgets via Docker Labels

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/docker.md

Shows how to attach widget metadata to a service using dot notation in Docker labels, including support for fields and multiple widgets.

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

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

### Configure Date & Time Widget Display (YAML)

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/info/datetime.md

This YAML configuration snippet demonstrates how to set up the datetime widget. It specifies the text size and formatting options for displaying the time, such as 'short' time style.

```yaml
- datetime:
    text_size: xl
    format:
      timeStyle: short
```

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

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

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

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

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

### Configure Widget with Custom HTTP Headers in YAML

Source: https://github.com/gethomepage/homepage/blob/dev/docs/configs/services.md

This YAML snippet shows how to add custom HTTP headers to a service widget configuration. This is useful for passing authentication tokens or other required headers to a reverse proxy. The example uses UptimeRobot.

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

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

### Configure Trilium Widget

Source: https://github.com/gethomepage/homepage/blob/dev/docs/widgets/services/trilium.md

Use this YAML configuration to set up the Trilium widget. Ensure you replace 'https://trilium.host.or.ip' with your Trilium instance's URL and 'etapi_token' with your actual ETAPI key.

```yaml
widget:
  type: trilium
  url: https://trilium.host.or.ip
  key: etapi_token
```