Homey is a simple home server dashboard packed with functionality. The layout is loosely inspired by Homer.
- 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
- 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!
homey-data.zipfrom 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
- Configure UI options in
config.yml.example. Rename to
- (Optional) Edit homey’s port (defualt 9080) in
- (Optional) Add service icons to the
- (Optional) Run monitorSystem.py to enable host machine stats.
- Launch with:
docker-compose up -d
Folder structure visualization:
homey-data │ .env │ config.yml │ docker-compose.yml └───icons │ homey.png │ portainer.png │ ... └───────────────
- 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
.envvalues blank to disable
- Refer to Docker Backends to configure Docker/Portainer API access
config.ymldefaults 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 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
Docker for Windows
The Docker socket and its permissions differ slightly on Windows.
docker-compose.yml, add an extra slash to the host (first) Docker socket path:
- 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.
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.
- 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:
python3 -m pip install -r homey-api/requirements.txt cd homey && npm i
- Configure external integrations in
.env.example. Leave fields blank to disable. Rename to
- Configure UI options if desired in
homey-api/config/config.yml.exampleand rename to
- (Optional) Copy icons into
- (Optional) Download and run
monitorSystem.pyto enable host machine stats. See System Monitor Module.
- Build frontend:
cd homey npm run prod_compile:sass npm run build
- Run backend:
cd homey-api gunicorn -b 0.0.0.0:9101 --threads 4 --worker-class gthread --log-file - app:app
Note: If pip didn’t automatically add gunicorn to $PATH, try:
- Serve the
/distfolder however you like. Quick ‘n’ dirty:
sudo nginx -c '/path/to/downloaded/nginx.conf'
- Sample NGINX configuration can be found in the client folder
Folder structure must remain as follows:
homey │ .env ├───homey │ └───dist ├───homey-api └───config │ config.yml └────────────
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.pyfrom the Releases page or above
Place anywhere (does not have to be in config directory – can be)
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.
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:
usage: monitorSystem.py [-h] [--interval N] [--cpu_window N] path disks [disks ...] Writes system usage information to JSON file on a timer. Use pythonw to run in background. positional arguments: path Output directory i.e. /home/bob/homey-data disks Space-separated list of mount points to monitor. Examples: Linux: / /mnt/backups /mnt/media/work-ssd Windows: C:\ E:\ Z:\ optional arguments: -h, --help show this help message and exit --interval N Query system & update file every N seconds (default: 30) --cpu_window N Average CPU usage over N seconds (default: 6) Quickstart: pythonw monitorSystem.py /path/to/homey-config-folder /
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
- User ID:
- Docker group ID:
getent group docker | cut -d: -f3
- Docker socket path:
/var/run/docker.sock(unless you’ve changed it)
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 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
Note: Once switched on, minimal mode can only be disabled by editing
Homey looks for service icons in
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
Frontend – config.yml
These options can all be modified through the GUI settings menu.
|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:
|service.name||String||Service display name|
|service.icon||String||Service icon filename without path i.e.
|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.
|TZ||String||Accepts a standard unix tz value i.e.
|HOMEY_API_WEATHER_LAT||String||Float with up to four decimal places i.e.
|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
|HOMEY_API_DOCKER_GROUP_ID||Integer||The group ID of the
|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.
|HOMEY_API_FLOOD_URL||String||Flood URL including protocol & port|
- ruTorrent support
- More fine-grained control over torrents
- In-page notifications for flood downloads
- Color configuration
- Additional cards
Other Things Called “Homey”
This project is in need of different title – open to suggestions!
- Modified Moby Dock 3D Model by Maurice Svay (CC BY 4.0)