DOCSEARCHbyAlgolia
Submit Docs

hass_ingress

repository·main·Indexed 42 days ago

https://github.com/lovelylain/hass_ingress

A project that provides a Hassio-like addon experience for Home Assistant users running in a standard Docker environment. It enables the integration of external containers—such as Node-RED, VSCode, and MQTT—directly into the Home Assistant UI via Ingress. Features include support for various work_modes (ingress, iframe, auth, hassio, custom), UI visibility controls, response body and header rewriting to fix absolute URLs, and the ability to pass user information to backend services starting from v1.3.0.

Tokens
5.1K
Snippets
20
Records
22
Agent score
55%

What's inside hass_ingress

  1. Configure ui_mode options

    main

    The ui_mode option controls the visibility of the Home Assistant header on the panel page:

    • replace: Redirects to the target URL. Useful for adding existing HA pages as sidebar panels.
    • normal: Hides the header on the ingress panel pages.
    • toolbar: Shows the header on the ingress panel pages.

  2. Configure work_mode options

    main

    The work_mode option determines how the panel interacts with the backend service:

    • ingress: Uses the Hass.io Ingress function. This is the default.
    • iframe: Uses a sidebar function similar to the Webpage dashboard.
    • auth: Works with Nginx auth_request. Useful for backend services that cannot be proxied by ingress. It expects specific request/response headers.
    • hassio: Supports Hass.io add-on ingress. Set the url to the add-on slug (e.g., url: a0d7b954_grafana).
    • custom: Required when using the tabs feature to enable multiple tabs without reloading.
    # Example of auth mode configuration
