homey

Homey is a simple home server dashboard packed with functionality. The layout is loosely inspired by Homer.

Demo Video

Features

Local Docker container management
Remote Docker container management via Portainer
Torrent transfer speed & download notifications via Flood

supported clients: qBittorent, rTorrent, Transmission, Deluge

Hourly & daily weather forecasts via Open Meteo
Monitor up/down status of services
Monitor server’s CPU usage, RAM usage, disk usage, uptime
Tablet & mobile layouts
Easter eggs 🥚 👀

Installation & Configuration

Supported platforms:

Docker
Docker Desktop for Windows
GNU/Linux

Untested platforms:

Windows (no Docker)
Docker Desktop for Mac

In theory, homey can run with minimal modification anywhere node & python are installed.

In development – bug reports welcome from all platforms!

Docker

Download homey-data.zip from the Releases page.
Unzip to a permanent location. This is where homey’s config files and icons will be stored.
Configure integrations in dotenv.example. Rename to .env.
Configure UI options in config.yml.example. Rename to config.yml.
(Optional) Edit homey’s port (defualt 9080) in docker-compose.yml
(Optional) Add service icons to the icons subdirectory.
(Optional) Run monitorSystem.py to enable host machine stats.
Launch with: docker-compose up -d

Folder structure visualization:

Notes:

See Configuration Options for a description of each option
If homey fails to launch, ensure .env (not dotenv) is located in the same directory as docker-compose.yml
Leave .env values blank to disable
Refer to Docker Backends to configure Docker/Portainer API access
config.yml defaults work out of the box

These options can be changed while homey is running

Icons can also be added while homey is running, via the options menu or icons folder

Icons are not required for each service

Config dir does not have to remain named homey-data
When running inside Docker, 0.0.0.0/localhost/127.0.0.1 resolve to the container’s IP address – not the host’s. To add services running on the host, use the machine’s explicit local IP (i.e. 192.168.1.XX) instead.
Refer to System Monitor Module for more information on monitorSystem.py

Docker for Windows

The Docker socket and its permissions differ slightly on Windows.

In docker-compose.yml, add an extra slash to the host (first) Docker socket path:

Replace “${HOMEY_API_DOCKER_USER_ID}:${HOMEY_API_DOCKER_GROUP_ID}” with root:

Save & exit
(Optional) Remove the unused USER_ID & GROUP_ID lines from your .env file
Follow Docker setup instructions.

Volume Mapping Note: The tilde character (~) maps to C:Users<you> on Windows.

GNU/Linux

Not recommended – the Docker images were created to orchestrate serving the frontend/backend, proxy rewrite rules, sharing resources, keeping track of gunicorn, etc. so you don’t have to do so manually.

Prerequisites:

Python 3
Node.js 16.14+
npm 8.3.1+
An http server of your choosing with proxy support

Sample NGINX configuration can be found in the client folder

Clone the repository: git clone https://github.com/vlfldr/homey && cd homey
Install dependencies:

Configure external integrations in .env.example. Leave fields blank to disable. Rename to .env.
Configure UI options if desired in homey-api/config/config.yml.example and rename to config.yml.
(Optional) Copy icons into homey/public/data/icons
(Optional) Download and run monitorSystem.py to enable host machine stats. See System Monitor Module.
Build frontend:

Run backend:

Note: If pip didn’t automatically add gunicorn to $PATH, try:

Serve the /dist folder however you like. Quick ‘n’ dirty:

Sample NGINX configuration can be found in the client folder

Folder structure must remain as follows:

Icons are uploaded to & managed through /dist/data/icons after building.

Note: If you just want to check out the project but don’t want to bother with Docker or NGINX, follow steps 1-6 and then run ./run-dev.sh in the project root. This is not only insecure, it’s over 10x heavier than it needs to be with all the development dependencies bundled in! Do not run homey as a dashboard this way.

System Monitor Module

Displays CPU/RAM/disk usage and uptime. By design, Docker containers do not have access to detailed host information. This can be circumvented by running a script on the host: monitorSystem.py

Download monitorSystem.py from the Releases page or above

Place anywhere (does not have to be in config directory – can be)

Install dependencies: pip install psutil

Run in background: pythonw monitorSystem.py /path/to/homey-config-dir /

This will write stats to file every 30 seconds and monitor disk usage on the OS drive.

Launch homey

To monitor aditional drives, add them to the launch command: pythonw monitorSystem.py /path/to/homey/config-dir / /mnt/backups /mnt/media/work-ssd

Change file write frequency: –interval 30

Reference:

Docker Backends

Portainer – Communicates with a running Portainer instance. Provides SSL password authentication. Its API should be accessible with no additional configuration at the same port as the web UI (default 9443).

