🐳 Agent v Dockeru

Docker je způsob, jak nainstalovat agenta na jakýkoli počítač, ať má vlastní balíček, nebo ne. Pokud máte Synology, QNAP, TrueNAS, počítač s Windows nebo Home Assistant, podívejte se nejdřív na jeho stránku v článku Místní agent: s balíčkem to má méně kroků.

---

Co potřebujete

• Počítač v dílně, který je stále zapnutý: NAS, mini-PC, počítač v dílně, Raspberry Pi nebo server, který už máte.
• Docker s Docker Compose, nebo Portainer, což je Docker s grafickým rozhraním.
• Aby byl ve stejné síti jako tiskárny, aby je našel sám.

Je nenáročný: nepotřebuje výkonný počítač a manifest ho omezuje na 512 MB paměti.

V Docker Desktop (Windows a Mac) automatické vyhledávání nefunguje. Docker tam běží uvnitř virtuálního počítače, který nevidí síť počítače, takže tiskárny se přidávají podle IP adresy. Fungují úplně stejně, jen je při jejich přidávání o jeden krok navíc. Ve Windows toto omezení instalátor pro Windows nemá.

---

Vytvoření v BolloPrint

1. Přejděte do Nastavení → Tiskárny a otevřete záložku Místní agent.
2. Klikněte na Nový agent. U otázky Kam ho nainstalujete? zvolte v části V kontejneru možnost Docker.
3. Dejte mu název, který poznáte. Lepší je kde je než co je: „Přízemí“, „Hala 2“.
4. Klikněte na Vytvořit agenta.
5. Zobrazí se manifest, ve kterém je kód agenta i jeho identita už vepsané. Nechte záložku Docker Compose a klikněte na Kopírovat. Není potřeba nic nahrazovat.
6. Až budete mít manifest uložený na bezpečném místě, klikněte na Uložit a okno se zavře.

Takto manifest vypadá. Ten váš má místo CHANGE_ME vaše klíče a místo YYYY verzi agenta, která má v tu chvíli běžet:

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

Tento odsud nekopírujte: vždy kopírujte ten svůj z obrazovky BolloPrint, protože jen ten obsahuje vaše klíče.

Dva řádky, kterým je dobré rozumět:

• BP_AGENT_CODE a BP_AGENT_INSTANCE_ID jsou klíče agenta: kdo je a ve které dílně pracuje. Zacházejte s nimi jako s heslem.
• network_mode: host umožňuje agentovi vidět vaši síť a najít tiskárny. Neotevírá žádný port.

---

Spuštění na vašem počítači

Manifest se použije beze změn, nic v něm neupravujte. Zvolte způsob, který používáte.

Docker Compose

1. Vytvořte pro agenta složku, například bolloprint-agent.
2. Do ní uložte manifest jako docker-compose.yml.
3. Z této složky agenta spusťte:

docker compose up -d

Portainer

1. Přejděte do Stacks → Add stack a zadejte název, například bolloprint-agent.
2. Do Web editor vložte manifest beze změn.
3. Klikněte na Deploy the stack.

Správce kontejnerů na vašem NAS

Pokud má váš NAS vlastního správce kontejnerů (například Container Manager na Synology), vytvořte nový projekt, vložte manifest jako jeho docker-compose.yml a spusťte ho. Je to totéž co Docker Compose, jen s grafickým rozhraním.

---

Kontrola, že funguje

Za méně než minutu se agent na záložce Místní agent změní z Nenainstalováno na Online, s názvem počítače, na kterém běží, a se svou verzí. O autorizaci vás žádat nebude: tato instalace je už autorizovaná.

Pokud se nezobrazí, podívejte se na jeho log na počítači, kde běží:

docker logs bolloprint_agent --tail 50

