HomePanel/addon/DOCS.md

Home Panel Documentation

Overview

Home Panel is a customizable dashboard for Home Assistant. It can run as:

• Home Assistant Add-on: Seamless integration with HA authentication
• Standalone Docker: Run independently and connect to Home Assistant

Standalone Docker

Quick Start

# Build the image
docker build -t homepanel .

# Run the container
docker run -d \
  --name homepanel \
  -p 8099:8099 \
  -v homepanel-data:/data \
  homepanel

Access the dashboard at http://localhost:8099

Docker Compose

version: '3.8'
services:
  homepanel:
    build: .
    ports:
      - "8099:8099"
    volumes:
      - homepanel-data:/data
    environment:
      - NODE_ENV=production
      - PORT=8099
    restart: unless-stopped

volumes:
  homepanel-data:

Environment Variables

Variable	Description	Default
PORT	Server port	8099
NODE_ENV	Node environment	production
HOMEPANEL_DATA_DIR	Data storage path	/data
LOG_LEVEL	Logging verbosity	info

---

Home Assistant Add-on

Add-on Options

Option	Description	Default
log_level	Logging verbosity level	info

Available log levels:

• trace - Most verbose, includes all debug information
• debug - Debug information for troubleshooting
• info - Standard informational messages (recommended)
• warn - Warning messages only
• error - Error messages only
• fatal - Fatal errors only
• off - Disable logging

Example Configuration

log_level: info

Usage

Accessing the Dashboard

1. After starting the add-on, click "Open Web UI" in the add-on info panel
2. You will be automatically authenticated via Home Assistant's ingress system
3. No separate password is required when accessing through Home Assistant

Standalone Access

If you need to access Home Panel outside of Home Assistant:

1. Enable the port mapping in the add-on configuration (port 3001)
2. Access the dashboard at http://your-ha-ip:3001
3. You will need to set up a password for standalone access

Features

Device Panels

Create custom panels for your devices with:

• Entity state displays
• Interactive controls (switches, sliders, etc.)
• Custom layouts and groupings

Weather Integration

Home Panel includes OpenMeteo weather integration:

1. Go to Settings
2. Enable OpenMeteo Weather
3. Set your latitude and longitude (or use "Get Location")
4. Save settings

Real-time Updates

All entity states update in real-time via WebSocket connections. Changes made in Home Assistant are immediately reflected in the dashboard.

Troubleshooting

Dashboard not loading

1. Check the add-on logs for errors
2. Ensure the add-on is running
3. Try restarting the add-on

Entities not updating

1. Verify the Home Assistant connection status in the dashboard
2. Check that the entities exist in Home Assistant
3. Review the add-on logs for connection errors

Authentication issues

When accessing via ingress (through Home Assistant UI):

• Authentication is automatic
• No password is required

When accessing standalone:

• Set a password in Settings
• Use the password to log in

Data Storage

The add-on stores its data in /config/homepanel/ which maps to the add-on's persistent storage. This includes:

• Settings configuration
• Device and panel configurations
• Custom entity configurations

Security

• Ingress authentication trusts Home Assistant's authentication
• Only requests from the Home Assistant ingress gateway (172.30.32.2) are auto-authenticated
• Standalone access requires password authentication
• Sensitive tokens are stored securely

Support

For issues, feature requests, or contributions:

• GitHub: https://github.com/tombutcher/HomePanel