Dockhand – Kompletny Przewodnik: Instalacja, Konfiguracja i Użytkowanie (2025/2026)

Dockhand to nowoczesna, samodzielnie hostowana platforma do zarządzania Dockerem, która w ciągu kilku miesięcy od premiery pod koniec 2025 roku zrewolucjonizowała środowisko narzędzi kontenerowych. Jeśli szukasz odpowiedzi na pytania: czym jest Dockhand, jak zainstalować Dockhand i jak go używać w praktyce — ten artykuł jest kompletnym źródłem wiedzy.

 

 

---

Spis treści

1. Czym jest Dockhand?
2. Dockhand vs Portainer – dlaczego warto zmienić?
3. Wymagania systemowe
4. Instalacja Dockhand – krok po kroku
   • Instalacja przez docker run
   • Instalacja przez Docker Compose
5. Pierwsze uruchomienie i konfiguracja
6. Zarządzanie kontenerami
7. Compose Stacks – wizualny edytor
8. Integracja z Git i GitOps
9. Skanowanie podatności – Grype i Trivy
10. Automatyczne aktualizacje kontenerów
11. Monitorowanie i powiadomienia
12. Uwierzytelnianie – SSO, OIDC, MFA, LDAP
13. Szyfrowanie danych
14. Dockhand Enterprise vs Free
15. Najczęstsze pytania (FAQ)
16. Podsumowanie

---

1. Czym jest Dockhand?

Dockhand to nowoczesna aplikacja webowa do zarządzania Dockerem, stworzona przez Jarka Krochmalskiego (Finsys). Oferuje intuicyjny interfejs graficzny do obsługi kontenerów, stosów Docker Compose, obrazów, wolumenów i sieci – wszystko w jednym, lekkim kontenerze bez zależności chmurowych i bez telemetrii.

Kluczowe cechy Dockhand:

• Zarządzanie kontenerami w czasie rzeczywistym – start, stop, restart, inspekcja
• Wizualny edytor Docker Compose – tworzenie i edycja stosów bez pisania YAML ręcznie
• Integracja z Git / GitOps – auto-sync stosów z repozytoriów Git przez webhook
• Wsparcie wielu hostów – zarządzanie zdalnymi maszynami przez agenta Hawser
• Terminal webowy – interaktywny shell bezpośrednio w przeglądarce
• Przeglądarka plików – upload i download plików z/do kontenerów
• Skanowanie CVE – wbudowane skanowanie obrazów przez Grype i Trivy
• Bezpieczne auto-aktualizacje – Safe-pull: nowy obraz jest skanowany przed zastąpieniem działającego kontenera
• Uwierzytelnianie klasy enterprise – SSO/OIDC, MFA, LDAP/AD, RBAC (Enterprise)
• Zero telemetrii – żadnych połączeń do zewnętrznych serwerów, żadnych analityk
• Darmowy na zawsze do użytku osobistego i wewnętrznego biznesowego

Dockhand działa na bazie SvelteKit 2 / Svelte 5 z frontendem opartym na TailwindCSS i shadcn-svelte. Warstwa bazodanowa to domyślnie SQLite (opcjonalnie PostgreSQL dla HA). Nie wymaga Redis ani kolejek wiadomości – minimalna powierzchnia ataku, maksymalna prostota deploymentu.

Ciekawostka: Dockhand buduje własną warstwę OS od zera przy użyciu pakietów Wolfi przez apko. Każdy pakiet jest jawnie zadeklarowany w Dockerfile – pełna przejrzystość, zero „mystery meat”. Podczas gdy inne narzędzia dostarczają Alpine z dziesiątkami CVE, Dockhand obsesyjnie dba o bezpieczeństwo własnego obrazu.

---

2. Dockhand vs Portainer – dlaczego warto zmienić?

Przez lata Portainer był domyślnym wyborem do zarządzania Dockerem w homelabbach i małych firmach. Dockhand pojawił się pod koniec 2025 roku i szybko zdobył reputację jego naturalnego następcy – i w wielu aspektach go przewyższa.

