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.

🧭 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