Inštalácia Nessie

Spustite Nessie na infraštruktúre, ktorú si vyberiete, od jedného počítača až po spravovanú cloudovú službu.

Čo potrebujete, než začnete

Nessie je pnpm monorepo Node služieb a dvoch statických balíkov. Bez ohľadu na to, ako ho spustíte, musia najprv existovať tieto štyri veci.

• PostgreSQL s pgvector. Nie je voliteľný a nedá sa nahradiť iným. Migrácie spúšťajú CREATE EXTENSION vector a vytvárajú stĺpce vector(1024). Produkcia beží na pgvector/pgvector:pg17.
• Node 22 a pnpm. Každý Dockerfile v infrastructure/docker/ sa zostavuje na node:22-slim a repozitár pripína správcu balíkov v koreňovom package.json (pnpm@10.22.0).
• Endpoint modelu kompatibilný s OpenAI a kľúč k nemu. Agenti aj embeddingy idú cez neho. Pozrite si „Konfigurácia inferencie“ nižšie.
• Objektové úložisko kompatibilné s S3 pre každé nasadenie, ktoré nie je lokálne vývojárske. Nahrávanie na lokálny disk je mimo režimu local odmietnuté a toto odmietnutie je chyba pri štarte, nie núdzový štart — pozrite si „Jeden stroj, alebo spravovaný cloud“.

Docker a reverzný proxy sú potrebné pre cestu s kontajnermi opísanú nižšie a doména s TLS pre všetko, čo je dostupné z internetu.

Veľkosť hardvéru — minimálny procesor, pamäť a disk pre dané množstvo ľudí — nie je nikde v repozitári uvedená, preto ju ani táto stránka neuvádza.

Komponenty a ako do seba zapadajú

API a worker sú jeden obraz. Oba balíky sú úzko prepojené, takže Dockerfile.app zostaví celý tím raz a kontajner workera prepíše príkaz na node worker/dist/index.js. V režime local nemá worker vlastný kontajner: API spúšťa worker vo vlastnom procese.

Redis tu nie je. Fronta úloh aj realtime prenos sú založené na Postgrese — ide o rozhodnutie, nie o opomenutie. Stromy pre Google Cloud mažú svoje moduly Pub/Sub a Redis z rovnakého dôvodu.

Porty

Pri lokálnom vývoji je API na porte 5454 a admin na 5455. Pracovná kópia si môže zvoliť vlastnú dvojicu nastavením NESSIE_API_PORT a NESSIE_ADMIN_PORT, v prostredí alebo v súbore .env repozitára; každý nástroj v repozitári vrátane testovacích sád prehliadača číta tie isté dve hodnoty. Dvojicu vyberte pred spustením a držte sa jej: ak presuniete bežiacu službu na iný port, admin bude komunikovať s nesprávnym API.

Produkcia je iná vec a toto pravidlo sa jej netýka. Kontajner API počúva interne na 5554 (pevne nastavené cez NESSIE_API_PORT) a push relé na 5556, obe za reverzným proxy.

Spustenie na jednom stroji pre vývoj

Repozitár obsahuje súbor Compose iba s databázou, a to je všetko, čo lokálna slučka potrebuje.

pnpm install
docker compose -f infrastructure/compose/docker-compose.yml up -d postgres

Tento kontajner sprístupňuje Postgres na porte 55432 s používateľom, heslom a databázou, ktoré sa všetky volajú nessie. Reťazec pripojenia vložte do súboru .env v koreni repozitára — jeho vývojársky skript ho číta — potom raz aplikujte migrácie a zostavte worker, pretože v režime local API načítava worker z jeho zostaveného dist:

DATABASE_URL=postgresql://nessie:nessie@localhost:55432/nessie

pnpm --filter @nessie/api prisma:migrate:deploy
pnpm --filter @nessie/worker build
pnpm dev

pnpm dev spúšťa API a admin paralelne s hot reloadom, na portoch 5454 a 5455. Overte, že API odpovedá na GET /api/health.

Postgres a požiadavka pgvector

Tri rozšírenia vytvárajú samotné migrácie — vector, pg_trgm a pgcrypto — takže rola, ktorá ich spúšťa, musí mať právo vytvárať rozšírenia. Pri spravovanom Postgrese je to prvé, čo treba skontrolovať.

