🐳 Agent w Dockerze

Docker to sposób na zainstalowanie agenta na dowolnym komputerze, niezależnie od tego, czy ma on własny pakiet. Jeśli twój komputer to Synology, QNAP, TrueNAS, PC z Windows albo Home Assistant, najpierw zajrzyj na jego stronę w Agent lokalny: z pakietem masz mniej kroków.

---

Czego potrzebujesz

• Komputera w warsztacie, który jest zawsze włączony: serwera NAS, mini-PC, komputera w warsztacie, Raspberry Pi albo serwera, który już masz.
• Dockera z Docker Compose albo Portainera, czyli Dockera z interfejsem graficznym.
• Żeby był w tej samej sieci co drukarki, wtedy znajdzie je sam.

Jest lekki: nie potrzebuje mocnego komputera, a manifest ogranicza go do 512 MB pamięci.

W Docker Desktop (Windows i Mac) nie ma automatycznego wykrywania. Docker działa tam wewnątrz maszyny wirtualnej, która nie widzi sieci komputera, więc drukarki dodaje się po IP. Działają dokładnie tak samo; dochodzi tylko jeden krok przy ich dodawaniu. W Windows instalator dla Windows nie ma tego ograniczenia.

---

Tworzenie go w BolloPrint

1. Przejdź do Ustawienia → Drukarki i otwórz kartę Agent lokalny.
2. Kliknij Nowy agent. W Gdzie go zainstalujesz? wybierz Docker, w sekcji W kontenerze.
3. Nadaj mu nazwę, którą rozpoznasz. Lepiej nazwać go od tego, gdzie stoi, niż od tego, czym jest: „Parter”, „Hala 2”.
4. Kliknij Utwórz agenta.
5. Pojawia się manifest, z kodem agenta i jego tożsamością już wpisanymi w środku. Zostaw kartę Docker Compose i kliknij Kopiuj. Nie trzeba niczego podmieniać.
6. Gdy manifest jest zapisany w bezpiecznym miejscu, kliknij Zapisz, żeby zamknąć okno.

Tak wygląda manifest. Twój ma twoje klucze zamiast CHANGE_ME i aktualną w danym momencie wersję agenta zamiast YYYY:

services:
  bolloprint-agent:
    image: ghcr.io/bolloprint/bolloprint-agent:YYYY
    container_name: bolloprint_agent
    restart: unless-stopped
    network_mode: host
    mem_limit: 512m
    pids_limit: 512
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      BP_AGENT_CODE: CHANGE_ME
      BP_AGENT_INSTANCE_ID: CHANGE_ME
      BP_PLATFORM: docker
    volumes:
      - identity:/var/lib/bolloprint

volumes:
  identity:
    name: bolloprint_agent_identity

Nie kopiuj tego stąd: zawsze kopiuj swój z ekranu BolloPrint, bo tylko on ma twoje klucze.

Dwie linie, które warto rozumieć:

• BP_AGENT_CODE i BP_AGENT_INSTANCE_ID to klucze agenta: kim jest i w którym warsztacie pracuje. Traktuj je jak hasło.
• network_mode: host pozwala agentowi widzieć twoją sieć, żeby znaleźć drukarki. Nie otwiera żadnego portu.

---

Uruchomienie go na twoim komputerze

Manifest wklejasz bez zmian, niczego nie ruszając. Wybierz sposób, z którego korzystasz.

Docker Compose

1. Utwórz folder dla agenta, na przykład bolloprint-agent.
2. W środku zapisz manifest jako docker-compose.yml.
3. Z tego folderu uruchom go:

docker compose up -d

Portainer

1. Przejdź do Stacks → Add stack i nadaj mu nazwę, na przykład bolloprint-agent.
2. W Web editor wklej manifest bez zmian.
3. Kliknij Deploy the stack.

Menedżer kontenerów twojego NAS-a

Jeśli twój NAS ma własny menedżer kontenerów (na przykład Container Manager w Synology), utwórz nowy projekt, wklej manifest jako jego docker-compose.yml i uruchom go. To to samo co Docker Compose, tylko z interfejsem graficznym.

---

Sprawdzenie, czy działa

W niecałą minutę agent zmienia stan z Niezainstalowany na Online na karcie Agent lokalny, z nazwą komputera, na którym działa, i swoją wersją. Nie poprosi o autoryzację: ta instalacja jest już autoryzowana.

