Automatyczny deploy usług w Portainer

Spis treści

• Przygotowanie repo
• Struktura katalogów
• GitHub token
• Tworzymy Stack
• Co dalej?

W tym rozdziale zbudujemy solidne podstawy do automatycznego deploy-u usług w Portainer.

Na początku:

Przygotujemy repozytorium na GitHubie, w którym będziemy trzymać:

• pliki docker-compose.yml,
• definicje stacków,
• konfigurację usług,
• ...w przyszłości backup-y konfiguracji

Stworzymy lokalną strukturę plików i folderów, a następnie wypchniemy wszystko do repozytorium.

Kolejny krok to konfiguracja Portainer:

Utworzymy stack oparty o repozytorium Git i skonfigurujemy go tak, aby:

• automatycznie pobierał pliki,
• aktualizował usługi przy zmianach w repozytorium.

Dlaczego zaczynamy właśnie od tego?

Bo dobrze przygotowane fundamenty:

• upraszczają dalszą rozbudowę infrastruktury,
• pozwalają wdrażać nowe usługi w kilka kliknięć,
• dają Ci realne Infrastructure as Code – czyli pełną kontrolę nad środowiskiem z poziomu Git.

Po przejściu tych kroków kolejne deploye będą już tylko formalnością.

---

Przygotowanie repo pomiń

Krok 1 – tworzymy nowe repo

Na początek zakładamy nowe repozytorium na GitHubie.

• Repository name: np.: home_automation
• Description: np.: Home Automation local environment
• Choose visibility: public => private
• Create repository

Po utworzeniu repo GitHub wyświetli Ci krótką instrukcję startową — dokładnie z niej skorzystamy.

Krok 2 – przygotowanie projektu lokalnie

Na swoim komputerze tworzysz katalog roboczy, np.:

home_automation

Najwygodniej od razu otworzyć go w Visual Studio Code — za chwilę i tak będziemy używać VSC jako:

• edytora plików docker-compose.yml,
• edytora konfiguracji stacków,
• a później również do edycji plików YAML w Home Assistant.

Krok 3 – inicjalizacja repozytorium

W terminalu, w katalogu projektu, wykonujesz dokładnie te polecenia, które podpowiada GitHub.

tak możesz je skopiować wszystkie na raz i wkleić w terminalu.

Krok 4 – sprawdzenie na GitHubie

Odśwież stronę repozytorium w przeglądarce. Jeśli wszystko poszło poprawnie:

• zniknie ekran z instrukcją startową,
• zobaczysz swoje pierwsze pliki w repo.

Od tego momentu masz już centralne miejsce na całą konfigurację infrastruktury — dokładnie to, czego potrzebujemy do dalszej automatyzacji w Portainerze

W kolejnym kroku przygotujemy strukturę katalogów pod stacki i usługi.

---

Struktura katalogów: DEV i PROD pomiń

Na początek przygotujmy porządną strukturę katalogów na pliki konfiguracyjne.

Tworzymy dwa główne katalogi:

/dev
/prod

Dlaczego taki podział?

Dla wygody i bezpieczeństwa:

• dev – środowisko testowe. Tu sprawdzasz nowe wersje obrazów, zmiany w konfiguracji, nowe stacki.

• prod – środowisko produkcyjne. Tu trafiają tylko sprawdzone i stabilne konfiguracje.

Dzięki temu:

• nie psujesz działającego domu testami,
• masz pełną kontrolę nad tym, co trafia na produkcję,
• możesz wdrażać zmiany etapami (DEV → PROD).

Na razie skupiamy się na DEV — do produkcji wrócimy później.

Pierwszy plik stacka

W katalogu dev tworzymy plik:

home_automation.yaml lub home_automation.yml

Przykładowa konfiguracja homeassiatnta:

services:
  homeassistant:
    image: "ghcr.io/home-assistant/home-assistant:latest"
    container_name: homeassistant-dev
    restart: on-failure
    volumes:
      - "/etc/localtime:/etc/localtime:ro"
    ports:
      - "8123:8123"
    privileged: true

Co tu się dzieje?

• services – lista usług w stacku
• homeassistant – nazwa usługi (będzie też nazwą hosta w sieci Dockera)
• image – oficjalny obraz Home Assistanta z GitHub Container Registry
• container_name – czytelna nazwa kontenera
• restart: on-failure – kontener restartuje się tylko gdy coś pójdzie nie tak
• volumes - synchronizacja czasu z hosta (/etc/localtime)
• ports - wystawiamy interfejs HA na http://IP_SERWERA:8123
• privileged: true wymagane w wielu instalacjach HA (USB, Bluetooth, Zigbee, itp.)

Od tego momentu masz już pierwszy realny element infrastruktury jako kod.

szybkie wypchnięcie do repozytorium:

git add .
git commit -m "Added homeassistant service" 
git push

lub przez UI

następnie Sync changes

---

GitHub Token (do integracji z Portainerem) pomiń

Gdzie wygenerować token?

Przechodzimy do github.com/settings/tokens

Ścieżka w UI: Awatar → Settings → Developer settings → Personal access tokens → Tokens (classic)

Następnie klikamy:

Generate new token → Generate new token (classic)

Konfiguracja tokena

Ustawienia:

• w polu Note nadajemy nazwę, np: portainer_token