Cecha	Dockhand	Portainer CE
Interfejs	Nowoczesny, szybki (Svelte 5)	Starszy, cięższy (Angular)
Telemetria	Zero	Tak
SSO/OIDC	Darmowy	Płatny (BE)
MFA	Darmowy	Płatny (BE)
LDAP/AD	Enterprise	Płatny (BE)
RBAC	Enterprise	Płatny (BE)
Skanowanie CVE	Wbudowane (Grype+Trivy)	Brak w CE
Safe-pull update	Tak	Nie
GitOps auto-sync	Tak	Ograniczony
Hawser (NAT traversal)	Tak	Nie
Powiadomienia (Apprise)	Wbudowane	Brak
SQLite/PostgreSQL	Tak	Nie (własna baza)
Licencja	BSL 1.1 / darmowy	EE/CE

Dockhand w jednym kontenerze zastępuje całe ekosystemy narzędzi: Portainer CE, Watchtower, Dozzle, Beszel, Dockge, Diun/WUD oraz PruneMate – eliminując konieczność zarządzania wieloma serwisami, portami i cyklami aktualizacji.

---

3. Wymagania systemowe

Dockhand działa na każdym systemie obsługującym Dockera:

• System operacyjny: Linux (x86_64, ARM64, ARMv7), macOS, Windows (przez Docker Desktop)
• Docker: wersja 20.10 lub nowsza
• Docker Compose: wersja 2.x (opcjonalnie, ale zalecane)
• RAM: minimum 256 MB (zalecane 512 MB+)
• Dysk: kilkanaście MB dla samego kontenera + przestrzeń na dane aplikacji
• Port: domyślnie 3000 (konfigurowalny)
• Dostęp do Docker socket: /var/run/docker.sock

Dockhand nie wymaga żadnych zewnętrznych zależności (brak Redis, brak RabbitMQ, brak zewnętrznych baz danych w trybie podstawowym).

---

4. Instalacja Dockhand – krok po kroku