Jeśli się nie pojawia, sprawdź jego log na komputerze, na którym działa:

docker logs bolloprint_agent --tail 50

Co się dzieje	Co sprawdzić
Nigdy się nie pojawia	Czy manifest został wklejony w całości, bez zmian? Czy komputer ma dostęp do internetu? Czy zapora nie blokuje ruchu wychodzącego?
Pojawia się, ale prosi o autoryzację	Manifest nie zawiera BP_AGENT_INSTANCE_ID (był edytowany ręcznie albo jest stary). Wygeneruj klucze ponownie i wdróż nowy manifest bez zmian.
Jest online, ale nie znajduje drukarek	Jeśli jest w innej sieci niż drukarki albo używasz Docker Desktop, tak ma być: dodaj je przyciskiem Dodaj po IP.

Gdy agent jest online, następny krok to podłączenie drukarek: znajdziesz to w Drukarki w sieci lokalnej.

---

Aktualizacja

Od wersji 2026.1.1 agent aktualizuje się sam: gdy wychodzi nowa wersja, pobiera ją, sprawdza, że pochodzi od nas, i uruchamia się z nią ponownie. Nigdy nie robi tego, gdy któraś z jego drukarek drukuje. Nie musisz ruszać swojego pliku.

Ręczna aktualizacja jest potrzebna tylko wtedy, gdy BolloPrint cię o nią poprosi (na przykład w przypadku agenta zainstalowanego dawno temu, w wersji sprzed automatycznych aktualizacji). Zobaczysz to tak:

• Nad zakładkami w Ustawienia → Drukarki pojawia się powiadomienie z nazwą twojego agenta: „»Parter« używa wersji XXXX. Dostępna jest już wersja YYYY”, z przyciskiem Jak zaktualizować.
• W zakładce Agent lokalny numer wersji tego agenta jest pomarańczowy. Jeśli jest czerwony, ta wersja nie jest już obsługiwana i warto zaktualizować jak najszybciej.

Co się zmienia

Zmienia się tylko linia image:, a w niej tylko wersja, czyli to, co stoi po dwukropku. Wszystko inne zostaje dokładnie tak samo: klucze, wolumen i reszta konfiguracji.

Właściwą wersję znajdziesz w zakładce Wdrożenie swojego agenta (menu ⋮ → Edytuj): to ta w linii image:.

Przed

    image: ghcr.io/bolloprint/bolloprint-agent:XXXX

Po

    image: ghcr.io/bolloprint/bolloprint-agent:YYYY

Z Docker Compose

1. Otwórz docker-compose.yml agenta i zmień wersję w linii image:.
2. Z folderu, w którym jest ten plik, pobierz nową wersję i uruchom agenta ponownie:

docker compose pull
docker compose up -d

Docker zastępuje kontener nowym, z tą samą konfiguracją i tym samym wolumenem.

Z Portainerem

1. Przejdź do Stacks i otwórz stack agenta.
2. Kliknij Editor i zmień wersję w linii image:.
3. Włącz Re-pull image and redeploy (albo Pull latest image, zależnie od wersji Portainera) i kliknij Update the stack.

Jak sprawdzić, że się udało

W niecałą minutę agent znów pokazuje się jako Online, z nową wersją i bez koloru ostrzeżenia. Powiadomienie nad zakładkami znika samo. Podczas restartu kontenera drukarki mogą przez kilka sekund pokazywać Rozłączona: wracają same, a trwające wydruki toczą się dalej na maszynie.

A jeśli nowa wersja sprawia ci problemy? Wpisz z powrotem poprzednią wersję w linii image: i wdróż tak samo. Potem utwórz zgłoszenie do wsparcia, żebyśmy to sprawdzili.

---

Przeniesienie na inny komputer

Tożsamość agenta jest w manifeście (BP_AGENT_INSTANCE_ID), więc ten sam plik uruchomiony na innej maszynie to nadal ten sam agent: z jego drukarkami, bez proszenia o autoryzację i bez kopiowania czegokolwiek osobno.

1. Na starym komputerze zatrzymaj go: docker compose down w jego folderze albo usuń stack w Portainerze.
2. Przenieś docker-compose.yml na nowy komputer i uruchom go tam poleceniem docker compose up -d.

Zatrzymaj stary przed uruchomieniem nowego: dwa komputery z tymi samymi kluczami jednocześnie przeszkadzają sobie w połączeniu.

