Home Lab Hub (RaidOwl/homelab-hub) to darmowa, samodzielnie hostowana (self-hosted) aplikacja webowa, która pozwala śledzić i wizualizować całą infrastrukturę domowego laboratorium serwerowego — sprzęt, maszyny wirtualne, aplikacje, storage, sieci i udziały sieciowe — w jednym, spójnym panelu. Projekt jest dostępny na GitHubie pod adresem github.com/RaidOwl/homelab-hub, opublikowany na licencji MIT, i cieszy się rosnącą popularnością wśród entuzjastów homelabu (ponad 500 gwiazdek na GitHubie).
W tym artykule znajdziesz szczegółowy opis funkcji, stosu technologicznego, instrukcję instalacji (zarówno w Dockerze, jak i bez niego), opis API oraz odpowiedzi na najczęstsze pytania dotyczące tego narzędzia.
Spis treści
- Czym jest Home Lab Hub?
- Kluczowe funkcje Home Lab Hub
- Stos technologiczny (Tech Stack)
- Wymagania systemowe
- Instalacja Home Lab Hub przez Dockera
- Aktualizacja do nowszej wersji
- Konfiguracja — zmienne środowiskowe
- Backup danych — eksport i import
- Struktura projektu
- Dokumentacja API
- Dla kogo jest Home Lab Hub?
- Najczęściej zadawane pytania (FAQ)
- Podsumowanie
1. Czym jest Home Lab Hub?
Home Lab Hub to narzędzie typu inventory management stworzone specjalnie z myślą o osobach prowadzących własne homelaby — czyli domowe środowiska serwerowe używane do nauki, testów, self-hostingu usług czy zabawy z infrastrukturą IT. Zamiast prowadzić arkusz Excela albo notatnik z listą sprzętu i usług, Home Lab Hub daje jeden webowy dashboard, w którym można:
- prowadzić pełną ewidencję (CRUD) sprzętu, maszyn wirtualnych, aplikacji/usług, zasobów storage, sieci i udziałów sieciowych,
- wizualizować zależności między elementami infrastruktury na interaktywnym grafie,
- prowadzić dokumentację techniczną w Markdown bezpośrednio w aplikacji,
- eksportować i importować całą bazę danych jednym kliknięciem.
Aplikacja jest w pełni self-hosted, co oznacza, że dane nigdy nie opuszczają Twojej sieci — wszystko trzyma się lokalnie w bazie SQLite.
2. Kluczowe funkcje Home Lab Hub
2.1. Zarządzanie inwentarzem (Inventory Management)
Pełne operacje CRUD (Create, Read, Update, Delete) dla wszystkich typów zasobów: sprzętu, maszyn wirtualnych, aplikacji i usług, storage’u, sieci oraz elementów „misc” (różnych, niesklasyfikowanych zasobów).
2.2 Zarządzanie udziałami sieciowymi (Shares Management)
Śledzenie udziałów sieciowych — NFS, SMB, iSCSI, FTP, SFTP oraz WebDAV — przypisanych do konkretnych urządzeń storage, z automatycznym uzupełnianiem szczegółów połączenia.
2.3 Eksport i import danych
Jednoklikowy eksport całej bazy danych do pliku JSON i równie prosty import — idealne rozwiązanie do tworzenia kopii zapasowych lub migracji między instancjami.
2.4 Wizualizacja sieci (Network Visualization)
Interaktywna mapa grafowa (oparta o bibliotekę Cytoscape.js) z układem depth-first, pokazująca relacje między elementami infrastruktury — świetny sposób, by zobaczyć „z lotu ptaka”, co jest z czym połączone.
2.5 Widok drzewa (Tree View)
Hierarchiczny widok infrastruktury z rozwijanymi węzłami, przydatny przy dużych, rozbudowanych homelabach.
2.6 Wbudowana dokumentacja
Hierarchiczna dokumentacja w Markdown z podglądem na żywo i automatycznym zapisem — można prowadzić notatki techniczne bez opuszczania aplikacji.
3. Stos technologiczny (Tech Stack)
| Warstwa | Technologia |
|---|---|
| Frontend | Svelte 4, Vite 5, Cytoscape.js, ByteMD, Pico CSS |
| Backend | Python 3.14, Flask 3, SQLAlchemy 2, Alembic |
| Baza danych | SQLite (domyślnie, konfigurowalna) |
| Wdrożenie | Docker, Docker Compose, Gunicorn |
Wybór Svelte na froncie zamiast popularniejszych React czy Vue sprawia, że aplikacja jest bardzo lekka i szybka — co ma znaczenie przy uruchamianiu na słabszym sprzęcie, jak Raspberry Pi.
4. Wymagania systemowe
- Node.js 24+ (do developmentu frontendu),
- Python 3.14+ (do developmentu backendu),
- Docker (opcjonalnie, do wdrożenia kontenerowego).
Obsługiwane platformy
- Linux (x86_64, ARM64) — w tym Raspberry Pi 4 i nowsze, Orange Pi itd.,
- macOS (Intel i Apple Silicon),
- Windows (natywnie lub przez WSL2).
Wsparcie dla ARM64 sprawia, że Home Lab Hub doskonale nadaje się do uruchomienia na energooszczędnym Raspberry Pi jako stały element homelabu.
5. Instalacja Home Lab Hub przez Dockera (najszybszy sposób)
Najprostszy sposób na uruchomienie aplikacji to Docker. Wystarczy jedna komenda:
docker run -d \
--name homelab-hub \
-p 8000:8000 \
-v ./data:/data \
--restart unless-stopped \
raidowl/homelab-hub:latest
Alternatywnie, korzystając z Docker Compose, wystarczy stworzyć plik docker-compose.yml:
services:
homelab-hub:
image: raidowl/homelab-hub:latest
container_name: homelab-hub
ports:
- "8000:8000"
volumes:
- ./data:/data
restart: unless-stopped
a następnie uruchomić:
docker compose up -d
Po uruchomieniu aplikacja dostępna jest pod adresem http://localhost:8000, a wszystkie dane są trwale zapisywane w katalogu ./data/.
6. Aktualizacja do nowszej wersji
Migracje bazy danych uruchamiają się automatycznie przy starcie kontenera. Aby zaktualizować aplikację:
# Pobierz najnowszy obraz
docker pull raidowl/homelab-hub:latest
# Zrestartuj kontener
docker compose down
docker compose up -d
Zalecaną dobrą praktyką jest zawsze wykonanie kopii zapasowej katalogu ./data/ przed aktualizacją:
cp -r ./data ./data-backup-$(date +%Y%m%d)
7. Konfiguracja — zmienne środowiskowe
| Zmienna | Wartość domyślna | Opis |
|---|---|---|
DATABASE_URL | sqlite:///data/homelab-hub.db | URI bazy danych SQLAlchemy |
FLASK_ENV | production | Środowisko Flask (production lub development) |
8. Backup danych — eksport i import
Home Lab Hub oferuje dwa sposoby wykonywania kopii zapasowych: przez interfejs graficzny oraz przez API.
Przez UI: wystarczy kliknąć przycisk „Export Data” w nagłówku aplikacji, aby pobrać plik homelab-export.json ze wszystkimi danymi. Import odbywa się analogicznie — przyciskiem „Import Data”.
Uwaga: import danych czyści całą istniejącą bazę przed przywróceniem z pliku. Zawsze warto zrobić eksport zapasowy przed importem.
Przez API/CLI:
# Eksport
curl -X GET http://localhost:5001/inventory/export -o export.json
# Import
curl -X POST http://localhost:5001/inventory/import \
-H "Content-Type: application/json" \
-d @export.json
Da się to również zrobić bezpośrednio w uruchomionym kontenerze Dockera, korzystając z docker exec i docker cp.
9. Struktura projektu
homelab-hub/
├── backend/
│ ├── app/
│ │ ├── models/ # Modele SQLAlchemy
│ │ └── routes/ # Blueprinty API Flask
│ ├── migrations/ # Migracje Alembic
│ ├── requirements.txt
│ └── wsgi.py
├── frontend/
│ ├── src/
│ │ ├── components/ # Komponenty Svelte
│ │ ├── pages/ # Komponenty widoków
│ │ └── lib/ # Klient API, stores
│ └── package.json
├── data/ # Baza SQLite (w .gitignore)
├── Dockerfile
└── docker-compose.yml
Taki podział jasno rozdziela logikę backendu (Python/Flask) od warstwy prezentacji (Svelte), co ułatwia rozwój i utrzymanie projektu przez społeczność.
10. Dokumentacja API
Wszystkie endpointy API są dostępne pod prefiksem /api/.
| Zasób | Endpointy |
|---|---|
| Health | GET /api/health |
| Hardware | GET/POST /api/hardware, GET/PUT/DELETE /api/hardware/:id |
| VMs | GET/POST /api/vms, GET/PUT/DELETE /api/vms/:id |
| Apps | GET/POST /api/apps, GET/PUT/DELETE /api/apps/:id |
| Storage | GET/POST /api/storage, GET/PUT/DELETE /api/storage/:id |
| Shares | GET/POST /api/shares, GET/PUT/DELETE /api/shares/:id |
| Networks | GET/POST /api/networks, GET/PUT/DELETE /api/networks/:id |
| Misc | GET/POST /api/misc, GET/PUT/DELETE /api/misc/:id |
| Documents | GET/POST /api/docs, GET/PUT/DELETE /api/docs/:id, PATCH /api/docs/:id/move |
| Inventory | GET /api/inventory, GET /api/inventory/search?q=, GET /api/inventory/export, POST /api/inventory/import |
| Map | GET /api/map/graph, GET/PUT /api/map/layout, POST/DELETE /api/map/edges |
Pełne REST API oznacza, że Home Lab Hub można łatwo zintegrować z własnymi skryptami automatyzacji, systemami monitoringu czy innymi narzędziami homelabu.
11. Dla kogo jest Home Lab Hub?
Narzędzie to sprawdzi się przede wszystkim dla:
- entuzjastów homelabu, którzy mają kilka serwerów, maszyn wirtualnych i usług self-hosted i chcą mieć nad tym porządek,
- administratorów małych sieci domowych/firmowych, potrzebujących prostego, wizualnego rejestru sprzętu i połączeń,
- osób uczących się DevOps/sysadmin, dla których wizualizacja zależności między VM-ami, storage’em a sieciami jest świetną pomocą dydaktyczną,
- każdego, kto woli mieć pełną kontrolę nad danymi (self-hosted, bez chmury, dane w SQLite na własnym dysku) zamiast korzystać z komercyjnych narzędzi CMDB.
12. Najczęściej zadawane pytania (FAQ)
Czy Home Lab Hub jest darmowy?
Tak. Projekt jest w pełni open source i udostępniony na licencji MIT, co pozwala na dowolne wykorzystanie, modyfikację i dystrybucję.
Czy dane są wysyłane do chmury?
Nie. Home Lab Hub to aplikacja w pełni self-hosted — wszystkie dane trafiają lokalnie do bazy SQLite w katalogu ./data/, którym w pełni zarządzasz sam.
Czy Home Lab Hub działa na Raspberry Pi?
Tak, aplikacja oficjalnie wspiera architekturę ARM64, w tym Raspberry Pi 4 i nowsze modele, dzięki czemu można uruchomić ją energooszczędnie na małym urządzeniu.
Jak zainstalować Home Lab Hub najszybciej?
Najszybszą metodą jest uruchomienie jednej komendy docker run z obrazu raidowl/homelab-hub:latest lub użycie Docker Compose — cały proces zajmuje mniej niż minutę.
Jaka baza danych jest używana?
Domyślnie SQLite, ale konfiguracja przez zmienną środowiskową DATABASE_URL (SQLAlchemy) pozwala teoretycznie podpiąć inne silniki bazodanowe wspierane przez SQLAlchemy.
Czy można eksportować i przenosić dane między instalacjami?
Tak — jednoklikowy eksport/import JSON pozwala łatwo migrować całą inwentaryzację między instancjami lub tworzyć regularne kopie zapasowe.
Jaki jest stos technologiczny projektu?
Frontend napisany jest w Svelte 4 z Vite 5, wizualizacja grafowa korzysta z Cytoscape.js, a backend oparty jest o Python 3.14, Flask 3 oraz SQLAlchemy 2 z migracjami Alembic.
13. Podsumowanie
Home Lab Hub to lekkie, w pełni open source’owe i self-hostowane narzędzie do inwentaryzacji oraz wizualizacji infrastruktury homelabowej. Łączy prosty, przejrzysty interfejs (Svelte + Pico CSS) z solidnym backendem (Flask + SQLAlchemy) i wygodnym wdrożeniem przez Docker. Dzięki funkcjom takim jak interaktywna mapa sieci, hierarchiczna dokumentacja Markdown, śledzenie relacji między zasobami oraz pełne REST API, projekt stanowi realną alternatywę dla ręcznego prowadzenia arkuszy kalkulacyjnych czy droższych, komercyjnych systemów CMDB.
Kod źródłowy, pełna dokumentacja oraz instrukcje instalacji dostępne są w oficjalnym repozytorium: github.com/RaidOwl/homelab-hub.
Ten artykuł powstał na podstawie oficjalnej dokumentacji projektu Home Lab Hub (RaidOwl/homelab-hub) dostępnej na GitHubie. Projekt jest rozwijany aktywnie i udostępniony na licencji MIT.