Nessie इंस्टॉल करना

Nessie को आपके चुने हुए इन्फ्रास्ट्रक्चर पर चलाएँ, एक मशीन से लेकर प्रबंधित क्लाउड तक।

शुरू करने से पहले आपको क्या चाहिए

Nessie एक pnpm monorepo है, जिसमें Node सेवाएँ और दो स्टैटिक बंडल शामिल हैं। चाहे आप इसे किसी भी तरीके से चलाएँ, पहले ये चार चीज़ें मौजूद होनी चाहिए।

• PostgreSQL के साथ pgvector। यह वैकल्पिक नहीं है, और इसे किसी और चीज़ से बदला नहीं जा सकता — माइग्रेशन CREATE EXTENSION vector चलाते हैं और vector(1024) कॉलम बनाते हैं। प्रोडक्शन में pgvector/pgvector:pg17 चलता है।
• Node 22 और pnpm। infrastructure/docker/ की हर Dockerfile node:22-slim पर बनती है, और रिपॉज़िटरी अपना पैकेज मैनेजर रूट package.json में पिन करती है (pnpm@10.22.0)।
• एक OpenAI-compatible मॉडल एंडपॉइंट और उसकी key। एजेंट और एम्बेडिंग, दोनों इसी से होकर जाते हैं। नीचे “इनफ़रेंस कॉन्फ़िगर करना” देखें।
• S3-compatible ऑब्जेक्ट स्टोरेज, किसी भी ऐसे डिप्लॉयमेंट के लिए जो स्थानीय डेवलपर सेटअप न हो। local मोड के बाहर लोकल डिस्क पर अपलोड स्वीकार नहीं होते, और यह अस्वीकार एक स्टार्ट-अप विफलता है, डिग्रेडेड बूट नहीं — देखें “एक मशीन, या मैनेज्ड क्लाउड”।

Docker और एक reverse proxy उस कंटेनर वाले रास्ते के लिए ज़रूरी हैं जो नीचे बताया गया है, और इंटरनेट से पहुँचने योग्य किसी भी चीज़ के लिए एक डोमेन और TLS चाहिए।

हार्डवेयर साइज़िंग — किसी दिए गए लोगों की संख्या के लिए न्यूनतम CPU, मेमोरी और डिस्क — रिपॉज़िटरी में कहीं नहीं बताई गई है, इसलिए यह पेज भी इसे नहीं बताता।

घटक, और वे आपस में कैसे जुड़ते हैं

API और वर्कर एक image हैं। दोनों packages आपस में गहराई से जुड़े हैं, इसलिए Dockerfile.app पूरे कोड को एक बार बनाता है, और वर्कर कंटेनर कमांड को node worker/dist/index.js पर बदल देता है। local मोड में वर्कर का कोई अलग कंटेनर नहीं होता: API अपने ही process के भीतर वर्कर चलाता है।

कोई Redis नहीं है। जॉब क्यू और realtime transport, दोनों Postgres पर चलते हैं — यह किसी चूक से नहीं, बल्कि सोचा-समझा फ़ैसला है। Google Cloud वाला tree भी इसी कारण से अपने Pub/Sub और Redis modules हटा देता है।

पोर्ट

स्थानीय विकास में API डिफ़ॉल्ट रूप से 5454 पर और एडमिन 5455 पर होता है। कोई चेकआउट अपनी जोड़ी ले सकता है, इसके लिए पर्यावरण में या रिपॉज़िटरी की .env में NESSIE_API_PORT और NESSIE_ADMIN_PORT सेट करें; रिपॉज़िटरी का हर टूल, ब्राउज़र टेस्ट सूट समेत, यही दो मान पढ़ता है। शुरू करने से पहले जोड़ी चुनिए और उसे बनाए रखिए: चल रही सेवा को दूसरे पोर्ट पर ले जाने से एडमिन गलत API से बात करने लगता है।

प्रोडक्शन का मामला अलग है और उस नियम से प्रभावित नहीं होता। API कंटेनर भीतर से 5554 पर सुनता है (NESSIE_API_PORT से पिन किया गया), और push relay 5556 पर; दोनों reverse proxy के पीछे रहते हैं।

एक मशीन पर विकास के लिए चलाना

रिपॉज़िटरी में एक Compose फ़ाइल है, जिसमें केवल एक डेटाबेस है, और स्थानीय loop को बस इतना ही चाहिए।

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

