Nessie paigaldamine

Käivitage Nessie infrastruktuuril, mille valite, alates ühest masinast kuni hallatud pilveni.

Mida on vaja enne alustamist

Nessie on pnpm-monorepo, mis koosneb Node-teenustest ja kahest staatilisest paketist. Sõltumata sellest, kuidas te seda käivitate, peavad esmalt olemas olema need neli asja.

• PostgreSQL koos pgvector-iga. See ei ole valikuline ega asendatav — migratsioonid käivitavad CREATE EXTENSION vector ja loovad vector(1024) veerud. Tootmises kasutatakse pgvector/pgvector:pg17.
• Node 22 ja pnpm. Kõik Dockerfile-id kataloogis infrastructure/docker/ ehitavad node:22-slim-i peale ning hoidla fikseerib paketihalduri juurfailis package.json (pnpm@10.22.0).
• OpenAI-ga ühilduv mudeli lõpp-punkt ja selle võti. Nii agendid kui ka embeddings käivad selle kaudu. Vt allpool „Mudelipäringute seadistamine“.
• S3-ga ühilduv objektisalvestus igasuguse juurutuse jaoks, mis ei ole kohalik arendaja juurutus. Üleslaadimised kohalikule kettale on väljaspool režiimi local keelatud ja see keeld on käivitusviga, mitte piiratud käivitus — vt „Üks masin või hallatud pilv“.

Allpool kirjeldatud konteinerteekonna jaoks on vaja Dockerit ja pöördproksit; internetist kättesaadava mis tahes asja jaoks on vaja domeeni ja TLS-i.

Riistvara mahutus — minimaalne protsessor, mälu ja kettaruum antud arvu inimeste jaoks — ei ole hoidlas kusagil kirjeldatud, seega ei ütle ka see leht seda.

Komponendid ja nende koostoime

API ja worker on üks image. Need kaks paketti on tihedalt omavahel seotud, seega ehitab Dockerfile.app kogu puu ühe korra ning worker-konteiner asendab käsu käsuga node worker/dist/index.js. Režiimis local ei ole worker-konteinerit üldse: API käitab workerit oma protsessis.

Redist ei ole. Tööjärjekord ja reaalajaedastus põhinevad mõlemad Postgresel — see on otsus, mitte unustus. Google Cloudi puu kustutab Pub/Sub ja Redis moodulid samal põhjusel.

Pordid

Kohalikus arenduses on API vaikimisi pordil 5454 ja admin pordil 5455. Väljavõte võib võtta oma paari, määrates NESSIE_API_PORT ja NESSIE_ADMIN_PORT keskkonnas või hoidla .env-failis. Iga hoidla tööriist, sealhulgas brauseritesti sviidid, loeb samu kahte väärtust. Valige paar enne käivitamist ja hoidke seda: töötava teenuse teisele pordile viimine jätab admini rääkima vale API-ga.

Tootmine on teine asi ja selle reegel ei muutu. API konteiner kuulab sisemiselt pordil 5554 (fikseeritud NESSIE_API_PORT-iga) ja push-vahendaja pordil 5556; mõlemad on pöördproksi taga.

Ühe masina käitamine arenduseks

Hoidlas on Compose-fail, milles on ainult andmebaas — see on kõik, mida kohalik tsükkel vajab.

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

See konteiner avaldab Postgresi pordil 55432, kasutaja, parool ja andmebaas on kõik nimega nessie. Ühendusstring lisatakse hoidla juurkataloogis asuvasse faili .env — API arendusskript loeb seda — seejärel rakendatakse migratsioonid ja ehitatakse worker üks kord, sest kohalikus režiimis laeb API workeri oma ehitatud dist-kataloogist:

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

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

pnpm dev käivitab API ja admini paralleelselt koos kuumlaadimisega pordil 5454 ja 5455. Kontrollige, et API vastas päringule GET /api/health.

Postgres ja pgvector-nõue

Kolm laiendust luuakse migratsioonidega endiga — vector, pg_trgm ja pgcrypto — seega peab roll, mis neid käivitab, tohtima laiendusi luua. Hallatud Postgresi puhul on see esimene asi, mida kontrollida.