Šírka vektorov je súčasťou schémy, nie nastavením. thoughts.embedding, thought_recalls.query_embedding a knowledge_page_chunks.embedding sú stĺpce vector(N) a N je uvedené raz ako EMBEDDING_DIMENSIONS v packages/schemas/src/embedding.ts — momentálne 1024, natívna šírka embedding modelu, ktorý produkcia používa. Každá požiadavka na embedding posiela túto šírku, takže poskytovateľ, ktorý by odpovedal inou šírkou, zlyhá nahlas namiesto toho, aby zapisoval vektory, ktoré databáza odmietne. Prechod na embedding model inej šírky znamená upraviť túto konštantu, napísať migráciu, ktorá zmení typ troch stĺpcov, a vytvoriť embeddingy nanovo: vektory rôznych šírok sa nedajú previesť, takže migrácia ich vynuluje namiesto toho, aby ich orezala.

Ak Nessie beží vedľa iných aplikácií v spoločnej Docker sieti, dajte jeho databázovému kontajneru iný názov. Služba projektu Compose sa volá nessie-postgres a nikdy postgres, pretože názov služby sa v spoločnej sieti stáva DNS aliasom a kolízia spôsobí, že postgres:5432 sa bude striedať medzi dvoma databázami.

Konfigurácia

Konfigurácia za behu je vrstvená: súbor nessie.config.json pripojený len na čítanie do API a workera, nad ktorým sú premenné prostredia. Mapovanie medzi nimi je ConfigEnvMap v packages/config a je to autoritatívny zoznam.

NESSIE_MODE určuje tvar nasadenia: local (predvolený a vývojársky režim), hosted alebo selfHosted — ten nastavuje inštalácia prevádzkovaná vlastnými silami. Vypína vývojárske prihlasovanie a vyžaduje zoznam povolených CORS.

Toto sú nastavenia, bez ktorých sa nasadenie selfHosted nespustí alebo nebude fungovať:

infrastructure/compose/.env.prod.example má presný tvar všetkých z nich, s voliteľnými blokmi — objektové úložisko, trezor tajomstiev, SSO, pripojená pošta — zakomentovanými na mieste. Úplný katalóg vrátane každého voliteľného nastavenia je v docs/deployment/configuration.md.

Nasadenie cez Docker Compose

Skopírujte .env.prod.example do .env vedľa docker-compose.prod.yml a vyplňte ho. Potom spustite databázu, zostavte, aplikujte migrácie a spustite služby. Poradie je dôležité: migrácie a seed dáta bežia nad databázou, ktorá je už spustená, skôr než čokoľvek začne obsluhovať.

COMPOSE="docker compose -f infrastructure/compose/docker-compose.prod.yml"

bash infrastructure/compose/ensure-encryption-key-ring.sh infrastructure/compose/.env
$COMPOSE up -d nessie-postgres
$COMPOSE build nessie-api nessie-admin nessie-web
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api prisma:migrate:deploy
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api seed:connectors
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api seed:apps
$COMPOSE run --rm --no-deps nessie-api pnpm --filter @nessie/api reconcile
$COMPOSE up -d

Produkčné Dockerfile-y pred zostavením každého balíka spustia jeho lint, takže zlyhanie lintu je zlyhanie zostavenia.

Krok reconcile nie je voliteľný

reconcile vytvorí predvolené pravidlá politiky každej organizácie a spätne doplní oprávnenia pre chránené MCP nástroje a nástroje osobného asistenta. API to kedysi robilo pri štarte na každej replike; teraz sa len pripojí, začne počúvať a nič ďalšie nerobí. Preto bez tohto kroku prvá organizácia nemá žiadne pravidlá politiky a každé pripojenie agenta je zamietnuté. Krok je idempotentný, takže spúšťanie pri každom nasadení nič nestojí — a upgrade aplikovaný ručne ho musí spustiť tiež.

Prvý účet vlastníka

Čerstvá inštalácia selfHosted nemá žiadnych používateľov, takže API vygeneruje jednorazový bootstrap token a zaznamená URL nastavenia. Token žije v Postgrese, nie v procese, takže sa všetky repliky zhodujú na jeho hodnote.

docker compose -f infrastructure/compose/docker-compose.prod.yml logs nessie-api 2>&1 | grep bootstrap

Otvorte https://<your-admin-host>/bootstrap?token=<token> a vytvorte účet vlastníka. Token expiruje po 15 minútach; ak potrebujete nový, reštartujte službu API.

Ak nastavíte SSO, žiadny bootstrap krok neexistuje. Bootstrap režim je potlačený hneď, ako sa zapne externý poskytovateľ autentifikácie — inak by prevzal prihlasovaciu obrazovku — a prvá osoba, ktorá sa prihlási cez SSO, vytvorí predvolený tím a stane sa jeho vlastníkom.

Konfigurácia inferencie