Co se děje	Co zkontrolovat
Nezobrazí se vůbec	Byl vložen celý manifest, beze změn? Má počítač přístup k internetu? Neblokuje odchozí provoz firewall?
Zobrazí se, ale žádá o autorizaci	Manifest neobsahuje BP_AGENT_INSTANCE_ID (byl ručně upraven nebo je starší). Přegenerujte klíče a nasaďte nový manifest beze změn.
Je online, ale nenachází tiskárny	Pokud je v jiné síti než tiskárny nebo používáte Docker Desktop, je to očekávané: přidejte je přes Přidat podle IP.

Jakmile je agent online, dalším krokem je připojit tiskárny: najdete to na stránce Tiskárny v místní síti.

---

Aktualizace

Od verze 2026.1.1 se agent aktualizuje sám: když vyjde nová verze, stáhne ji, ověří, že pochází od nás, a restartuje se s ní. Nikdy to neudělá, dokud některá z jeho tiskáren tiskne. Na svůj soubor nemusíte sahat.

Ručně je to potřeba udělat, jen pokud vás o to BolloPrint požádá (například u agenta nainstalovaného už dávno, s verzí starší než automatická aktualizace). Poznáte to takto:

• Nad záložkami v Nastavení → Tiskárny se zobrazí upozornění s názvem vašeho agenta: „„Přízemí“ používá verzi XXXX. Už je k dispozici verze YYYY“, s tlačítkem Jak aktualizovat.
• Na záložce Místní agent se číslo verze tohoto agenta zobrazí oranžově. Pokud je červené, tato verze už není podporovaná a je dobré aktualizovat co nejdřív.

Co se mění

Mění se jen řádek image:, a v něm jen verze, tedy to, co je za dvojtečkou. Všechno ostatní zůstává přesně stejné: klíče, svazek i zbytek konfigurace.

Verzi, která má běžet, najdete na záložce Nasazení svého agenta (nabídka ⋮ → Upravit): je to ta na řádku image:.

Před

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

Po

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

S Docker Compose

1. Otevřete soubor docker-compose.yml agenta a změňte verzi na řádku image:.
2. Ze složky, ve které je tento soubor, stáhněte novou verzi a agenta znovu spusťte:

docker compose pull
docker compose up -d

Docker nahradí kontejner novým se stejnou konfigurací a stejným svazkem.

S Portainerem

1. Přejděte do Stacks a otevřete stack agenta.
2. Klikněte na Editor a změňte verzi na řádku image:.
3. Zapněte Re-pull image and redeploy (nebo Pull latest image, podle vaší verze Portaineru) a klikněte na Update the stack.

Kontrola, že vše proběhlo dobře

Za méně než minutu se agent znovu zobrazí jako Online, s novou verzí a bez varovné barvy. Upozornění nad záložkami samo zmizí. Během restartu kontejneru se tiskárny mohou na pár sekund zobrazit jako Odpojená: samy se vrátí a probíhající tisky na stroji normálně pokračují.

A když vám nová verze dělá problémy? Vraťte na řádek image: předchozí verzi a nasaďte stejným způsobem. Potom založte požadavek na podporu, abychom se na to podívali.

---

Přesun na jiný počítač

Identita agenta je přímo v manifestu (BP_AGENT_INSTANCE_ID), takže stejný soubor spuštěný na jiném počítači je stále tentýž agent: se svými tiskárnami, bez žádosti o autorizaci a bez čehokoli, co by bylo nutné kopírovat zvlášť.

1. Na starém počítači ho zastavte: docker compose down v jeho složce, nebo smažte stack v Portaineru.
2. Přeneste docker-compose.yml na nový počítač a spusťte ho tam pomocí docker compose up -d.

Starý zastavte dřív, než spustíte nový: dva počítače se stejnými klíči najednou si navzájem přebírají spojení.

Pokud je váš manifest starší a neobsahuje řádek BP_AGENT_INSTANCE_ID, po spuštění na jiném počítači se agent zobrazí jako instalace čekající na autorizaci (viz níže). Autorizujte ji a zůstane to stále tentýž agent, s celou svou historií.