Vektori laius on osa skeemist, mitte seadistus. thoughts.embedding, thought_recalls.query_embedding ja knowledge_page_chunks.embedding on vector(N) veerud ning N on märgitud ühe korra konstandina EMBEDDING_DIMENSIONS failis packages/schemas/src/embedding.ts — praegu 1024, tootmises kasutatava embeddingmudeli algne laius. Iga embed-päring saadab selle laiuse, nii et pakkuja, mis vastaks mõnel muul laiusel, ebaõnnestub valjusti, selle asemel et kirjutada vektoreid, mida andmebaas ei aktsepteeri. Üleminek teise laiusega embeddingmudelile nõuab selle konstandi muutmist, migratsiooni, mis kirjutab need kolm veergu uuesti, ning vektorite uuesti arvutamist: erineva laiusega vektoreid ei saa teisendada, seega migratsioon tühjendab need, selle asemel et neid lõigata.

Kui käitate Nessie’t teiste rakenduste kõrval jagatud Docker-võrgus, andke selle andmebaasikonteinerile eraldi nimi. Projekti enda Compose-teenus on nimega nessie-postgres ja mitte kunagi postgres, sest teenuse nimi muutub jagatud võrgus DNS-aliasiks ning kokkupõrge paneb postgres:5432 vaheldumisi kahe andmebaasi vahel.

Seadistus

Käituskonfiguratsioon on kihiline: fail nessie.config.json on API-le ja workerile ette nähtud kirjutuskaitstult ning keskkonnamuutujad lähevad selle peale. Nende kahe vastavuse määrab ConfigEnvMap paketis packages/config, mis on autoriteetne loend.

NESSIE_MODE valib juurutuse kuju: local (vaikimisi ja arendaja tee), hosted või selfHosted — mida isemajutatud paigaldus seab. See keelab arendaja sisselogimise ja nõuab CORS-lubade loendit.

Need on seadistused, ilma milleta selfHosted juurutus ei käivitu või ei tööta:

infrastructure/compose/.env.prod.example näitab kõigi nende täpset kuju, valikuliste plokkidega — objektisalvestus, saladuste hoidla, SSO ja ühendatud post — kommenteeritult kohal. Täielik loend, kaasa arvatud iga valikuline seadistus, on docs/deployment/configuration.md.

Juurutamine Docker Composega

Kopeerige .env.prod.example failiks .env faili docker-compose.prod.yml kõrvale ja täitke see, seejärel käivitage andmebaas, ehitage, migreerige ja käivitage teenused. Järjekord on oluline: migratsioonid ja algandmed käivitatakse juba töötava andmebaasi vastu, enne kui ükski teenus teenindab.

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

Tootmise Dockerfile-id käivitavad iga paketi lindi enne selle ehitamist, seega on lindi tõrge ehitusviga.

Reconcile-samm on kohustuslik

reconcile lisab iga organisatsiooni vaikimisi poliitikareeglid ning täiendab kaitstud MCP ja isikliku assistendi tööriistaõigused. API tegi seda varem igal replikal käivitusel; nüüd ta ühendub, kuulab ja ei tee midagi muud, seega ilma selle sammuta pole esimesel organisatsioonil poliitikareegleid ning iga agendi sidumine keelatakse. See on idempotentne, seega on selle käivitamine igal juurutusel ohutu — ja käsitsi rakendatud uuendus peab selle samuti käivitama.

Esimese omaniku konto

Värske selfHosted paigaldus ei sisalda ühtegi kasutajat, seega API loob ühekordse käivitustõendi ja logib seadistamise URL-i. Tõend elab Postgresis, mitte protsessis, nii et kõik replikad on selle osas ühel meelel.

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

Avage https://<your-admin-host>/bootstrap?token=<token> ja looge omaniku konto. Tõend aegub 15 minuti pärast; uue saamiseks taaskäivitage API teenus.

Kui seadistate SSO, ei ole käivitussammu üldse. Käivitusrežiim on välja lülitatud kohe, kui väline autentimisteenus on lubatud — muidu röövib see sisselogimisvaate — ning esimene isik, kes SSO kaudu sisse logib, loob vaikemeeskonna ja saab selle omanikuks.

Mudelipäringute seadistamine

Vestlus on OpenAI-ga ühilduv. NESSIE_MODEL_BASE_URL on lõpp-punkt, NESSIE_MODEL_API_KEY kandja-võti ja NESSIE_MODEL_PROVIDER nimetab adapteri — Nessie kompileerib adapterid openai, kimi ja deepseek jaoks ning pöördub kõigi muude poole üldise OpenAI-ga ühilduva ühenduse kaudu. NESSIE_MODEL_NAME määrab juurutuse vaikimisi mudeli, millest üksiku agendi enda mudelivalik on siiski prioriteetsem.