वह कंटेनर 55432 पर Postgres प्रकाशित करता है, जिसके user, password और डेटाबेस का नाम nessie है। कनेक्शन स्ट्रिंग रिपॉज़िटरी की root में एक .env में रखें — API की dev script उसे पढ़ती है — फिर माइग्रेशन लागू करें और वर्कर को एक बार बनाएँ, क्योंकि local मोड में API वर्कर को उसके बने हुए 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 API और एडमिन को hot reload के साथ समानांतर चलाता है, 5454 और 5455 पर। जाँचें कि API ने GET /api/health का जवाब दिया।

Postgres, और pgvector की ज़रूरत

तीन extensions माइग्रेशन खुद बनाते हैं — vector, pg_trgm और pgcrypto — इसलिए जो role उन्हें चलाती है, उसे extensions बनाने की अनुमति होनी चाहिए। किसी managed Postgres पर सबसे पहले यही जाँचें।

vector की चौड़ाई schema का हिस्सा है, कोई सेटिंग नहीं। thoughts.embedding, thought_recalls.query_embedding और knowledge_page_chunks.embedding vector(N) columns हैं, और N एक बार packages/schemas/src/embedding.ts में EMBEDDING_DIMENSIONS के रूप में लिखा है — अभी 1024, यानी उस embedding model की मूल चौड़ाई जिसे प्रोडक्शन इस्तेमाल करता है। हर embed request यही चौड़ाई भेजता है, इसलिए कोई प्रोवाइडर किसी और चौड़ाई पर जवाब दे, तो वह चुपचाप ऐसे vectors लिखने के बजाय ज़ोर से विफल होता है जिन्हें डेटाबेस स्वीकार नहीं करता। किसी अलग चौड़ाई वाले embedding model पर जाने के लिए उस constant को बदलना होगा, तीन columns का type बदलने वाला माइग्रेशन लिखना होगा, और फिर से embed करना होगा: अलग-अलग चौड़ाई के vectors आपस में बदले नहीं जा सकते, इसलिए माइग्रेशन उन्हें काटने के बजाय null कर देता है।

अगर आप Nessie को किसी साझा Docker network पर दूसरी applications के साथ चलाते हैं, तो उसके डेटाबेस कंटेनर को एक अलग नाम दें। प्रोजेक्ट की अपनी Compose service का नाम nessie-postgres है, कभी postgres नहीं, क्योंकि service का नाम साझा network पर DNS alias बन जाता है, और टकराव होने पर postgres:5432 दो डेटाबेस के बीच round-robin करता है।

कॉन्फ़िगरेशन

Runtime कॉन्फ़िगरेशन परतों में होता है: एक nessie.config.json फ़ाइल, जो API और वर्कर में केवल-पढ़ने (read-only) के लिए mount होती है, और उसके ऊपर environment variables। दोनों के बीच का मेल packages/config में ConfigEnvMap है, और वही आधिकारिक सूची है।

NESSIE_MODE डिप्लॉयमेंट का ढाँचा चुनता है: local (डिफ़ॉल्ट, और डेवलपर का रास्ता), hosted, या selfHosted — जो एक self-hosted इंस्टॉल सेट करता है। यह dev login बंद करता है और CORS allowlist माँगता है।

ये वे सेटिंग हैं जिनके बिना selfHosted deployment शुरू नहीं होगा, या ठीक से काम नहीं करेगा:

infrastructure/compose/.env.prod.example में सबकी सटीक बनावट है, और वैकल्पिक ब्लॉक — object storage, secret vault, SSO, connected mail — अपनी जगह पर comment किए हुए हैं। पूरी सूची, हर वैकल्पिक सेटिंग सहित, docs/deployment/configuration.md में है।

Docker Compose से deploy करना

.env.prod.example को docker-compose.prod.yml के साथ .env में कॉपी करें और उसे भरें, फिर डेटाबेस शुरू करें, build करें, migrate करें और start करें। क्रम मायने रखता है: माइग्रेशन और seeds ऐसे डेटाबेस पर चलते हैं जो पहले से चालू है, इससे पहले कि कोई service जवाब देना शुरू करे।

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

Production Dockerfiles हर package को build करने से पहले उसका lint चलाती हैं, इसलिए lint की विफलता build की विफलता है।