Soubor už nemáte? Pak přegenerujte klíče a na novém počítači nasaďte nový manifest.

---

Přegenerování klíčů

V okně agenta (nabídka ⋮ → Upravit), na záložce Nasazení, vytvoří Přegenerovat klíče nový kód a novou identitu a ukáže vám s nimi manifest.

Použijte to ve dvou případech:

• Ztratili jste manifest a potřebujete agenta znovu nasadit.
• Máte podezření, že vaše klíče má někdo jiný, například proto, že se objevila instalace, která není vaše.

Agenta to okamžitě odpojí: předchozí kód a identita přestanou platit, jakmile kliknete na tlačítko, a agent zůstane odpojený, dokud ho znovu nenasadíte s novým manifestem. Tady manifest vložíte celý, místo toho, který jste měli, a agenta znovu spustíte (docker compose up -d, nebo Update the stack v Portaineru). Svazek zůstává, jak je.

Pokud se agent nikdy nepřipojil (zobrazuje se jako Nenainstalováno), přegenerování nic nepřeruší.

K aktualizaci není přegenerování potřeba. Stačí změnit verzi image.

---

Autorizace instalací

Instalace ze zkopírovaného manifestu se připojí rovnou. Každá jiná instalace, která používá stejný kód, čeká na vaše schválení: nad záložkami uvidíte červené upozornění a uvnitř agenta, ve Stavu, bude instalace v části Instalace čekající na autorizaci, s názvem počítače, ze kterého se připojuje.

Se současným manifestem se to téměř nestává. Běžně se to stává u staršího agenta, nasazeného s manifestem bez BP_AGENT_INSTANCE_ID, když ho přesunete na jiný počítač, smažete jeho svazek nebo ho přeinstalujete od začátku.

Pokud počítač poznáváte, klikněte na Autorizovat. Po autorizaci jedné instalace ztratí ta předchozí přístup.

---

Odebrání

1. V BolloPrint, na řádku agenta, zvolte nabídku ⋮ → Smazat. Jeho tiskárny zmizí ze seznamu spolu s ním (jejich historie se neztratí: viz Místní agent).
2. Na svém počítači kontejner zastavte a smažte: docker compose down v jeho složce, nebo smažte stack v Portaineru. BolloPrint to za vás udělat nemůže.
3. Pokud ho už nebudete používat, smažte i jeho svazek:

docker volume rm bolloprint_agent_identity

---

Co NEDĚLAT

• Nepoužívejte stejný manifest na dvou počítačích najednou. Pro dva počítače dva agenti, každý se svým.
• Nepřegenerovávejte klíče kvůli aktualizaci. Agenta to odpojí, dokud ho znovu nenasadíte.
• Nevytvářejte kvůli aktualizaci nového agenta. Aktualizace znamená stejného agenta s jinou verzí; nový agent by měl jiné klíče a jeho tiskárny by se samy nepřevedly.
• Neměňte ručně klíče v manifestu a nekopírujte je do jiné instalace.

---

Časté dotazy

Musím otevírat porty? Ne. Agent se připojuje k BolloPrint, ne naopak, a na vašem počítači nezveřejňuje žádný port.

Přijdu při aktualizaci nebo přesunu o tiskárny nebo historii? Ne. Tiskárny a všechno, co vytiskly, jsou v BolloPrint, ne v agentovi.

Mohu verze přeskočit? Ano. Přejděte rovnou na tu, která se zobrazuje na záložce Nasazení.

K čemu je svazek? Agent si do něj ukládá svůj log za posledních několik dní a verze, které stahuje při aktualizaci. U agentů nasazených se starším manifestem také svou identitu. Data o tiscích neukládá.

Funguje na Raspberry Pi? Ano. Image funguje pro počítače Intel/AMD i ARM; Docker si sám vybere tu správnou.