Embeddings suunatakse eraldi, sest vestlusteenuse pakkuja ei pruugi neid üldse pakkuda — näiteks DeepSeek’il ei ole embeddingu lõpp-punkti. Iga määramata NESSIE_EMBEDDING_* väli pärib vestlusteenuse pakkuja, nii et juurutus, mis ühtegi neist ei määra, teeb embeddingud vestluse lõpp-punkti kaudu. Kui vestlusteenuse pakkuja ei suuda embeddingud teha, määrake NESSIE_EMBEDDING_PROVIDER ja NESSIE_EMBEDDING_MODEL ning proksi puhul, mis suunab teenuse järgi, ka teenuse segment. Vale seadistus ei anna vea valjusti, vaid ebaõnnestub vaikselt: mälu meenutamine ja teadmusbaasi otsing langevad sõnalisele kanalile ja jätkavad, logides samal ajal kb_search: query embedding failed.

Nessie enda kulude arvestus — organisatsioonipõhine žetoonide register ja eelarvepiirang — ei sõltu sellest, millise lõpp-punktini te suunate, ning töötab samamoodi, olenemata sellest, kas allkirjastatud atribuutimine kõne põhjal on seadistatud või mitte.

Sisselogimine

Nessie autentib inimesi UnlikeOtherAI kaudu, mis haldab ka organisatsiooni ja meeskonna struktuuri. Admini sisselogimisvaates on üks nupp „Logi sisse / Registreeru“.

Integratsioon on konfiguratsiooni-JWT-voog, mitte standardne OIDC: API pakub allkirjastatud RS256 konfiguratsioonidokumenti aadressil GET /api/auth/sso/config ja vastavat JWKS-i aadressil GET /.well-known/jwks.json, mõlemad API hostil. Seadistamine on ühekordne jada — genereerige RSA-2048 võtmepaar ja määrake UOA_CONFIG_JWT_PRIVATE_KEY_B64, UOA_CONFIG_JWT_KID, UOA_DOMAIN, UOA_CONFIG_URL, UOA_JWKS_URL, UOA_REDIRECT_URL ja UOA_CONTACT_EMAIL; nupule klõpsatakse üks kord, mis loob integratsioonitaotluse; taotlus kiidetakse heaks, mis saadab kontaktaadressile ühekordse lingi koos kliendisaladusega; seejärel määratakse UOA_CLIENT_SECRET ja API taaskäivitatakse. kid peab olema domeenis unikaalne.

Domeeni taga ja TLS-iga

Juurutus teenindab kolme nime: avalikku veebisaiti, adminit ja API-t. Admini ja API päritolud ei ole omavahel asendatavad. Dockerfile.admin lisab VITE_API_BASE_URL paketti ehitamise ajal, seega peab iga ehitatud admini artefakt — kaasa arvatud töölauarakendus, mis seda sisaldab — olema ehitatud API päritolu vastu. Kui ehitate selle admini enda päritolu vastu, lahendub /api/auth/providers admini HTML-kestaks ning sisselogimine jääb seisma tekstiga „Teenusepakkujate laadimine...“.

Tootmises lõpetab TLS Caddy, mis hangib hostinimede kaupa sertifikaadid HTTP-01 kaudu ega vaja selleks DNS-teenusepakkuja pistikprogrammi. Suunake proksi admini ja veebi konteineritele pordil 80 ning API-le selle sisemisel pordil.

Määrake NESSIE_API_TRUSTED_PROXY_HOPS API ees olevate proksite arvuks — üks ühe pöördproksi taga. Vaikimisi on 0, mis ignoreerib X-Forwarded-For-i täielikult. See on üks otsus kahe tagajärjega: sama arv määrab ka autentimise päringupiirangute võtmed, nii et liiga madal väärtus paneb kõik kliendid jagama proksi ämbrit ja liiga kõrge väärtus lubab kliendil oma aadressi võltsida. Eksige madalale ja mõõtke.

Iga organisatsiooni ja meeskonna teenindamine oma alamdomeenil on võimalik ja vaikimisi väljas. Seda reguleerib NESSIE_TEAM_HOST_BASE_DOMAIN — kui see on määramata, ei suunata organisatsioone hostinime järgi üldse — ning sertifikaadi väljastamise värav NESSIE_TLS_CHECK_KEY keeldub kõigest, kui see on määramata. See on õige vaikeväärtus juurutusele, mis seda funktsiooni ei kasuta.

Tervisekontrollid

SIGTERM-i korral API tühjendab ennast, selle asemel et surra sinnasamasse. NESSIE_SHUTDOWN_TIMEOUT_MS piirab tühjendamist ja vaikimisi on see 25 sekundit; hoidke see väiksem kui orkestraatori konteinerile antud lõpetamisaeg, muidu tapab käituskeskkond protsessi enne ning tühjendamine ei too mitte midagi kasu.