Chat je kompatibilný s OpenAI. NESSIE_MODEL_BASE_URL je endpoint, NESSIE_MODEL_API_KEY bearer token a NESSIE_MODEL_PROVIDER pomenúva adaptér. Nessie obsahuje adaptéry pre openai, kimi a deepseek a všetko ostatné prechádza cez všeobecný konektor kompatibilný s OpenAI. NESSIE_MODEL_NAME nastavuje predvolený model nasadenia; výber modelu u jednotlivého agenta má aj tak prednosť.

Embeddingy sa smerujú samostatne, pretože chatový poskytovateľ ich nemusí poskytovať vôbec — DeepSeek napríklad nemá endpoint pre embeddingy. Každé nenastavené pole NESSIE_EMBEDDING_* preberie chatového poskytovateľa, takže nasadenie, ktoré nenastaví žiadne, embeduje cez chatový endpoint. Ak chatový poskytovateľ embedovať nemôže, nastavte NESSIE_EMBEDDING_PROVIDER, NESSIE_EMBEDDING_MODEL a na proxy, ktorá smeruje podľa služby, aj segment služby. Chyba sa tu prejaví potichu, nie nahlas: pamäťové vyhľadávanie a vyhľadávanie v znalostnej báze prejdú na lexikálny kanál a pokračujú ďalej, pričom zapisujú kb_search: query embedding failed.

Vlastné účtovanie spotreby Nessie — tokenový účet pre každú organizáciu a brána rozpočtu — nezávisí od toho, na aký endpoint ho nasmerujete, a funguje rovnako, či je podpisovanie atribúcie volaní nastavené, alebo nie.

Prihlasovanie

Nessie autentifikuje ľudí cez UnlikeOtherAI, ktorý spravuje aj štruktúru organizácií a tímov. Prihlasovacia stránka administrácie zobrazuje jediné tlačidlo „Login / Register“.

Integrácia je postavená na konfiguračnom JWT toku, nie na štandardnom OIDC: API na GET /api/auth/sso/config podáva podpísaný konfiguračný dokument RS256 a zodpovedajúci JWKS na GET /.well-known/jwks.json, obe na hostiteľovi API. Nastavenie je jednorazová postupnosť: vygenerujte pár kľúčov RSA-2048 a nastavte UOA_CONFIG_JWT_PRIVATE_KEY_B64, UOA_CONFIG_JWT_KID, UOA_DOMAIN, UOA_CONFIG_URL, UOA_JWKS_URL, UOA_REDIRECT_URL a UOA_CONTACT_EMAIL. Raz kliknite na tlačidlo, čím vytvoríte žiadosť o integráciu. Nechajte ju schváliť, čo na kontaktnú adresu pošle jednorazový odkaz s klientskym tajomstvom. Nastavte UOA_CLIENT_SECRET a reštartujte API. kid musí byť pre každú doménu jedinečný.

Umiestnenie za doménu s TLS

Nasadenie obsluhuje tri názvy: verejnú stránku, admin a API. Zdroje admina a API nie sú zameniteľné. Dockerfile.admin zapečie VITE_API_BASE_URL do balíka v čase zostavenia, takže každý zostavený artefakt administrácie — vrátane desktopového zostavenia, ktoré ho obsahuje — musí byť zostavený voči zdroju API. Ak ho zostavíte voči vlastnému zdroju administrácie, /api/auth/providers sa vyhodnotí na HTML obal administrácie a prihlasovanie uviazne na „Loading providers...“.

Produkcia ukončuje TLS v Caddy, ktorý získava certifikáty pre jednotlivé názvy hostiteľov cez HTTP-01 a na to nepotrebuje plugin DNS poskytovateľa. Nasmerujte proxy na kontajnery admina a webu na porte 80 a na API na jeho internom porte.

Nastavte NESSIE_API_TRUSTED_PROXY_HOPS na počet proxy pred API — 1 za jedným reverzným proxy. Predvolená hodnota je 0, ktorá úplne ignoruje X-Forwarded-For. Je to jedno rozhodnutie s dvoma dôsledkami: rovnako určuje, ako sa kľúčujú limity počtu autentifikačných požiadaviek. Pri nízkej hodnote všetci klienti zdieľajú limit proxy, pri vysokej si môže klient sfalšovať vlastnú adresu. Radšej nastavte nízko a potom overte meraním.

Obsluhovať každú organizáciu a tím na vlastnej subdoméne je možné a predvolene vypnuté. Riadi to NESSIE_TEAM_HOST_BASE_DOMAIN: ak nie je nastavené, nájomcovia sa podľa názvu hostiteľa vôbec nesmerujú. Brána vydávania certifikátov NESSIE_TLS_CHECK_KEY zase odmietne všetko, kým nie je nastavená — čo je správna predvolená hodnota pre nasadenie, ktoré túto funkciu nepoužíva.

Kontroly stavu