reconcile चरण वैकल्पिक नहीं है

reconcile हर संगठन की डिफ़ॉल्ट policy rules seed करता है और protected-MCP तथा Personal Assistant tool grants भरता है। API पहले यह काम हर replica पर boot के समय करता था; अब वह केवल कनेक्ट होता है, सुनता है, और बस इतना ही करता है। इसलिए इस चरण के बिना पहले संगठन के पास policy rules नहीं होंगे, और हर एजेंट का bind अस्वीकार होगा। यह idempotent है, इसलिए हर deploy पर इसे चलाने से कोई नुकसान नहीं होता — और हाथ से लागू किया गया upgrade भी इसे चलाए जाने की माँग करता है।

पहला owner खाता

नया selfHosted इंस्टॉल बिना किसी user के आता है, इसलिए API एक बार चलने वाला bootstrap token बनाता है और setup URL लॉग करता है। टोकन किसी process में नहीं, Postgres में रहता है, ताकि हर replica उसके बारे में एकमत रहे।

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

https://<your-admin-host>/bootstrap?token=<token> खोलें और owner खाता बनाएँ। टोकन 15 मिनट में समाप्त हो जाता है; नया टोकन बनाने के लिए API service रीस्टार्ट करें।

अगर आप SSO कॉन्फ़िगर करते हैं, तो bootstrap का कोई चरण नहीं होता। जैसे ही कोई बाहरी auth provider चालू होता है, bootstrap mode बंद हो जाता है — वरना वह login screen पर कब्ज़ा कर लेता — और SSO से पहली बार साइन इन करने वाला व्यक्ति डिफ़ॉल्ट टीम को bootstrap करके उसका owner बन जाता है।

इनफ़रेंस कॉन्फ़िगर करना

Chat OpenAI-compatible है। NESSIE_MODEL_BASE_URL एंडपॉइंट है, NESSIE_MODEL_API_KEY bearer है, और NESSIE_MODEL_PROVIDER adapter का नाम बताता है — Nessie openai, kimi और deepseek के लिए adapters कंपाइल करता है, और बाकी किसी भी चीज़ तक generic OpenAI-compatible कनेक्टर से पहुँचता है। NESSIE_MODEL_NAME डिप्लॉयमेंट का डिफ़ॉल्ट मॉडल सेट करता है, जिसे किसी एक एजेंट का अपना मॉडल चुनाव भी बदल सकता है।

एम्बेडिंग अलग से रूट होते हैं, क्योंकि चैट प्रोवाइडर उन्हें बिल्कुल नहीं दे सकता — उदाहरण के लिए DeepSeek के पास embeddings endpoint नहीं है। हर बिना सेट NESSIE_EMBEDDING_* field chat प्रोवाइडर से मान लेता है, इसलिए जो डिप्लॉयमेंट इनमें से कुछ भी सेट नहीं करता, वह चैट एंडपॉइंट से ही embed करता है। जब चैट provider embed न कर सके, तब NESSIE_EMBEDDING_PROVIDER और NESSIE_EMBEDDING_MODEL सेट करें, और अगर proxy service के आधार पर route करता है, तो service segment भी। गलत कॉन्फ़िगरेशन ज़ोर से नहीं, चुपचाप विफल होता है: memory recall और knowledge-base search lexical चैनल पर गिर जाते हैं और चलते रहते हैं, और इस दौरान kb_search: query embedding failed लॉग करते हैं।

Nessie का अपना खर्च-हिसाब — हर संगठन का token ledger और budget gate — इस बात से प्रभावित नहीं होता कि आप उसे किस एंडपॉइंट पर भेजते हैं, और signed per-call attribution कॉन्फ़िगर हो या न हो, दोनों में एक जैसा काम करता है।

साइन इन करना

Nessie लोगों को UnlikeOtherAI के ज़रिए प्रमाणित करता है, जो संगठन और टीम की संरचना भी संभालता है। एडमिन के login पेज पर एक ही बटन दिखता है: “Login / Register”।

