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

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

Folder structure visualization:

homey-data
│   .env
│   config.yml  
│   docker-compose.yml  
└───icons
    │   homey.png
    │   portainer.png
    │   ...
    └───────────────

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.

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

  - //var/run/docker.sock:${HOMEY_API_DOCKER_SOCKET}

2. Replace "${HOMEY_API_DOCKER_USER_ID}:${HOMEY_API_DOCKER_GROUP_ID}" with root:

  user: root

3. Save & exit
4. (Optional) Remove the unused USER_ID & GROUP_ID lines from your .env file
5. 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

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

python3 -m pip install -r homey-api/requirements.txt
cd homey && npm i

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

cd homey
npm run prod_compile:sass
npm run build

8. 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:

export PATH="$PATH:/user/<you>/.local/bin"

9. Serve the /dist folder 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.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:

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 /

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.

Backend – .env

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

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