Sign in Subscribe

Install and configue Homepage

Install and configue Homepage

Homepage is a an open source dashboard for all of your services it is fairly easy to install and set up

Install using Docker Compose

Using docker compose:

version: "3.3"
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 # (optional) For docker integration

Configuration

Homepage uses YAML for configuration, YAML stands for "YAML Ain't Markup Language.". It's a human-readable data serialization format that's a superset of JSON. Great for config files, easy to read and write. Supports complex data types like lists and objects. Indentation matters. If you already use Docker Compose, you already use YAML.

Here are some tips when writing YAML:

  1. Use Indentation Carefully: YAML relies on indentation, not brackets.
  2. Avoid Tabs: Stick to spaces for indentation to avoid parsing errors. 2 spaces are common.
  3. Quote Strings: Use single or double quotes for strings with special characters, this is especially important for API keys.
  4. Key-Value Syntax: Use key: value format. Colon must be followed by a space.
  5. Validate: Always validate your YAML with a linter before deploying.

You can find tons of online YAML validators, here's one: https://codebeautify.org/yaml-validator, heres another: https://jsonformatter.org/yaml-validator.

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.

title: My Awesome Homepage

Start URL

You can customize the start_url as required for installable apps. The default is "/".

startUrl: https://custom.url

Background Image

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.

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.

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:

volumes:
  - /my/homepage/images:/app/public/images

and then reference that image:

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.

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.

cardBlur: sm # sm, "", md, etc... see https://tailwindcss.com/docs/backdrop-blur

Favicon

If you'd like to use a custom favicon instead of the included one, you may provide a full URL to an image of your choice.

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 for more detailed information on how to provide your own files.

Theme

You can configure a fixed them (and disable the theme switcher) by passing the theme option, like so:

theme: dark # or light

Color Palette

You can configured a fixed color palette (and disable the palette switcher) by passing the color option, like so:

color: slate

Supported colors are: slate, gray, zinc, neutral, stone, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, red, white

Layout

You can configure service and bookmarks sections to be either "column" or "row" based layouts, like so:

Assuming you have a group named Media in your services.yaml or bookmarks.yaml file,

layout:
  Media:
    style: row
    columns: 4

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.

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

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

Services

Services are defined as array entries on groups,

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

Descriptions

Services may have descriptions,

- Group A:
    - Service A:
        href: http://localhost/
        description: This is my service

- Group B:
    - Service B:
        href: http://localhost/
        description: This is another service
Service Descriptions

Icons

Services may have an icon attached to them, you can use icons from Dashboard Icons automatically, by passing the name of the icon, with, or without .png or with .svg to use the svg version.

You can also specify prefixed icons from Material Design Icons with mdi-XX or Simple Icons with si-XX.

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

To use a remote icon, use the absolute URL (e.g. https://...).

To use a local icon, first create a Docker mount to /app/public/icons and then reference your icon as /icons/myicon.png. You will need to restart the container when adding new icons.

Warning

Material Design Icons for brands were deprecated and may be removed in the future. Using Simple Icons for brand icons will prevent any issues if / when the Material Design Icons are removed.

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

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.

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

You can also apply different styles to the ping indicator by using the statusStyle property, see settings.

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.

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

Docker Integration

Services may be connected to a Docker container, either running on the local machine, or a remote machine.

- Group A:
    - Service A:
        href: http://localhost/
        description: This is my service
        server: my-server
        container: my-container

- Group B:
    - Service B:
        href: http://localhost/
        description: This is another service
        server: other-server
        container: other-container
Service Containers

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 for more information

Docker Stats Expanded

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

Here is an example of a Radarr & Sonarr service, with their respective integrations.

- Group A:
    - Sonarr:
        icon: sonarr.png
        href: http://sonarr.host/
        description: Series management
        widget:
          type: sonarr
          url: http://sonarr.host
          key: apikeyapikeyapikeyapikeyapikey

- Group B:
    - Radarr:
        icon: radarr.png
        href: http://radarr.host/
        description: Movie management
        widget:
          type: radarr
          url: http://radarr.host
          key: apikeyapikeyapikeyapikeyapikey
Service Integrations

Service Widgets

Unless otherwise noted, URLs should not end with a / or other API path. Each widget will handle the path on its own.

Each service can have one widget attached to it (often matching the service type, but 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 for more details.

Using Emby as an example, this is how you would attach the Emby service widget.

- Emby:
    icon: emby.png
    href: http://emby.host.or.ip/
    description: Movies & TV Shows
    widget:
      type: emby
      url: http://emby.host.or.ip
      key: apikeyapikeyapikeyapikeyapikey

Field Visibility

Each widget can optionally provide a list of which fields should be visible via the fields widget property. If no fields are specified, then all fields will be displayed. The fields property must be a valid YAML array of strings. As an example, here is the entry for Sonarr showing only a couple of fields.

In all cases a widget will work and display all fields without specifying the fields property.

- Sonarr:
    icon: sonarr.png
    href: http://sonarr.host.or.ip
    widget:
      type: sonarr
      fields: ["wanted", "queued"]
      url: http://sonarr.host.or.ip
      key: apikeyapikeyapikeyapikeyapikey