Pri SIGTERM API dokončí rozpracovanú prácu namiesto toho, aby zomrelo na mieste. NESSIE_SHUTDOWN_TIMEOUT_MS ohraničuje toto dokončenie a predvolene je 25 sekúnd. Udržte ho pod ochrannou lehotou, ktorú orchestrátor dá kontajneru, inak runtime proces ukončí skôr a dokončenie nič neprinesie.

Aktualizácia

Aktualizácia je prisma migrate deploy nad existujúcou databázou, potom seed dáta a potom reconcile. Sú to tie isté štyri príkazy ako pri prvom nasadení.

Postup je otestovaný na ceste, ktorou skutočne ide používateľ prevádzkujúci Nessie sám, a nie na čerstvej databáze: CI obnoví snímku zachytenú dvadsať migrácií pozadu, migruje ju na aktuálnu najnovšiu verziu, overí schému a spustí rýchlu kontrolu nad základnými tabuľkami. Každé vydanie v tomto posuvnom okne je overený zdroj upgradu. Priečinky migrácií sú po commitnutí nemenné a krok lintu zlyhá zostavenie, ak sa niektorý premenuje, prečísluje, zmaže alebo zmení, lebo všetky štyri rozbijú migrate deploy pre databázu, ktorá už zaznamenala starý riadok.

Jedna zlyhaná migrácia zablokuje každé nasadenie po nej. migrate deploy sa zastaví na prvom zlyhaní a odmietne každú neskoršiu migráciu s P3009, takže inštalácia zostáva na starom vydaní, kým ju niekto ručne neuvoľní. Produkcia projektu sama strávila jeden deň odmietaním každého nasadenia takýmto spôsobom. Uvoľnenie vyžaduje potvrdiť, že zlyhaná migrácia sa naozaj vrátila späť — žiadny z objektov, ktoré vytvára, by nemal existovať, a všetko, čo mení, by malo mať pôvodný tvar — a až potom ju označiť ako vrátenú späť. Migrácia, ktorá sa aplikovala len čiastočne, nie je kandidát.

Zálohovanie a obnova pre nasadenie Docker Compose prevádzkované vlastnými silami nie sú v repozitári zdokumentované, preto táto stránka neopisuje postup pre ne.

Jeden stroj, alebo spravovaný cloud

Cesta s jediným hostiteľom a Docker Compose, popísaná vyššie, je tá overená: na nej beží vlastná produkcia projektu na jedinom serveri, s databázou, objektovým úložiskom, API, workerom, adminom a stránkou ako kontajnermi za zdieľaným reverzným proxy.

Škálovanie nad jeden stroj mení tri veci a všetky sú vynucované, nie len odporúčané. Mimo režimu local Nessie spúšťa API a worker ako oddelené procesy a ako viac kópií každého z nich, takže každá schopnosť, ktorá predpokladá, že jeden proces vlastní disk stroja, je odmietnutá: úložisko objektov na súborovom systéme (chyba pri štarte), šablóny prostredia na vykonávanie s poskytovateľom docker (neaktívne a pri zabezpečovaní zlyhajú nahlas) a vstavané nástroje file_read, file_write a file_glob (neúspešný výsledok nástroja, ktorý agent môže prečítať). Každé odmietnutie pomenuje nastavenie, režim a to, čo použiť namiesto toho.

Pre spravovaný cloud repozitár obsahuje strom Terraform v infrastructure/terraform/ zameraný na Google Cloud: API ako službu Cloud Run s minimom jednej inštancie — drží trvalého klienta Postgres LISTEN a spúšťa údržbové úlohy, takže škálovanie na nulu zastaví realtime doručovanie — worker ako worker pool Cloud Run, pretože nepočúva na porte a Service by nikdy nebol pripravený, úlohu migrácie, ktorá podmieňuje každé nasadenie, Cloud SQL pre PostgreSQL 17 a bucket GCS, ku ktorému sa pristupuje cez backend kompatibilný s S3.

Táto cesta je napísaná, nie vyskúšaná. Repozitár to hovorí jasne a táto stránka tiež: pre ňu neexistuje projekt Google Cloud, nič v strome nebolo naplánované ani aplikované proti skutočnému projektu, cesta multipart nahrávania do GCS nebola testovaná na skutočnom bucketu, typ zdroja worker pool nie je overený a počet hopov dôveryhodného proxy v nej je zástupná hodnota, ktorú treba ešte zmerať, nie nameraná hodnota. Administrácia a verejná stránka tam nie sú vôbec modelované. Berte to ako východisko, ktoré si overíte, nie ako podporované nasadenie.

Kde žijú dáta nasadenia, čo softvér drží a čo úmyselne nedrží, je na samostatnej stránke: Vyrobené v EÚ a kde sú vaše dáta.