Jeśli twój manifest jest stary i nie ma linii BP_AGENT_INSTANCE_ID, po uruchomieniu na innym komputerze agent pojawi się jako instalacja oczekująca na autoryzację (niżej). Autoryzuj ją, a nadal będzie to ten sam agent, z całą historią.

Nie masz już pliku? Wtedy wygeneruj klucze ponownie i wdróż nowy manifest na nowym komputerze.

---

Ponowne generowanie kluczy

W oknie agenta (menu ⋮ → Edytuj), w zakładce Wdrożenie, opcja Wygeneruj klucze ponownie tworzy nowy kod i nową tożsamość i pokazuje manifest z nimi.

Używaj jej w dwóch przypadkach:

• Zgubiono manifest i trzeba ponownie wdrożyć agenta.
• Podejrzewasz, że ktoś ma twoje klucze, na przykład dlatego, że pojawia się instalacja, która nie jest twoja.

Natychmiast odcina agenta: poprzedni kod i tożsamość przestają działać w chwili kliknięcia przycisku, a agent pozostaje rozłączony, dopóki nie wdrożysz go ponownie z nowym manifestem. Tutaj wklejasz manifest w całości, w miejsce dotychczasowego, i uruchamiasz go ponownie (docker compose up -d albo Update the stack w Portainerze). Wolumen zostaje bez zmian.

Jeśli agent nigdy się nie połączył (widać Niezainstalowany), ponowne generowanie niczego nie przerywa.

Do aktualizacji nie trzeba generować kluczy ponownie. Wystarczy zmienić wersję obrazu.

---

Autoryzowanie instalacji

Instalacja ze skopiowanego manifestu wchodzi od razu. Każda inna instalacja używająca tego samego kodu czeka na twoją zgodę: zobaczysz czerwone powiadomienie nad zakładkami, a w agencie, w zakładce Stan, instalację w sekcji Instalacje oczekujące na autoryzację, z nazwą komputera, z którego się łączy.

Przy aktualnym manifeście prawie się to nie zdarza. To normalne w przypadku starszego agenta, wdrożonego z manifestu bez BP_AGENT_INSTANCE_ID, gdy przenosisz go na inną maszynę, usuwasz jego wolumen albo instalujesz go od zera.

Kliknij Autoryzuj, jeśli rozpoznajesz komputer. Gdy autoryzujesz jeden, poprzedni traci dostęp.

---

Usuwanie

1. W BolloPrint, w wierszu agenta, wybierz menu ⋮ → Usuń. Jego drukarki znikają z listy razem z nim (ich historia nie przepada: zobacz Agent lokalny).
2. Na swoim komputerze zatrzymaj i usuń kontener: docker compose down w jego folderze albo usuń stack w Portainerze. BolloPrint nie może zrobić tego za ciebie.
3. Jeśli nie będziesz go już używać, usuń też jego wolumen:

docker volume rm bolloprint_agent_identity

---

Czego NIE robić

• Nie używaj tego samego manifestu na dwóch komputerach jednocześnie. Dwa komputery to dwa agenty, każdy z własnym manifestem.
• Nie generuj kluczy ponownie, żeby zaktualizować. To odcina agenta, dopóki nie wdrożysz go ponownie.
• Nie twórz nowego agenta, żeby zaktualizować. Aktualizacja to ten sam agent w innej wersji; nowy miałby inne klucze, a jego drukarki nie przeszłyby same.
• Nie zmieniaj ręcznie kluczy w manifeście ani nie kopiuj ich do innej instalacji.

---

Najczęstsze pytania

Czy muszę otwierać porty? Nie. To agent łączy się z BolloPrint, a nie odwrotnie, i nie udostępnia żadnego portu na twoim komputerze.

Czy przy aktualizacji albo przeniesieniu tracę drukarki lub historię? Nie. Drukarki i wszystko, co wydrukowały, są w BolloPrint, a nie w agencie.

Czy mogę przeskakiwać wersje? Tak. Przejdź od razu na tę, która pojawia się w zakładce Wdrożenie.

Do czego służy wolumen? Agent trzyma w nim swój log z ostatnich dni i wersje, które pobiera przy aktualizacji. W agentach wdrożonych ze starego manifestu także swoją tożsamość. Nie przechowuje danych o wydrukach.

Czy działa na Raspberry Pi? Tak. Obraz nadaje się na komputery Intel/AMD i ARM; Docker sam wybiera właściwy.