यह integration standard OIDC के बजाय एक config-JWT flow है: API GET /api/auth/sso/config पर एक signed RS256 config document देता है, और मेल खाती JWKS GET /.well-known/jwks.json पर, दोनों API host पर। इसे एक बार करने वाला क्रम है — एक RSA-2048 keypair बनाएँ और UOA_CONFIG_JWT_PRIVATE_KEY_B64, UOA_CONFIG_JWT_KID, UOA_DOMAIN, UOA_CONFIG_URL, UOA_JWKS_URL, UOA_REDIRECT_URL और UOA_CONTACT_EMAIL सेट करें; बटन एक बार दबाएँ, जिससे एक integration अनुरोध खुलता है; उसे मंज़ूरी दिलवाएँ, जिससे contact पते पर एक बार का link जाता है, जिसमें client secret होता है; फिर UOA_CLIENT_SECRET सेट करें और API रीस्टार्ट करें। kid हर domain के लिए अनूठा होना चाहिए।

domain के पीछे रखना, TLS के साथ

एक डिप्लॉयमेंट तीन नाम परोसता है: सार्वजनिक साइट, एडमिन और API। एडमिन और API के ओरिजिन आपस में बदले नहीं जा सकते। Dockerfile.admin build के समय VITE_API_BASE_URL को bundle में डाल देता है, इसलिए हर बना हुआ admin artifact — desktop build भी, जो उसे साथ लेकर चलता है — API ओरिजिन के खिलाफ़ बनना चाहिए। अगर उसे एडमिन के अपने ओरिजिन के खिलाफ़ बनाया गया, तो /api/auth/providers एडमिन के HTML shell तक पहुँचेगा, और login “Loading providers...” पर अटका रहेगा।

Production में TLS Caddy पर समाप्त होता है, जो हर hostname का certificate HTTP-01 से लेता है, और उसके लिए DNS-provider plugin की ज़रूरत नहीं होती। प्रॉक्सी को एडमिन और web containers की ओर port 80 पर भेजें, और API की ओर उसके भीतरी port पर।

NESSIE_API_TRUSTED_PROXY_HOPS को API के सामने मौजूद proxies की संख्या पर सेट करें — एक reverse proxy के पीछे 1। यह डिफ़ॉल्ट रूप से 0 होता है, जो X-Forwarded-For को पूरी तरह अनदेखा करता है। यह एक फ़ैसला है जिसके दो नतीजे हैं: यही authentication rate limits की कुंजी भी है, इसलिए बहुत कम हो तो हर क्लाइंट प्रॉक्सी की एक ही bucket साझा करता है, और बहुत ज़्यादा हो तो क्लाइंट अपना पता खुद गढ़ सकता है। कम से शुरू करें और मापें।

हर संगठन और टीम को उसका अपना subdomain देना संभव है, और यह डिफ़ॉल्ट रूप से बंद है। यह NESSIE_TEAM_HOST_BASE_DOMAIN से नियंत्रित होता है; सेट न हो तो tenants को hostname से बिल्कुल route नहीं किया जाता। और certificate जारी करने का गेट NESSIE_TLS_CHECK_KEY जब तक सेट न हो, हर चीज़ से इनकार करता है — जो उस डिप्लॉयमेंट के लिए सही डिफ़ॉल्ट है जो यह सुविधा इस्तेमाल नहीं करती।

हेल्थ चेक

SIGTERM मिलने पर API जहाँ है वहीं मर जाने के बजाय drain करता है। NESSIE_SHUTDOWN_TIMEOUT_MS उस drain की सीमा तय करता है, और डिफ़ॉल्ट 25 सेकंड है; इसे उस grace period से कम रखें जो आपका orchestrator container को देता है, वरना runtime पहले process को मार देगा और drain से कोई फ़ायदा नहीं होगा।

Upgrade करना

Upgrade का मतलब है मौजूदा डेटाबेस पर prisma migrate deploy, फिर seeds, फिर reconcile। पहली deploy वाले वही चार कमांड।

यह रास्ता उस route के लिए परखा गया है जो एक self-hoster सच में लेता है, खाली डेटाबेस पर नहीं: CI एक snapshot restore करता है जो बीस migrations पीछे लिया गया था, उसे current head तक migrate करता है, schema validate करता है और मुख्य tables पर smoke check चलाता है। उस trailing window के भीतर का कोई भी release एक सिद्ध upgrade स्रोत है। Migration folders एक बार commit होने के बाद अपरिवर्तनीय (immutable) हैं, और अगर कोई folder नाम बदले, नंबर बदले, मिटाया जाए या बदला जाए, तो lint step build विफल करता है, क्योंकि ये चारों migrate deploy को उस डेटाबेस के लिए तोड़ देते हैं जिसने पुरानी row दर्ज कर ली है।