# In Nginx config:
# auth_request api: /api/ingress/_/auth
# Request headers: X-Ingress-Name, X-Original-URL, X-Hass-Origin
# Response headers: Set-Cookie (ingress_token), Location (login_url_path)

  3. Use static tokens for public links

    main

    The static_token option allows you to create public links that never expire. These links can be used to access the backend service without logging into Home Assistant. The URL format is /api/ingress/t-{static_token}/.

    ```yaml
ingress:
  ttyd:
    work_mode: ingress
    title: Terminal
    url:
    static_token: secret-token-value-for-ttyd

    Access via: /api/ingress/t-secret-token-value-for-ttyd/.

  5. Configure hass_ingress panels

    main

    To enable Ingress panels, add an ingress: block to your configuration.yaml file. Each entry under ingress defines a new panel. After modifying the configuration, you can reload it without restarting Home Assistant by going to the developer-tools page and clicking INGRESS under the reload section.

    ingress:
  link_automation:
    work_mode: iframe
    ui_mode: replace
    title: Automation
    icon: mdi:link
    url: /config/automation/dashboard
  frigate:
    ui_mode: toolbar
    title: Frigate
    icon: mdi:cctv
    url: http://172.30.32.2:5000

  6. Configure the Docker Network and DNS Proxy

    main

    To allow Home Assistant (running in network_mode: host) to communicate with addon containers in a custom bridge network, a DNS proxy is required. This setup uses an Nginx container to proxy DNS requests to the Docker internal resolver.

    1. Define the custom network in docker-compose.yml

    Use a specific subnet to ensure predictable IP addressing for the DNS proxy and Home Assistant's DNS settings.

    2. Configure the DNS Proxy container

    The dns service uses an Nginx image with a stream configuration to proxy UDP port 53 traffic to 127.0.0.11:53 (the Docker internal DNS).

    3. Configure Home Assistant DNS

    Set the dns option in the homeassistant service to point to the IP address of your dns container (e.g., 172.30.32.3).

    # docker-compose.yml network snippet
networks:
  default:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: hassio
    ipam:
      config:
        - subnet: 172.30.32.0/23
          ip_range: 172.30.33.0/24
          gateway: 172.30.32.1

# dns_proxy.conf snippet
stream {
  server {
    listen 53 udp;
    proxy_pass 127.0.0.11:53;
    proxy_timeout 10s;
  }
}

  7. Use rewrite rules to fix absolute URLs

    main

    If a backend service uses absolute paths that break when proxied through ingress, you can use the rewrite option to rewrite the response body or headers. This is common for services like OpenWrt.

    Use $http_x_ingress_path in your replacement string to dynamically inject the correct ingress path.

    Supported modes:

    • body: Rewrites the response body.
    • header: Rewrites response headers.

    Example for OpenWrt (fixing HTML, JS, and Login responses):

    openwrt:
  title: OpenWrt
  url: http://192.168.0.1/
  rewrite:
    - mode: body
      match: /(luci-static|cgi-bin)/
      replace: $http_x_ingress_path/\1/
    - mode: body
      match: \\/(luci-static|cgi-bin|ubus)\/\
      replace: $http_x_ingress_path\/\1\/\
    - mode: header
      name: "(Location|Set-Cookie)"
      match: /cgi-bin/
      replace: $http_x_ingress_path/cgi-bin/

  9. Setup Home Assistant and Addons in Docker without Hassio

    main

    This guide provides a method to run Home Assistant and equivalent 'addons' (containers) in a Docker environment without using Hassio Supervisor. It uses docker compose to manage containers and the hass_ingress project to provide an Ingress experience similar to the official Supervisor.

    Workflow for adding new addons:

    1. Add the service to your docker-compose.yml.
    2. Start the container using docker compose up -d.
    3. Add the ingress configuration to your Home Assistant configuration.yaml.
    4. Reload INGRESS in Home Assistant to see the new service in the sidebar.
    # Example setup sequence
mkdir -p /opt/hassio
cd /opt/hassio
# 1. Create docker-compose.yml and nginx/dns_proxy.conf
# 2. Start containers
docker compose up -d
# 3. Configure Home Assistant
# (Access http://local_ip:8123/ to configure HA)
# 4. Add ingress to homeassistant/configuration.yaml
docker compose restart homeassistant

  10. Configure Ingress for Addons in Home Assistant

    main

    To make an addon accessible via the Home Assistant sidebar, you must add an ingress entry to your homeassistant/configuration.yaml.

    Configuration Keys:

    • title: The display name in the sidebar.
    • icon: The Material Design Icon (e.g., mdi:sitemap).
    • url: The internal service address in the format service_name:port (e.g., nodered:1880).
    • require_admin: (Optional) Boolean to restrict access.
    • rewrite: (Optional) Used for complex apps (like Tandoor or OpenWrt) that require body or header rewriting to handle absolute URLs correctly.
    • headers: (Optional) Used to pass authentication or specific path information to the addon.
    ingress:
  nodered:
    require_admin: true
    title: Node-RED
    icon: mdi:sitemap
    url: nodered:1880

  11. Add OpenWrt with Auto-Login and URL Rewriting

    main

    To integrate OpenWrt, use the headers key for auto-login and the rewrite key to fix absolute URLs in the HTML and JS responses.

    Home Assistant Configuration:

    ingress:
  openwrt:
    title: OpenWrt
    icon: mdi:router-wireless
    url: 192.168.0.1
    headers:
      http-auth-user: !secret openwrt_user
      http-auth-pass: !secret openwrt_auth
    rewrite:
      - mode: body
        match: /(luci-static|cgi-bin)/
        replace: $http_x_ingress_path/\1/
      - mode: body
        match: \\/(luci-static|cgi-bin|ubus)\/\
        replace: $http_x_ingress_path\/\1\/
      - mode: header
        name: "(Location|Set-Cookie)"
        match: /cgi-bin/
        replace: $http_x_ingress_path/cgi-bin/
    # No docker-compose service provided for OpenWrt in source, 
# but it is configured via Home Assistant Ingress.

  12. Add Node-RED as an Addon

    main

    To add Node-RED, add the following service to your docker-compose.yml and configure the ingress in Home Assistant.

    Note: You may need to run sudo chown 1000:1000 -R ./node-red to ensure correct permissions for the data volume.

    Home Assistant Configuration:

    ingress:
  nodered:
    require_admin: true
    title: Node-RED
    icon: mdi:sitemap
    url: nodered:1880
    services:
  nodered:
    image: nodered/node-red
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./node-red:/data
      - ./share:/share