Note: If using a self-signed cert, ignore self-signed warnings

Docker API – Communicates with the parent Docker Engine process if running in a container. Talks to the local Docker Engine if running on bare metal. To find the appropriate config values for .env:

User ID: id -u
Docker group ID: getent group docker | cut -d: -f3
Docker socket path: /var/run/docker.sock (unless you’ve changed it)

Flood

Flood is a web-based frontend for multiple torrent clients. Once it’s running and talking to your client of choice, the API should be accessible via the same port as the web UI. No additional configuration is required.

Note: Unless you’ve deployed Flood with an SSL cert or behind a reverse proxy, credentials will be transmitted in plaintext upon authentication. This should not pose a security risk as Flood only exposes its interfaces on 127.0.0.1 by default. However do be aware that someone snooping through local network traffic could theoretically obtain your Flood username & password.

Minimal Mode

Minimal mode turns homey into a more traditional dashboard with links to services and low overhead. Everything is disabled except service links and bookmarks. If you’d like to run homey in minimal mode and are not running in Docker, work with the local config file: /public/config/config.yml. If you’re running in Docker, edit the config file in homey’s Docker volume as usual.

This option can be toggled using the settings menu or the minimal_mode flag.

Note: Once switched on, minimal mode can only be disabled by editing config.yml.

Icons

Homey looks for service icons in <docker_volume>/icons and homey/public/data/icons. Icons can also be uploaded via GUI in the settings menu. Currently only PNG is supported.

Docker containers will use icons which share their exact name. For example: to set portainer-agent‘s icon, upload a new icon named portainer-agent.png.

You can find a collection of PNG self-hosted service icons at NX211’s Homer Icons (512×512) or Homer Icons Compressed (128×128).

Configuration Options

Frontend – config.yml

These options can all be modified through the GUI settings menu.

Option
Type
Purpose

title
String
Change the title of your dashboard

minimal_mode
Boolean
Disables 3D eyecandy and most functionality. See Minimal Mode for more info.

show_house
Boolean
Disables 3D house in header

compact_services
Boolean
Reduces padding around services

enable_service_status
Boolean
Toggles service up/down indicators

enable_notifications
Boolean
Toggles in-page notifications

audio_notifications
Boolean
Toggles in-page notification audio

bookmarks_in_header
Boolean
Fills empty space in the header with bookmarks

docker_api_backend
String
Docker display/control backend. Valid options: docker, portainer

service.name
String
Service display name

service.subtitle
String
Service description

service.url
String
Service URL

service.icon
String
Service icon filename without path i.e. portainer.png

bookmark.name
String
Bookmark display name

bookmark.url
String
Bookmark target URL

bookmark.hover
String
Optional hovertext for bookmarks

card.enabled
Boolean
Toggles visibility of individual cards in bottom right section

Backend – .env

These settings cannot be changed after launching homey. All floats and strings must be wrapped in double quotes.

Option
Type
Purpose

TZ
String
Accepts a standard unix tz value i.e. “America/Chicago”. Ensures container’s clock matches local clock. List of all valid tz strings

HOMEY_API_WEATHER_LAT
String
Float with up to four decimal places i.e. “23.4809”. Sent to Open Meteo weather API. If location seems incorrect, double check +/- signs.

HOMEY_API_WEATHER_LONG
String
Float with up to four decimal places. Sent to Open Meteo weather API.

HOMEY_API_DOCKER_USER_ID
Integer
The user ID of an appropriately priveleged member of the docker group. See Docker Backends for more info.

HOMEY_API_DOCKER_GROUP_ID
Integer
The group ID of the docker group. See Docker Backends for more info.

HOMEY_API_DOCKER_SOCKET
String
Custom socket paths are not supported yet – do not modify this value. See Docker Backends for more info.

HOMEY_API_PORTAINER_URL
String
Portainer URL including protocol & port i.e. “https://192.168.1.2:9443”

HOMEY_API_PORTAINER_USER
String
Portainer username

HOMEY_API_PORTAINER_PASSWORD
String
Portainer password

HOMEY_API_FLOOD_URL
String
Flood URL including protocol & port

HOMEY_API_FLOOD_USER
String
Flood username

HOMEY_API_FLOOD_PASSWORD
String
Flood password

Planned Features

ruTorrent support
More fine-grained control over torrents
In-page notifications for flood downloads
Color configuration
Additional cards

Other Things Called “Homey”

A few other (very cool) projects have already coined the name “homey”, including a home automation solution, an apartment rental service, and a children’s budget management app.

This project is in need of different title – open to suggestions!

Built With

Vue.js
Three.js
Tween.js
Chart.js
SASS
Flask
Modified Moby Dock 3D Model by Maurice Svay (CC BY 4.0)
❤️

GitHub

View Github