nanobot-runtime/projects/ai/artifacts/librechat-podman/README.md

LibreChat — Podman (rootless) + systemd Quadlet

Náhrada OpenWebUI. Minimal stack: api + mongodb (bez RAG/vectordb/admin-panel, kvůli RAM). Volitelně meilisearch pro fulltext search (SEARCH=true).

Zdroje:

• https://www.librechat.ai/docs/local/docker
• https://www.librechat.ai/docs/remote/docker_linux
• https://www.librechat.ai/docs/configuration/dotenv
• Quadlet: https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html

Instalace (rootless, user services)

1. Předpoklady: podman ≥ 4.4 (ideálně 5.x), uživatelský účet na serveru.

2. Linger, aby user services běžely bez loginu:

   loginctl enable-linger <user>
   

3. Adresář s konfigem:

   mkdir -p ~/librechat
   # .env ze šablony z repa LibreChat (.env.example)
   cp .env.example ~/librechat/.env
   

   V ~/librechat/.env nastavit:

   • MONGO_URI=mongodb://librechat-mongodb:27017/LibreChat (DNS jméno kontejneru v quadlet síti; default v šabloně je 127.0.0.1)
   • MEILI_HOST=http://librechat-meilisearch:7700
   • Trvalé secrets — vygenerovat (např. openssl rand -hex 32): CREDS_KEY (64 hex znaků), CREDS_IV (32 hex), JWT_SECRET, JWT_REFRESH_SECRET (jinak se vygenerují do /app/data/.env.temp — funguje, ale po ztrátě volume jsou session/šifrované záznamy nenávratně pryč)
   • SEARCH=true jen při provozu meilisearch + MEILI_MASTER_KEY

4. Quadlet unity nakopírovat do ~/.config/containers/systemd/user/:

   cp librechat.network librechat-mongodb.container librechat.container \
      ~/.config/containers/systemd/user/
   # volitelně: cp librechat-meilisearch.container ~/.config/containers/systemd/user/
   

   Cestu k .env v unitách případně upravit (výchozí %h/librechat/.env = ~/.config/... patřičně).

5. Start:

   systemctl --user daemon-reload
   systemctl --user enable --now librechat-mongodb.service
   systemctl --user enable --now librechat.service
   # volitelně: systemctl --user enable --now librechat-meilisearch.service
   

6. UI na http://<host>:3080. První registrace = admin účet single-tenant deploymentu. Po vytvoření účtu v .env doplnit ALLOW_REGISTRATION=false a restart (systemctl --user restart librechat.service).

Volitelné doplňky

• librechat.yaml (custom endpointy — Ollama/litellm proxy na nvidia.hell, preset modelů atd.): soubor do ~/librechat/librechat.yaml + v librechat.container odkomentovat Volume řádek. Validace YAML fail-fast.
• RAG (vectordb + rag_api): až když bude potřeba, ~1 GB RAM navíc.
• Aktualizace: podman auto-update (quadlet unity mají default label), nebo ručně podman pull registry.librechat.ai/danny-avila/librechat-dev:latest
  • systemctl --user restart librechat.service.

Provoz / debugging

• Logy: journalctl --user -u librechat.service (nebo -u librechat-mongodb)
• Stav kontejnerů: podman ps
• Port konflikt: PublishPort v librechat.container (default 3080:3080)

Designová rozhodnutí

• Quadlet místo podman generate systemd (deprecated) a místo systemd-oneshot nad podman compose (systemd neví o kontejnerech, špatný restart/watchdog).
• Společná quadlet síť (librechat.network) — DNS mezi api a mongo přes ContainerName, žádné porty mimo host kromě 3080.
• Rootless + linger — žádný root daemon na hostu; port 3080 > 1024, žádný konflikt s privileged porty.
• Bind-mount .env do /app/.env — stejně jako upstream compose (aplikace čte /app/.env za běhu, env_file samotný nestačí).
• Data v pojmenovaných volumech: librechat-data (/app/data — session, temp credentials), librechat-mongodb-data (/data/db). Záloha: podman volume export.