ProxMenux/web/messages/sk/docs/oci-manager/stacks.json

{
  "meta": {
    "title": "Aplikácie s viacerými kontajnermi | ProxMenux",
    "description": "Ako OCI manager Apps inštaluje aplikáciu s databázou a vyrovnávacou pamäťou do samostatných natívnych LXC: plán, súkromná sieť, riadiaci skript závislostí, overenie a aktualizácia s obnovou pri zlyhaní."
  },
  "header": {
    "title": "Aplikácie s viacerými kontajnermi",
    "description": "Aplikácia so svojou databázou, vyrovnávacou pamäťou a ďalšími službami sa stáva niekoľkými koordinovanými LXC, nainštalovanými a aktualizovanými ako jedna.",
    "section": "OCI manager Apps"
  },
  "sections": [
    {
      "id": "intro",
      "blocks": [
        {
          "calloutInfo": {
            "title": "Jedna aplikácia pre užívateľa, niekoľko LXC pre Proxmox VE",
            "body": "Definícia viacerých kontajnerov je jedným záznamom v katalógu. Inštalátor vytvorí jeden natívny LXC pre každú službu a explicitne spravuje ich závislosti. Immich, Nextcloud, Paperless-ngx a Tandoor sú nainštalované týmto spôsobom."
          }
        },
        {
          "mermaid": {
            "chartCode": "flowchart LR\n C[\"Docker Compose\"] --> O[\"{{plan}}\"]\n O --> A[\"{{app}}<br/>{{appNet}}\"]\n O --> D[\"{{db}}<br/>{{private}}\"]\n O --> R[\"{{cache}}<br/>{{private}}\"]\n V1[(\"config\")] --> A\n V2[(\"database\")] --> D\n V3[(\"cache\")] --> R\n D --> A\n R --> A",
            "labels": {
              "plan": "Plán inštalácie",
              "app": "Aplikácia LXC",
              "appNet": "LAN + súkromné",
              "db": "PostgreSQL LXC",
              "cache": "Valkey LXC",
              "private": "súkromné"
            }
          }
        }
      ]
    },
    {
      "id": "plan",
      "title": "1. Plán ešte pred vytvorením kontajnerov",
      "blocks": [
        {
          "p": "Počas spracovania definície Compose sa nevytvára žiadny LXC. Najprv vznikne úplný plán so všetkými kontajnermi, obrazmi, VMID, sieťami, cestami, citlivými údajmi, poradím spúšťania a kontrolami stavu služieb. Ak plán nie je konzistentný, inštalácia sa nezačne."
        },
        {
          "table": {
            "headers": [
              "Prvok plánu",
              "Obsah",
              "Overenie pred vytvorením čohokoľvek"
            ],
            "rows": [
              [
                "Kontajnery aplikácie",
                "Hlavná aplikácia, databáza, vyrovnávacia pamäť, strojové učenie a iné závislosti",
                "Jedinečné VMID, známe úlohy kontajnerov a presne jeden hlavný kontajner"
              ],
              [
                "Obrazy",
                "Priebežne aktualizovaný odkaz, architektúra a určený digest každej služby",
                "Všetky existujú, podporujú architektúru a prejdú kontrolou integrity OCI"
              ],
              [
                "Sieť",
                "Súkromný most, podsieť, pevná adresa pre každú službu a prístup LAN pre hlavný kontajner",
                "Žiadna zrážka s existujúcimi mostmi alebo podsietami a žiadna opakovaná adresa"
              ],
              [
                "Perzistencia",
                "Kontajnerové disky, hostiteľské adresáre, majitelia a zálohovanie",
                "Žiadne prekrývanie ciest, dostupné úložisko a deklarované oprávnenia"
              ],
              [
                "Citlivé údaje",
                "Heslo databázy, aplikačné kľúče a počiatočné prihlasovacie údaje",
                "Vygenerujú sa iba raz a odovzdajú sa len kontajnerom, ktoré ich používajú"
              ],
              [
                "Životný cyklus",
                "Poradie spúšťania, poradie zastavovania a kontrola stavu služby v každom kontajneri",
                "Hlavná aplikácia sa spúšťa posledná a zastavuje prvá"
              ]
            ]
          }
        }
      ]
    },
    {
      "id": "create",
      "title": "2. Vytváranie jednotlivých kontajnerov",
      "blocks": [
        {
          "steps": {
            "items": [
              {
                "title": "Rezervujte každý VMID",
                "body": "Skontroluje sa zoznam VM a kontajnerov Proxmox VE aj evidencia inštalácií. Inštalátor neprevezme existujúci kontajner a nepoužije konfiguráciu, ktorá stále patrí inej inštancii aplikácie."
              },
              {
                "title": "Pripravte každý obraz",
                "body": "Všetky obrazy sú vyriešené, stiahnuté a overené pred vytvorením prvého kontajnera."
              },
              {
                "title": "Vytvoriť každý rootfs",
                "body": "Importujú sa oficiálne metadáta OCI a pridá sa identita inštancie ProxMenux aj úloha kontajnera v aplikácii."
              },
              {
                "title": "Súkromná sieť",
                "body": "Vytvorí sa sieťový most a podsieť. Každý kontajner dostane pevnú adresu; iba hlavný kontajner navyše dostane rozhranie LAN."
              },
              {
                "title": "Perzistencia",
                "body": "Každá databáza a konfigurácia dostane svoj vlastný disk kontajnera; iba údaje určené na zdieľanie používajú adresáre hostiteľov."
              },
              {
                "title": "Prostredie",
                "body": "Zapíšu sa interné adresy služieb, zdieľané citlivé údaje a premenné služieb. Aplikácia pristupuje k svojim závislostiam cez ich vyhradené súkromné adresy."
              },
              {
                "title": "Záznam",
                "body": "Pre každý kontajner sa uloží jeho natívna konfigurácia, úpravy rootfs, ktoré treba zachovať pri aktualizáciách, a príslušnosť k aplikácii."
              }
            ]
          }
        }
      ]
    },
    {
      "id": "checks",
      "title": "3. Spustiť a skontrolovať každý kontajner",
      "intro": "Vytvorený LXC ešte neznamená pripravenú službu. Závislosti sa spúšťajú v určenom poradí a každá prejde kontrolou špecifickou pre danú službu.",
      "blocks": [
        {
          "table": {
            "headers": [
              "Služba",
              "Kontrola",
              "Čo ukazuje"
            ],
            "rows": [
              [
                "PostgreSQL",
                "<code>pg_isready</code> v CT s očakávaným hostiteľom, používateľom a databázou",
                "Server akceptuje spojenia pre nakonfigurovanú databázu"
              ],
              [
                "Redis / Valkey",
                "<code>redis-cli</code> alebo <code>valkey-cli</code> s príkazom <code>PING</code> na jeho súkromnej adrese",
                "Broker počúva a odpovedá"
              ],
              [
                "Immich strojové učenie",
                "HTTP <code>GET /ping</code>, plus kontrola zvoleného runtime GPU",
                "Služba odpovedá a požadovaná akcelerácia neprešla na CPU"
              ],
              [
                "Nextcloud",
                "<code>GET /status.php</code> s <code>installed=true</code>, <code>maintenance=false</code> a <code>needsDbUpgrade=false</code>",
                "Inicializácia ukončená bez ďalšej migrácie"
              ],
              [
                "Paperless-ngx / Tandoor",
                "HTTP na adrese LAN a skutočnom porte služby",
                "Frontend a jeho závislosti poskytujú aplikáciu"
              ],
              [
                "Hlavná aplikácia",
                "Koncový bod jeho šablóny, napríklad <code>/api/server/ping</code> v Immich",
                "Hlavná aplikácia funguje spolu so službami, od ktorých závisí"
              ]
            ]
          }
        },
        {
          "calloutWarning": {
            "title": "Spustený neznamená funkčný",
            "body": "Stav spustené znamená iba to, že proces LXC existuje. Ak služba umožňuje presnejšie overenie, použije sa kontrola príkazom exec alebo cez HTTP s časovým limitom. Ak sa niektorý kontajner zastaví alebo neprejde kontrolou, aplikácia sa neoznačí ako nainštalovaná."
          }
        }
      ]
    },
    {
      "id": "hook",
      "title": "4. Riadiaci skript závislostí (hook)",
      "blocks": [
        {
          "p": "Riadiaci skript závislostí (hook) sa nastaví iba na hlavnom kontajneri aplikácie so závislými službami. Proxmox VE ho uchováva ako snippet a spúšťa ho ako <code>hookscript</code> daného CT. Postup spúšťania aplikácie nie je zapísaný v skripte: je súčasťou samostatnej súkromnej konfigurácie inštalácie."
        },
        {
          "codeGrid": {
            "items": [
              {
                "title": "Hlavné nastavenie CT",
                "code": "hookscript: local:snippets/proxmenux-stack-dependencies.sh"
              },
              {
                "title": "Súkromná konfigurácia inštalácie (príklad)",
                "code": "/etc/pve/priv/proxmenux-stack-VMID.json\n{\n  \"schema\": 1,\n  \"stack\": \"immich\",\n  \"dependencies\": [\n    {\"vmid\": 107, \"label\": \"PostgreSQL\", \"healthcheck\": {...}},\n    {\"vmid\": 108, \"label\": \"Valkey\", \"healthcheck\": {...}},\n    {\"vmid\": 106, \"label\": \"Machine Learning\", \"healthcheck\": {...}}\n  ]\n}"
              }
            ]
          }
        },
        {
          "snippet": {
            "summary": "Kompletný zdroj proxmenux-stack-dependencies.sh",
            "pathCode": "local:snippets/proxmenux-stack-dependencies.sh",
            "snippetCode": "stackDependencyHook"
          }
        },
        {
          "p": "Skript je rovnaký pre všetky aplikácie s viacerými kontajnermi. VMID, názvy, typy kontrol a časové limity načíta zo súkromnej konfigurácie príslušnej aplikácie v <code>/etc/pve/priv/proxmenux-stack-VMID.json</code>."
        },
        {
          "steps": {
            "items": [
              {
                "title": "Proxmox VE zavolá pre-start",
                "body": "Pred spustením hlavného CT sa riadiacemu skriptu odovzdá jeho VMID a fáza životného cyklu."
              },
              {
                "title": "Zámok pre celú aplikáciu",
                "body": "<code>flock</code> na <code>/run/lock/proxmenux-stack-VMID.lock</code> zabraňuje dvom štartovým sekvenciám súčasne."
              },
              {
                "title": "Načítanie a overenie uloženej konfigurácie",
                "body": "Požaduje sa známa schéma, numerické závislosti, etikety, exec, http alebo kontrola chodu a pozitívny timeout."
              },
              {
                "title": "Závislosti v poradí",
                "body": "Každý CT musí existovať; zastavený sa spustí, už spustený sa nereštartuje."
              },
              {
                "title": "Čakanie na pripravenosť služby",
                "body": "Kontrola beží každé dve sekundy, a CT je tiež potvrdené, že stále beží."
              },
              {
                "title": "Hlavné CT začína",
                "body": "Keď je každá závislosť pripravená, pre-start končí a Proxmox VE spustí aplikáciu."
              }
            ]
          }
        },
        {
          "calloutInfo": {
            "title": "Riadiaci skript nezastavuje závislé služby",
            "body": "Fázy post-start, pre-stop a post-stop nič nevykonávajú. Po zastavení hlavného CT zostanú PostgreSQL, Redis, Valkey alebo služba strojového učenia spustené. Riadiaci skript určuje poradie spúšťania; nemení viaceré LXC na jeden proces."
          }
        },
        {
          "table": {
            "headers": [
              "Typ",
              "Príklad",
              "Neskoršie spustenia"
            ],
            "rows": [
              [
                "Aplikácia so závislými službami",
                "Immich, Nextcloud, aplikácia s PostgreSQL",
                "Riadiaci skript hlavného CT spustí závislé služby a čaká na ich pripravenosť."
              ],
              [
                "Súprava aplikácií",
                "Súprava Arr",
                "Bez hlavného kontajnera: každý LXC používa vlastné nastavenie <code>onboot</code>"
              ],
              [
                "Samostatná aplikácia",
                "Jellyfin",
                "Proxmox VE spustí daný LXC priamo"
              ]
            ]
          }
        }
      ]
    },
    {
      "id": "stack-checks",
      "title": "5. Kontrola celej aplikácie",
      "blocks": [
        {
          "list": {
            "items": [
              "Každý VMID existuje, je jedinečný a udržiava očakávanú inštančnú identitu.",
              "Každá uložená konfigurácia patrí tej istej aplikácii a zachováva úlohu kontajnera aj jeho zaznamenanú natívnu konfiguráciu.",
              "Hlavný kontajner je posledný v <code>start_order</code> a prvý v <code>stop_order</code>.",
              "Nechýba žiadny kontajner, zväzok ani úprava rootfs.",
              "Riadiaci skript odkazuje na oficiálny snippet, jeho obsah sa nezmenil a jeho konfigurácia zodpovedá postupu spúšťania aplikácie.",
              "Zistené obrazy a hodnoty digest zodpovedajú pripraveným archívom OCI.",
              "Zariadenia, profily GPU, pripojenia, citlivé údaje a adresy služieb stále zodpovedajú uloženým konfiguráciám.",
              "Keď všetky závislé služby prejdú kontrolou, kontrola na adrese hlavnej aplikácie overí spoluprácu jej kontajnerov."
            ]
          }
        }
      ]
    },
    {
      "id": "manage",
      "title": "Správa nainštalovanej aplikácie",
      "intro": "V časti <strong>Spravovať nainštalované aplikácie OCI</strong> sa z ktoréhokoľvek kontajnera aplikácie otvorí správa celej aplikácie. Ponuka obsahuje <strong>Aktualizovať všetky kontajnery aplikácie</strong>, <strong>Upraviť dodatočné cesty a zariadenia</strong>, <strong>Znova vytvoriť všetky kontajnery s uloženou konfiguráciou</strong> a <strong>Odstrániť: vymazať aplikáciu a jej kontajnery</strong>. Opätovné vytvorenie zostaví každý kontajner z pôvodného obrazu podľa uloženého digestu bez hľadania novšieho obrazu. Používa rovnaké kroky ako aktualizácia a ponúka sa pre aplikácie s viacerými kontajnermi, ktoré podporujú aktualizáciu.",
      "blocks": [
        {
          "steps": {
            "items": [
              {
                "title": "Ktorýkoľvek kontajner aplikácie",
                "body": "Uložená konfigurácia kontajnera obsahuje VMID hlavného kontajnera a úplný zoznam kontajnerov aplikácie."
              },
              {
                "title": "Aplikáciu možno znova vytvoriť",
                "body": "Overia sa identity kontajnerov, uložené konfigurácie, riadiaci skript, úpravy a možnosť zopakovať celý postup vytvorenia aplikácie."
              },
              {
                "title": "Prvé obrazy",
                "body": "Aplikácia sa nezastaví, kým sa každý digest neurčí, nestiahne a neoverí."
              },
              {
                "title": "Zastaviť kontajnery a zálohovať celú aplikáciu",
                "body": "Natívne zálohy sa vytvoria a overia pri zastavených kontajneroch, aby aplikácia a databázy zodpovedali rovnakému okamihu."
              },
              {
                "title": "Aktualizovať a skontrolovať každý kontajner",
                "body": "Pred kontrolou stavu služby v každom kontajneri sa znova použijú potrebné úpravy, sieť, pripojenia, citlivé údaje a zariadenia."
              },
              {
                "title": "Potvrdiť výsledok alebo všetko obnoviť",
                "body": "Nové konfigurácie sa uložia ako platné až po úspešnej kontrole všetkých kontajnerov. Ak niektorý zlyhá, obnovia sa všetky kontajnery aplikácie."
              }
            ]
          }
        },
        {
          "table": {
            "headers": [
              "Upraviť",
              "Čo sa zmení?",
              "Čo sa uchováva"
            ],
            "rows": [
              [
                "Extra cesty a zariadenia",
                "Pridajú sa do aplikačného kontajnera alebo sa z neho odstránia a kontajner sa reštartuje. Nič sa znova nevytvára.",
                "Údaje aplikácie, jej databázy a ostatných kontajnerov"
              ],
              [
                "Čo spúšťa rozpoznanie (Immich)",
                "Kontajner strojového učenia dostane obraz a zariadenia pre CPU alebo GPU hostiteľa. Celá aplikácia sa zastaví a aktualizuje rovnakým postupom ako pri aktualizácii.",
                "Modelová vyrovnávacia pamäť, knižnica a databáza. Ak niečo zlyhá, predchádzajúce kontajnery a predchádzajúca voľba sú obnovené"
              ]
            ]
          }
        },
        {
          "calloutWarning": {
            "title": "Aktualizácia vyžaduje možnosť znova vytvoriť celú aplikáciu",
            "body": "Ak sa postup prípravy aplikácie nedá zopakovať, aktualizácia sa odmietne ešte pred zastavením jej kontajnerov. Aplikácia zostane bežať bez zmeny."
          }
        }
      ]
    },
    {
      "id": "failure",
      "title": "6. Keď niečo zlyhá",
      "blocks": [
        {
          "p": "Ak počas inštalácie nastane chyba, zastavia a odstránia sa neúplné kontajnery vytvorené touto operáciou aj súkromný most, ak ho operácia vytvorila. Inštalácia aplikácie sa označí ako platná až po dokončení celého postupu."
        },
        {
          "p": "Aktualizácia sa vykonáva ako jeden celok: najprv sa pripravia všetky obrazy, potom sa zastavia kontajnery aplikácie. Každý kontajner sa zálohuje a jeho záloha sa overí. Až potom sa nahradia systémové disky rootfs. Kontajnery sa spúšťajú postupne a každý prejde kontrolou stavu služby. Ak niektorý zlyhá, všetky kontajnery sa obnovia z jednej sady záloh, aby databáza aj aplikácia zodpovedali rovnakému okamihu."
        },
        {
          "mermaid": {
            "chartCode": "flowchart TB\n P[\"{{prepare}}\"] --> S[\"{{stop}}\"]\n S --> B[\"{{backup}}\"]\n B --> R[\"{{replace}}\"]\n R --> H{\"{{healthy}}\"}\n H -- \"{{yes}}\" --> C[\"{{commit}}\"]\n H -- \"{{no}}\" --> X[\"{{rollback}}\"]",
            "labels": {
              "prepare": "Pripravte každý obraz",
              "stop": "Zastaviť, hlavný kontajner ako prvý",
              "backup": "Overená záloha každého CT",
              "replace": "Nahradiť rootfs",
              "healthy": "Sú všetky funkčné?",
              "yes": "Áno",
              "no": "Nie",
              "commit": "Uložiť platné konfigurácie",
              "rollback": "Obnoviť všetky kontajnery"
            }
          }
        }
      ]
    },
    {
      "id": "not-assumed",
      "title": "Čo správa aplikácie nezahŕňa",
      "blocks": [
        {
          "list": {
            "items": [
              "Súprava nainštalovaná v jednom postupe, napríklad súprava Arr, sa líši od aplikácie so závislými službami: jej kontajnery nemajú určené vzájomné poradie spúšťania.",
              "Súkromná sieť nenahrádza autentifikáciu, TLS ani konfiguráciu každej aplikácie.",
              "Záloha jedného LXC neobsahuje sieťový most, riadiaci skript ani uložené konfigurácie ostatných kontajnerov aplikácie.",
              "Prowlarr, Sonarr alebo Radarr neprijímajú žiadne indexátory, profily alebo poskytovateľov z ProxMenux."
            ]
          }
        }
      ]
    }
  ]
}