Uuendamine

Uuendus on prisma migrate deploy olemasoleva andmebaasi vastu, seejärel algandmed ja seejärel reconcile. Samad neli käsku, mis esimesel juurutusel.

Teekonda on testitud sellele marsruudile, mida isemajutaja tegelikult järgib, mitte värske andmebaasi vastu: CI taastab hetktõmmise, mis on võetud kahekümne migratsiooni kaugusel, migreerib selle praeguse tipuni, valideerib skeemi ja käivitab põhitabelite üle suitsukontrolli. Iga väljalase selles viimases aknas on tõestatud uuenduse allikas. Migratsioonikaustad on pärast kinnitamist muutumatud ning lint ebaõnnestub ehituse, kui mõnda neist nimetatakse ümber, nummerdatakse ümber, kustutatakse või muudetakse — kõik need neli katkestavad migrate deploy-i andmebaasi jaoks, mis on juba salvestanud vana rea.

Üks ebaõnnestunud migratsioon blokeerib kõik sellele järgnevad juurutused. migrate deploy peatub esimese tõrke juures ja keeldub kõigist hilisematest migratsioonidest veakoodiga P3009, nii et paigaldus jääb vanale väljalasttele, kuni keegi selle käsitsi puhastab. Projekti enda tootmine veetis ühe päeva, lükates iga juurutuse nii tagasi. Ühe puhastamine tähendab kinnitamist, et ebaõnnestunud migratsioon tõesti tagasi võeti — ükski objekt, mida see loob, ei tohi eksisteerida ja kõik, mida see muudab, peab olema algsel kujul — ning alles siis märkida see tagasi võetuks. Pooleldi rakendatud migratsioon ei ole kandidaat.

Varundamist ja taastamist isemajutatud Compose-juurutusele ei ole hoidlas dokumenteeritud, seega ei kirjelda see leht selle protseduuri.

Üks masin või hallatud pilv

Üheserverilise Docker Compose’i tee, mis on kirjeldatud ülal, on see, mis on tõestatud: just seda kasutab projekti enda tootmine ühel serveril, kus andmebaas, objektisalvestus, API, worker, admin ja sait töötavad konteineritena jagatud pöördproksi taga.

Mitme masina peale skaleerimine muudab kolme asja ja need kõik on jõustatud, mitte soovitatud. Väljaspool režiimi local käitab Nessie API-d ja workerit eraldi protsessidena ja mitme koopiana, seega on keelatud iga võimekus, mis eeldab, et üks protsess omab masina ketast: failisüsteemi objektisalvestus (käivitusviga), täitekeskkonna mallid koos docker pakkujaga (mõjutud ja ebaõnnestuvad valjusti) ning sisseehitatud tööriistad file_read, file_write ja file_glob (ebaõnnestunud tööriistatulemus, mille agent näeb). Iga keeldumine nimetab seadistuse, režiimi ja selle, mida selle asemel kasutada.

Hallatud pilve jaoks sisaldab hoidla Terraform-puud kataloogis infrastructure/terraform/, mis on suunatud Google Cloudile: API Cloud Run teenusena vähemalt ühe instantsiga — see hoiab püsivat Postgresi LISTEN-klienti ja käitab hooldustsükleid, seega nulli skaleerimine peatab reaalajaedastuse; worker Cloud Run worker poolina, sest see ei seo porti ja teenus ei muutuks kunagi valmis; migreerimistöö, mis kontrollib iga väljarullimist; Cloud SQL for PostgreSQL 17 ning GCS-i ämber, millele pääsetakse ligi S3-ga ühilduva taustaosa kaudu.

See tee on kirjutatud, mitte läbi kõnnitud. Hoidla ütleb seda otse ja seda ütleb ka see leht: Google Cloudi projekti selleks ei ole, puu midagi pole plaanitud ega rakendatud reaalse projekti vastu, mitmeosalise üleslaadimise tee GCS-i on testimata reaalse ämbri vastu, worker poolide ressursitüüp on valideerimata ning seal olev usaldatud proksi hüppearv on kohahoidja, mida tuleb mõõta, mitte mõõtmise tulemus. Admin ja avalik sait ei ole seal üldse modelleeritud. Käsitlege seda lähtepunktina, mille te ise kontrollite, mitte toetatud juurutusena.

Juurutuse andmete asukoht — see, mida tarkvara hoiab ja mida see tahtlikult ei hoia — on eraldi lehel: ELis loodud ja kus teie andmed asuvad.