DOCSEARCHbyAlgolia
Submit Docs

Homer Dashboard

repository·main·Indexed 11 days ago

https://github.com/bastienwirtz/homer

A lightweight, fast, and simple static HTML/JS dashboard designed to organize and access services via a single YAML configuration file. Version 26.04.2 supports Docker deployment, PWA icons, custom themes via Bulma CSS, and 'Smart cards' for real-time data fetching from external APIs.

Tokens
16.9K
Snippets
82
Records
94
Agent score
95%

What's inside Homer

  1. How Smart cards work in Homer

    main

    Smart cards are specialized service integrations that display real-time data and extra features beyond a standard service link. To enable a Smart card, you must add a type key to the service item in your config.yml file.

    Security Warning

    Your config.yml is exposed at /assets/config.yml via HTTP. Do not include sensitive API keys directly in the file unless your Homer instance is protected by authentication or you use a proxy like CORSair to inject credentials via server-side environment variables.

    CORS Requirements

    Smart cards that fetch data from external services are subject to CORS restrictions. To make them work, you must ensure one of the following:

    1. All services are hosted on the same domain as Homer.
    2. The external services are configured to accept cross-site requests (CORS headers).
    3. You use a proxy to inject the necessary CORS headers.

  2. Optimize YAML configuration with Anchors

    main

    Since Homer uses YAML, you can use YAML anchors (&) and aliases (*) to avoid repeating tag definitions. Define your tag styles once in a tags section, then reference them in your items using the <<: *{NAME} syntax. This makes updating styles across many services much easier.

    # Define anchors in the tags section
tags: 
  Favourite: &Favourite
    - tag: "Favourite"
      tagstyle: "is-medium is-primary"
  Apps: &Apps
    - tag: "App"
      tagstyle: "is-medium is-info"

# Reference them in items
- name: "VS Code"
  logo: "/assets/vscode.png"
  <<: *Apps
  url: "https://vscode.example.com/"
  target: "_blank"

  3. How custom services work

    main

    Custom services are small Vue.js components located in src/components/services/ that add specific features to dashboard items.

    To maintain performance and design consistency, it is recommended to extend the Generic service rather than building from scratch. The Generic service provides a standard card layout and offers three optional named slots for customization:

    1. #icon: The left area containing the icon.
    2. #content: The main area containing the title, subtitle, and other core information.
    3. #indicator: The top right area (empty by default).

    If a slot is omitted, the Generic component will display the default information for that area. Every service must implement an item prop and bind it to the Generic component.

    <template>
  <Generic :item="item">
    <template #icon>
      <!-- left area containing the icon -->
    </template>
    <template #content>
      <!-- main area containing the title, subtitle, ... -->
    </template>
    <template #indicator>
      <!-- top right area, empty by default -->
    </template>
  </Generic>
</template>

<script>
import Generic from "./Generic.vue";

export default {
  name: "MyNewService",
  props: {
    item: Object,
  },
  components: {
    Generic,
  }
};
</script>

  4. Customize Homer themes and colors

    main

    Homer supports different color themes and deep visual customization via the colors key.

    Theme Selection

    • defaults.colorTheme: Set to auto, light, or dark.
    • theme: Select a theme name (e.g., default). Custom themes can be placed in src/assets/themes.
    • stylesheet: An array of paths to custom CSS files (e.g., - "assets/custom.css").

    Color Overrides

    You can provide specific hex codes for both light and dark modes. Common keys include highlight-primary, background, card-background, text, link, and background-image.

    Bulma Styling

    Homer uses Bulma CSS. The tagstyle option for services and tags accepts any Bulma modifier. Common color modifiers include:

    • is-info (blue)
    • is-success (green)
    • is-warning (yellow)
    • is-danger (red)
    defaults:
  layout: columns
  colorTheme: auto

theme: default

colors:
  light:
    highlight-primary: "#3367d6"
    background: "#f5f5f5"
  dark:
    highlight-primary: "#3367d6"
    background: "#131313"

  5. Install Homer Operator

    main

    To manage multiple Homer instances in a Kubernetes cluster using Custom Resource Definitions (CRDs), use the homer-operator provided by rajsinghtech.

    # Download the operator manifest
wget https://raw.githubusercontent.com/rajsinghtech/homer-operator/main/deploy/operator.yaml

# Apply the operator file
kubectl apply -f operator.yaml

  8. Install Homer Controller with CRDs

    main

    To deploy Homer using Custom Resource Definitions (CRDs) for dynamic declaration of Homer Services, use the homer-k8s chart provided by bananaops. This approach allows you to manage Homer services via Kubernetes-native custom resources.

    # Add and update the repository
helm repo add bananaops https://bananaops.github.io/homer-k8s/
helm repo update bananaops

# Install with all defaults
helm install homer bananaops/homer-k8s

# Install with customisations
wget https://raw.githubusercontent.com/bananaops/homer-k8s/main/helm/homer-k8s/values.yaml
# Edit values.yaml as needed
helm install homer bananaops/homer-k8s -f values.yaml

  9. Install Homer using the release tarball

    main

    To use the prebuilt version without Docker:

    1. Download the latest homer.zip from the GitHub releases page.
    2. Extract the archive.
    3. Rename assets/config.yml.dist to assets/config.yml.
    4. Serve the directory using a web server (e.g., http-server, python -m http.server, or Nginx).
    wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
unzip homer.zip -d homer
cd homer
cp assets/config.yml.dist assets/config.yml
# Serve with a web server
# Example: pnpx http-server
    wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
unzip homer.zip -d homer
cd homer
cp assets/config.yml.dist assets/config.yml
# Example using pnpx http-server

  10. How to add a new service sample to the mock server

    main

    To mock a new service, you must save a sample API output into a static file within the dummy-data directory. The directory structure and filename must mirror the service's API path so that the mock server can serve them seamlessly when the service endpoint is requested.

    Steps to add a sample:

    1. Create a directory for your service inside dummy-data.
    2. Create any necessary sub-folders to match the API path.
    3. Save the API response in a file named exactly after the service endpoint.

    Note: If the service implementation expects a specific base URL (e.g., /admin), you may need to omit that part of the path in your local directory structure if the url or endpoint property in your Homer configuration already includes it.

    # Example: Mocking a PiHole API response
mkdir pihole
curl http://my-pihole.me/admin/api.php -o pihole/api.php

  11. Add a new custom theme

    main

    Themes are implemented using SCSS. To add a new theme:

    1. Create a new SCSS file in the src/assets/themes/ directory.
    2. Scope all your styles using the selector body #app.theme-<name> to ensure they only apply when that specific theme is active.
    3. Import your new theme file into the main style file (src/assets/app.scss).
    // src/assets/themes/my-awesome-theme.scss
body #app.theme-my-awesome-theme {
  /* your styles here */
}

// src/assets/app.scss
@import "./themes/sui.scss";
/* ... */
@import "./themes/my-awesome-theme.scss";