एक विफल migration उसके बाद की हर deploy को रोक देता है। migrate deploy पहली विफलता पर रुक जाता है और बाद की हर migration को P3009 के साथ मना कर देता है, इसलिए installation पुराने release पर अटकी रहती है, जब तक कोई उसे हाथ से साफ़ न कर दे। प्रोजेक्ट की अपनी production ने एक दिन तक हर deploy को इसी तरह ठुकराया। किसी एक को साफ़ करने का मतलब है यह पक्का करना कि विफल migration सच में rollback हो चुकी है — जो objects वह बनाती है वे मौजूद नहीं होने चाहिए, और जो वह बदलती है वह अपने मूल रूप में होनी चाहिए — और फिर ही उसे rolled back के रूप में resolve करें। जो migration आधी लागू हुई है, वह इस प्रक्रिया के लिए उम्मीदवार नहीं है।

Self-hosted Compose डिप्लॉयमेंट के लिए backup और restore repository में दस्तावेज़ित नहीं हैं, इसलिए यह पेज उसके लिए कोई प्रक्रिया नहीं बताता।

एक मशीन, या मैनेज्ड क्लाउड

ऊपर का single-host Docker Compose रास्ता वह है जो सिद्ध है: यही वह है जिस पर प्रोजेक्ट की अपनी production एक single server पर चलती है, जिसमें database, object storage, API, वर्कर, एडमिन और साइट सब कंटेनर हैं जो एक साझा reverse proxy के पीछे हैं।

एक से ज़्यादा मशीनों पर जाने से तीन चीज़ें बदलती हैं, और ये सिर्फ़ सलाह नहीं, बल्कि लागू होने वाली बातें हैं। local मोड के बाहर Nessie API और वर्कर को अलग processes के रूप में चलाता है, और उनकी कई-कई प्रतियाँ, इसलिए कोई भी क्षमता जो मानती है कि एक process मशीन की disk का मालिक है, मना है: filesystem object storage (start-up विफलता), docker provider वाले execution-environment templates (निष्क्रिय, और provisioning ज़ोर से विफल होती है), और file_read, file_write तथा file_glob builtin tools (एक विफल tool result, जिसे एजेंट पढ़ सकता है)। हर इनकार बताता है कि कौन-सी सेटिंग, कौन-सा मोड, और उसकी जगह क्या इस्तेमाल करें।

Managed cloud के लिए repository में infrastructure/terraform/ में एक Terraform tree है, जो Google Cloud को लक्षित करता है: API एक Cloud Run service के रूप में, कम से कम एक इंस्टेंस के साथ — वह एक persistent Postgres LISTEN क्लाइंट रखता है और maintenance sweeps चलाता है, इसलिए इसे शून्य तक स्केल करने पर realtime delivery रुक जाती है; वर्कर एक Cloud Run worker pool के रूप में, क्योंकि वह कोई port बाइंड नहीं करता और एक Service कभी ready नहीं होती; एक migrate job जो हर rollout पर पहरा देता है; Cloud SQL for PostgreSQL 17; और एक GCS bucket, जिस तक S3-compatible backend से पहुँचा जाता है।

वह रास्ता लिखा गया है, चलाकर परखा नहीं गया। repository यह साफ़ कहती है, और यह पेज भी: इसके लिए कोई Google Cloud प्रोजेक्ट मौजूद नहीं है, tree में कुछ भी किसी असली प्रोजेक्ट के खिलाफ़ न योजना बना है न लागू हुआ है, GCS पर multipart upload का रास्ता किसी असली bucket पर परखा नहीं गया, worker-pool resource type अप्रमाणित है, और इसमें trusted-proxy hop count एक placeholder है, जिसे मापा जाना बाकी है, माप नहीं। एडमिन और सार्वजनिक साइट वहाँ बिल्कुल मॉडल नहीं किए गए हैं। इसे एक शुरुआती बिंदु मानें जिसे आप खुद सत्यापित करें, समर्थित डिप्लॉयमेंट नहीं।

डिप्लॉयमेंट का डेटा कहाँ रहता है, software क्या रखता है और जानबूझकर क्या नहीं रखता, यह एक अलग पेज पर है: EU में बना, और आपका डेटा कहाँ रहता है।