evilstudio/homelab-assistant-tool

CLI Tool which can help with manage your homelab devices.

v2.4.3 2026-04-19 21:37 UTC

Requires

• php: ^8.3
• ext-ctype: *
• ext-iconv: *
• ext-json: *
• ext-mbstring: *
• ext-openssl: *
• ext-pdo: *
• ext-pdo_sqlite: *
• diegonz/php-wake-on-lan: ^2.1
• doctrine/doctrine-bundle: ^2.13
• doctrine/doctrine-migrations-bundle: ^3.4
• doctrine/orm: ^3.6
• dragonmantank/cron-expression: ^3.4
• geerlingguy/ping: ^1.2
• phpseclib/phpseclib: ^3.0
• symfony/dotenv: ^7.4
• symfony/flex: ^2
• symfony/framework-bundle: ^7.4
• symfony/monolog-bundle: ^3.10
• symfony/process: ^7.4
• symfony/runtime: ^7.4
• symfony/security-bundle: ^7.4
• symfony/twig-bundle: ^7.4
• symfony/yaml: ^7.4

Requires (Dev)

• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^4.0

Conflicts

• symfony/symfony: *

MIT

• Dariusz Matoga

• tool
• helper
• assistant
• homelab

README

Introduction

Homelab Assistant Tool is an application for homelab operations and automation. It combines a CLI interface with a Web UI for managing devices, UPS units, schedules, and operational logs.

For technical details, see Tech Stack.

✨ Key Features

• 🔌 Device operations

  • Start, stop, check status, and SSH operations for managed devices (via CLI)

• 🔋 UPS-aware behavior

  • UPS monitoring support and battery-aware automation logic

• ⏰ Scheduling

  • Cron-based automation with schedule-to-device assignment

• 🧾 Action logs

  • Unified action history for CLI, CRON, and WEB operations
  • Log filtering and cleanup tools

• 🌐 Web UI

  • Management views for devices, UPS, schedules, and logs
  • Manual operational actions from the browser

• 🔐 Authentication

  • simple mode (local username/password)
  • oidc mode (OIDC provider login)

📁 Project Structure

.
├── bin/             # CLI entrypoints and helper scripts
├── config/          # Symfony and app configuration
├── docs/            # Main technical documentation
├── migrations/      # Doctrine migrations
├── public/          # Web entrypoint and built assets
├── src/             # Application source code
│   ├── Command/         # CLI commands (setup, CRUD, runtime, users)
│   ├── Contract/        # Runtime contracts and enums
│   ├── Controller/      # Web controllers
│   ├── Entity/          # Doctrine entities
│   ├── EventSubscriber/ # Request/auth/log subscribers
│   ├── Factory/         # Runtime factories/adapters
│   ├── Helper/          # Configuration and helpers
│   ├── Repository/      # Doctrine repositories
│   ├── Runtime/         # Runtime models
│   └── Service/         # Application, runtime, auth, infrastructure services
├── templates/       # Twig templates (dashboard, devices, ups, schedules, logs, auth)
├── tests/           # Unit, integration, and functional test suites
└── var/             # Runtime data, cache, logs, SQLite files

🚀 Quick Start

You can run HAT in two ways.

Option 1: Docker only (without cloning the full repository)

1. Download docker-compose.yml, .env.example, and config/parameters.yaml

mkdir -p config var/data
curl -L -o docker-compose.yml https://raw.githubusercontent.com/evilstudio/homelab-assistant-tool/main/docker-compose.yml
curl -L -o .env https://raw.githubusercontent.com/evilstudio/homelab-assistant-tool/main/.env.example
curl -L -o config/parameters.yaml https://raw.githubusercontent.com/evilstudio/homelab-assistant-tool/main/config/parameters.yaml

2. Update .env and config/parameters.yaml

Set values for your environment (.env for app/auth settings and OIDC values when using HAT_AUTH_MODE=oidc, config/parameters.yaml for runtime settings).

3. Pull GHCR image

docker compose pull

4. Run initial setup commands

docker compose run --rm hat-app php bin/console hat:setup:configure
docker compose run --rm hat-app php bin/console hat:setup:db --init
docker compose run --rm hat-app php bin/console hat:user:create

hat:user:create is required only for simple auth mode.

5. Start container

docker compose up -d

6. Open application

Open: http://localhost:8080

Option 2: Clone full project (development/local workflow)

1. Clone repository

git clone https://github.com/evilstudio/homelab-assistant-tool.git
cd homelab-assistant-tool
composer install
cp .env.example .env

2. Update .env

Set values for your environment (application/auth settings, and OIDC values when using HAT_AUTH_MODE=oidc).

3. Run setup commands locally

php bin/console hat:setup:configure
php bin/console hat:setup:db --init
php bin/console hat:user:create # Required only for `simple` auth mode

4. Start an application with an GHCR image

docker compose pull
docker compose up -d

5. Or run development compose with local build and Xdebug

docker compose -f docker-compose.dev.yml up -d --build

For local non-docker CLI workflow (optional):

php bin/console list

💻 Commands Overview

Here is a list of commands available in HAT.

Command	Description
hat:setup:configure	Configure app technical settings.
hat:setup:db	Initialize/migrate SQLite database.
hat:setup:init	Run full setup flow.
hat:device:create/update/remove/list	Manage devices.
hat:ups:create/update/remove/list	Manage UPS entries.
hat:schedule:create/update/remove/list	Manage schedules.
hat:device:check-status	Check runtime status for a device.
hat:device:ssh	Open SSH session to a device.
hat:device:start	Start a device.
hat:device:stop	Stop a device.
hat:cron:execute	Execute scheduled tasks and maintenance.
hat:logs:list	List action logs stored in DB.
hat:logs:cleanup	Remove old/all action logs from DB.
hat:user:create	Create local user for simple auth mode.
hat:user:remove	Remove local user in simple auth mode.
hat:user:reset-password	Reset local user password (simple mode).

🧭 Notes

• Business data is stored in SQLite.
• Integration/functional tests use separate SQLite DB (var/data/hat_test.sqlite).
• Runtime settings are configured in config/parameters.yaml.
• Web logs are written to var/log/web.log.

🧪 Testing & Quality

Quick Start:

# Run all tests (Xdebug off)
bin/phpunit

# Run with coverage report
bin/phpunit-coverage

📚 Documentation:

• 📖 Test Implementation Summary - Overview and current scope
• 🚀 CI/CD Guide - GitLab pipeline setup