• Expiration: wybieramy Custom i ustawiamy 1 rok - (krótszy czas = większe bezpieczeństwo)

• Scopes zaznaczamy repo

To wystarczy, żeby Portainer mógł:

• czytać repozytoria,
• pobierać pliki stacków,
• wykonywać automatyczny deploy.

i klikamy Genrate token

Bardzo ważne – bezpieczeństwo

Token pojawi się tylko raz.

Skopiuj go i zapisz w bezpiecznym miejscu (np. menedżer haseł).

• nie wrzucaj do repozytorium
• nie wklejaj w tutorialach
• nie trzymaj w plain text na serwerze
• używaj tylko w Portainerze jako secret / credential

Jeśli token wycieknie — natychmiast go unieważnij i wygeneruj nowy.

---

Tworzenie stack-a w Portainer pomiń

Co będzie potrzebne?

Do utworzenia stacka z repozytorium GitHub potrzebujesz:

• nazwy użytkownika GitHub
• Personal Access Token (z poprzedniego kroku)
• nazwy repozytorium
• lokalizacji pliku docker-compose

Jak znaleźć potrzebne dane?

Wejdź do swojego repozytorium i przejdź dokładnie do pliku stacka, np.:

https://github.com/<<YOUR_NAME>>/<<YOUR_REPO_NAME>>/blob/main/DEV/home_automation.yaml

Z tego adresu wyciągamy:

• <<YOUR_NAME>> – Twoja nazwa użytkownika na GitHubie
• <<YOUR_REPO_NAME>> – nazwa repozytorium
• /dev/home_automation.yaml – ścieżka do pliku compose, zwróć uwage na rozszerzenie .yaml / .yml
• adres repozytorium do Portainera: https://github.com/<<YOUR_NAME>>/<<YOUR_REPO_NAME>>.git

---

Dodajemy stack w Portainer

1. Wybór środowiska

Jeśli w lewym menu widzisz: Environment: None selected

Kliknij i wybierz swoje środowisko.

---

2. Dodanie stacka

Przechodzimy do Stacks → Add stack

---

3. Konfiguracja stacka

Podstawowe ustawienia

• Name - nazwa stacka, np. home_automation_dev małe litery, bez spacji i bez myślników
• Build method: Repository

---

4. Dostęp do repozytorium

Zaznacz Authentication i uzupełnij:

• Username: <<YOUR_NAME>>
• Personal Access Token: <<YOUR_TOKEN>>
• Repository URL: https://github.com/<<YOUR_NAME>>/<<YOUR_REPO_NAME>>.git
• Compose path: /DEV/home_automation.yaml - to jest lokalizacja pliku compose na githubie

---

5. Deploy options – automatyzacja

To jedna z najważniejszych sekcji.

zaznaczamy opcje GitOps updates

Na start ustaw:

• Mechanizm: Polling
• Fetch interval: np 5 minut

Co to daje?

Portainer:

• co 5 minut sprawdzi repozytorium,
• jeśli wykryje zmianę → automatycznie zaktualizuje stack,
• jeśli nie → nic nie robi.

To jest podstawowy, ale bardzo skuteczny GitOps.

---

6.Environment variables

Sekcja Environment variables pozwala dodać zmienne środowiskowe przekazywane do kontenerów.

Na tym etapie:

• nie musisz nic dodawać,

ale warto wiedzieć, że:

• tu trzymasz hasła,
• tokeny,
• ścieżki,
• tryby DEV/PROD itd.

W przyszłości będziesz z tego korzystać bardzo często.

---

7. Deploy

Na końcu upewnij się, że Access control jest zaznaczony oraz grupa jest ustawiona na 'Administrators', następnie klikamy: Deploy the stack

Pierwsze uruchomienie może potrwać chwilę — obraz Home Assistanta jest dość duży.

Weryfikacja

Po poprawnym deployu:

• Zostaniesz przekierowany do listy stacków.
• Wejdź w zakładkę Containers.
• Powinieneś zobaczyć: homeassistant-dev

Sprawdzenie w przeglądarce

Otwórz:

http://IP_SERWERA:8123

Jeśli wszystko poszło dobrze — zobaczysz ekran powitalny Home Assistanta - pamiętaj że to test, nie ma tu zamontowanych volumenów wiec po restarcie dane znikną. W kolejnym wpisie zrobimy to produkcyjnie. 😎

---

Co właśnie zrobiłeś?

Zbudowałeś fundament pod Infrastructure as Code i przeszedłeś cały proces tworzenia pierwszego stacka w Portainerze — i to jest dokładnie ten moment, w którym zaczyna się porządkowanie infrastruktury.

Od teraz, korzystając z tego samego schematu, będziesz mógł:

• tworzyć kolejne stacki dla następnych grup usług,
• oddzielać środowiska DEV / PROD,
• porządkować serwisy w logiczne „grupy”.

W kolejnym wpisie przejdziemy już do wdrożenia produkcyjnego Home Assistanta: z użyciem zmiennych środowiskowych, z podpiętym wolumenem na dane i z konfiguracją gotową na realne użycie.

W następnych kilku wpisach stworzymy co najmniej trzy takie stacki, każdy do innej roli w Twojej infrastrukturze — i zobaczysz, jak bardzo ułatwia to dalszą pracę