4.1 Instalacja przez docker run {#docker-run}

Najprostsza metoda – jedno polecenie i Dockhand działa:

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

Po uruchomieniu otwórz przeglądarkę i przejdź pod adres http://localhost:3000.

Wariant z matchującymi ścieżkami (wymagany gdy używasz relatywnych ścieżek w stosach Compose):

mkdir -p /opt/dockhand

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/dockhand:/opt/dockhand \
  -e DATA_DIR=/opt/dockhand \
  fnsys/dockhand:latest

Rozwiązywanie problemu z uprawnieniami do Docker socket

Dockhand domyślnie działa jako użytkownik niebędący rootem. Jeśli widzisz błąd permission denied, masz kilka opcji:

Opcja A – dopasowanie GID grupy docker (zalecane):

# Znajdź GID grupy docker na hoście
stat -c '%g' /var/run/docker.sock
# np. 999

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  --group-add 999 \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

Opcja B – PUID/PGID (najbardziej zalecana):

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  -e PUID=$(id -u) \
  -e PGID=$(id -g) \
  --group-add 999 \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

Zmienna PUID/PGID uruchamia kontener jako root, naprawia uprawnienia wolumenów, po czym spada do wskazanego użytkownika – named volumes działają bez dodatkowej konfiguracji.

---

4.2 Instalacja przez Docker Compose

Plik docker-compose.yml dla podstawowej instalacji:

yaml

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

Uruchomienie:

docker compose up -d

---

5. Pierwsze uruchomienie i konfiguracja

Po uruchomieniu Dockhand otwórz przeglądarkę i przejdź pod http://localhost:3000 (lub odpowiedni adres IP i port).

Ważne: Przy pierwszym uruchomieniu uwierzytelnianie jest wyłączone. Każdy z dostępem do interfejsu ma pełne uprawnienia administratora. Skonfiguruj uwierzytelnianie jak najszybciej!

Konfiguracja uwierzytelniania:

1. Kliknij Settings w lewym pasku bocznym.
2. Wybierz zakładkę Authentication.
3. Przejdź do zakładki Users.
4. Kliknij Add user i wprowadź nazwę użytkownika oraz hasło.
5. Kliknij Create user.
6. Przełącz przycisk Authentication z OFF na ON.

Od tej chwili dostęp do Dockhand wymaga logowania.

Dodawanie lokalnego środowiska Docker:

Po zalogowaniu przejdź do Settings → Environments i dodaj lokalne środowisko przez socket (/var/run/docker.sock). Jeśli używasz socket proxy, podaj adres TCP proxy.

---

6. Zarządzanie kontenerami

Panel główny Dockhand prezentuje kafle (tiles) dla każdego skonfigurowanego środowiska Docker. Każdy kafel pokazuje w czasie rzeczywistym:

• liczbę działających / zatrzymanych kontenerów
• zużycie CPU i RAM
• status sieci i wolumenów

Operacje na kontenerach:

W widoku listy kontenerów możesz dla każdego kontenera:

• Uruchomić / zatrzymać / zrestartować jednym kliknięciem
• Sprawdzić logi – strumieniowanie w czasie rzeczywistym z filtrowaniem
• Otworzyć terminal – interaktywny shell bezpośrednio w przeglądarce
• Przeglądać pliki – browser plików z możliwością uploadu i downloadu
• Sprawdzić inspekcję – pełne informacje o konfiguracji kontenera
• Ręcznie zaktualizować obraz kontenera
• Skonfigurować auto-update z opcją skanowania CVE przed aktualizacją

Tworzenie kontenerów:

Dockhand oferuje graficzny kreator kontenerów z obsługą wszystkich kluczowych parametrów: obrazu, portów, wolumenów, zmiennych środowiskowych, sieci, etykiet i polityki restartu.

---

7. Compose Stacks – wizualny edytor

Jedną z największych zalet Dockhand jest wbudowany, wizualny edytor stosów Docker Compose.

Tworzenie stosu:

1. Przejdź do sekcji Stacks w lewym menu.
2. Kliknij Create.
3. Nadaj stosowi nazwę.
4. Edytuj plik docker-compose.yml w wbudowanym edytorze (z podświetlaniem składni) lub użyj trybu wizualnego.
5. Zarządzaj sekretami i zmiennymi środowiskowymi oddzielnie od pliku Compose.
6. Kliknij Create & Start.

Zarządzanie sekretami w stosach:

Dockhand rozróżnia zwykłe zmienne środowiskowe od sekretów (haseł, kluczy API). Sekrety są szyfrowane w bazie danych i nigdy nie są widoczne w postaci jawnej po zapisaniu. Są wstrzykiwane do kontenera w trakcie deploymentu.

Zdalne deploymenty:

Dockhand stosuje scentralizowane podejście – pliki Compose żyją na węźle Dockhand, a nie na zdalnych serwerach. Zalety:

• Jedno źródło prawdy – wszystkie definicje stosów w jednym miejscu, łatwy audyt i kontrola wersji
• Mniejsza powierzchnia ataku – zdalne węzły nie potrzebują dostępu do plików konfiguracyjnych ani SSH/SFTP
• Uproszczone zarządzanie sekretami – wrażliwe zmienne środowiskowe pozostają na węźle Dockhand i są wstrzykiwane w momencie deployu

---

8. Integracja z Git i GitOps

Dockhand obsługuje GitOps – możesz połączyć stos Compose bezpośrednio z repozytorium Git (GitHub, GitLab, Gitea, Bitbucket itp.).

Konfiguracja GitOps:

1. W ustawieniach Dockhand (Settings → Git) dodaj swoje repozytorium i dane uwierzytelniające (token lub klucz SSH).
2. Tworząc lub edytując stos, wybierz źródło Git i wskaż ścieżkę do pliku Compose w repozytorium.
3. Skonfiguruj webhook – przy każdym push do repozytorium Dockhand automatycznie pobierze zmiany i ponownie wdroży stos.
4. Możesz też włączyć auto-sync – Dockhand cyklicznie sprawdza repozytorium i synchronizuje zmiany.

To idealne rozwiązanie dla zespołów stosujących Infrastructure as Code – cała konfiguracja kontenerów w repozytorium Git, automatycznie wdrażana na serwer.

---

9. Skanowanie podatności – Grype i Trivy

Dockhand integruje dwa wiodące skanery CVE obrazów Docker: Grype (Anchore) i Trivy (Aqua Security).

Jak działa skanowanie:

• Skanery są pobierane jako osobne kontenery przy pierwszym użyciu (lub wcześniej ręcznie)
• Możesz skanować dowolny obraz w sekcji Images
• Możesz zaplanować automatyczne skanowanie przez Schedules
• Wyniki pokazują CVE z podziałem na krytyczność: Critical, High, Medium, Low

Safe-pull protection:

Przy włączonych auto-aktualizacjach Dockhand implementuje mechanizm Safe-pull:

1. Nowy obraz jest pobierany do tymczasowego taga
2. Obraz jest skanowany pod kątem CVE
3. Jeśli podatności przekraczają ustawiony próg – tymczasowy obraz jest usuwany, a kontener nadal działa na starym obrazie
4. Jeśli skan przeszedł – stary obraz jest zastępowany nowym

Konfiguracja progu blokowania aktualizacji:

• Never block – aktualizuj zawsze (skan działa dla widoczności)
• Any vulnerability – blokuj przy jakiejkolwiek podatności (najostrzejszy tryb)
• Critical or High – zrównoważone podejście dla produkcji
• Critical only – blokuj tylko przy krytycznych CVE

---

10. Automatyczne aktualizacje kontenerów

Dockhand zastępuje Watchtower dzięki wbudowanemu systemowi auto-aktualizacji.

Konfiguracja auto-update:

Na poziomie każdego kontenera możesz skonfigurować:

• Sprawdzanie aktualizacji – Dockhand powiadamia, gdy pojawi się nowy tag obrazu
• Automatyczne aktualizacje – nowe obrazy są pobierane i wdrażane automatycznie
• Harmonogram – definiuj okna serwisowe (np. aktualizuj tylko w nocy)
• Polityka bezpieczeństwa – połącz auto-update ze skanowaniem CVE (Safe-pull)

Ręczna aktualizacja:

W widoku listy kontenerów te z dostępnymi aktualizacjami są wyraźnie oznaczone. Kliknięcie przycisku aktualizacji pobiera nowy obraz i restartuje kontener.

---

11. Monitorowanie i powiadomienia

Dashboard i metryki:

Dockhand oferuje dashboard z kaflem dla każdego środowiska, pokazujący:

• Zużycie CPU i RAM w czasie rzeczywistym
• Użycie dysku hosta
• Status NVIDIA i AMD GPU (dla kontenerów GPU-accelerated)
• Liczba działających/zatrzymanych/błędnych kontenerów

Log aktywności:

Sekcja Activity rejestruje wszystkie akcje wykonane w Dockhand – kto, co, kiedy. W edycji Enterprise logi aktywności są bardziej szczegółowe i przeznaczone do audytu.

Powiadomienia są wysyłane przy: dostępności nowych aktualizacji obrazów, wynikach skanowania CVE, błędach kontenerów, zakończeniu zadań harmonogramu.

---

12. Uwierzytelnianie – SSO, OIDC, MFA, LDAP

Dockhand oferuje w darmowej wersji funkcje uwierzytelniania, za które Portainer pobiera opłaty:

Lokalni użytkownicy:

Podstawowy system użytkowników z zarządzaniem hasłami bezpośrednio w Dockhand.

OIDC / SSO:

Integracja z dowolnym dostawcą tożsamości obsługującym OpenID Connect:

• Keycloak
• Authentik
• Authelia
• Google Workspace
• Microsoft Entra ID (Azure AD)
• Okta
• GitHub OAuth
• i inne

Konfiguracja w Settings → Authentication → OIDC/SSO. Wymagane: Client ID, Client Secret, URL dostawcy.

Multi-Factor Authentication (MFA):

Dockhand obsługuje TOTP (Google Authenticator, Authy, 1Password itp.) jako drugi składnik uwierzytelnienia. MFA jest dostępne bezpłatnie dla wszystkich użytkowników.

LDAP / Active Directory (licencja):

Integracja z LDAP i Active Directory dostępna jest w edycji Enterprise, umożliwiając centralne zarządzanie użytkownikami w organizacji.

---

13. Szyfrowanie danych

Dockhand automatycznie szyfruje wszystkie wrażliwe dane (hasła rejestrów, tokeny, sekrety stosów) przy użyciu AES-256.

Jak działa szyfrowanie:

• Przy pierwszym uruchomieniu generowany jest losowy 256-bitowy klucz
• Klucz jest przechowywany w $DATA_DIR/.encryption_key z uprawnieniami 0600
• Wszystkie wrażliwe pola są szyfrowane przed zapisem do bazy danych

Zarządzanie kluczem szyfrowania:

Zalecane podejście produkcyjne to przekazanie własnego klucza przez zmienną środowiskową:

bash

docker run -d \
  --name dockhand \
  -e ENCRYPTION_KEY=twoj-bezpieczny-klucz-256-bit \
  ...
  fnsys/dockhand:latest

Ważne: Jeśli utracisz plik .encryption_key i nie masz ustawionej zmiennej ENCRYPTION_KEY, zaszyfrowane dane są nie do odzyskania. Zawsze uwzględnij plik klucza w backupach, lub używaj zmiennej środowiskowej z menedżera sekretów (Vault, Docker secrets).

---

14. Dockhand Enterprise vs Free

Funkcja	Free	Enterprise
Zarządzanie kontenerami	Tak	Tak
Compose Stacks	Tak	Tak
Git/GitOps	Tak	Tak
Terminal webowy	Tak	Tak
Przeglądarka plików	Tak	Tak
Skanowanie CVE	Tak	Tak
Safe-pull	Tak	Tak
SSO/OIDC	Tak	Tak
MFA	Tak	Tak
Powiadomienia (Apprise)	Tak	Tak
Hawser (multi-host)	Tak	Tak
Lokalni użytkownicy	Tak pełny admin	Tak
LDAP/Active Directory	Nie	Tak
RBAC (role i uprawnienia)	Nie	Tak
Audit logging	Podstawowy	Zaawansowany

Darmowa wersja jest bezpłatna na zawsze do użytku osobistego, wewnętrznego biznesowego, non-profit, edukacyjnego i ewaluacyjnego. Niedozwolone jest oferowanie Dockhand jako komercyjnej usługi SaaS/hosted (licencja BSL 1.1).

---

15. Najczęstsze pytania (FAQ)

Czy Dockhand jest bezpieczny? Tak. Dockhand buduje własną warstwę OS od zera (Wolfi/apko), zero telemetrii, wbudowane skanowanie CVE, AES-256 szyfrowanie wrażliwych danych, wsparcie dla Docker socket proxy. Wersja 1.0.5+ praktycznie eliminuje podatności znane z obrazów Alpine.

Czy mogę używać Dockhand w firmie? Tak – darmowa wersja jest dopuszczona do wewnętrznego użytku biznesowego. Licencja BSL 1.1 zabrania jedynie odsprzedaży Dockhand jako usługi hostowanej.

Jak zaktualizować Dockhand? Najprościej: w interfejsie Dockhand możesz zaktualizować samego siebie tak jak każdy inny kontener (funkcja auto-update lub ręczna aktualizacja obrazu).

Co to jest Hawser? Hawser to otwartoźródłowy agent Dockhand do zarządzania zdalnymi hostami Docker. Umożliwia zarządzanie maszynami za NAT bez otwierania portów przychodzących.

Czy Dockhand działa na Raspberry Pi? Tak – Dockhand obsługuje architekturę ARM64 i ARMv7, działa na Raspberry Pi 3/4/5 i innych urządzeniach ARM.

Czy Dockhand zastępuje Portainer? Dla zdecydowanej większości przypadków użycia – tak. Dockhand oferuje wszystkie kluczowe funkcje Portainer CE oraz wiele dodatkowych (SSO, MFA, skanowanie CVE, Safe-pull, Apprise, Hawser) bez dodatkowych kosztów.

Jak wykonać backup Dockhand? Wystarczy zbackupować wolumen danych (dockhand_data lub ścieżka bind mount) oraz plik .encryption_key. Wszystkie konfiguracje stosów, użytkownicy, ustawienia i sekrety są tam zapisane.

Czy Dockhand obsługuje GPU? Tak – Dockhand monitoruje NVIDIA i AMD GPU: użycie, pamięć i temperaturę dla kontenerów GPU-accelerated.

---

16. Podsumowanie

Dockhand jest w 2025/2026 roku jednym z najlepszych narzędzi do zarządzania Dockerem – zarówno dla homelabberów, jak i małych i średnich przedsiębiorstw. Łączy w sobie nowoczesny, szybki interfejs z zaawansowanymi funkcjami bezpieczeństwa i operacyjnymi, które wcześniej wymagały utrzymania kilku osobnych kontenerów.

Kluczowe przewagi Dockhand:

• Jeden kontener zamiast siedmiu – zastępuje Portainer, Watchtower, Dozzle, Beszel, Dockge, Diun/WUD i PruneMate
• Bezpieczeństwo przez design – hardened OS, szyfrowanie, skanowanie CVE, Safe-pull, socket proxy
• Zero kosztów dla osób prywatnych i firm – SSO, MFA, GitOps bez opłat
• Prywatność – zero telemetrii, zero analityk, zero połączeń do zewnętrznych serwerów
• Aktywny rozwój – projekt jest intensywnie rozwijany przez Jareka Krochmalskiego

Instalacja zajmuje dosłownie jedną minutę (docker run lub docker compose up -d) i nie wymaga żadnej konfiguracji startowej poza opcjonalnym włączeniem uwierzytelniania.