Contextator
ENTR

Başlangıç

Kurulum

Contextator'ı çalıştırmanın her yolu — Docker Compose, sade docker run, imajı kendiniz derlemek ya da kaynaktan — üstelik ilk hesap ve reverse proxy kurulumuyla.

Güncelleme:

Contextator, pgvector’lü PostgreSQL 16 ile Node.js uygulamasını içeren tek bir Docker imajı olarak gelir. Kurulacak ayrı bir veritabanı ve bir migration adımı yoktur: şema her başlatmada oluşturulur ve güncel tutulur.


Gereksinimler

Docker Compose v2 destekleyen güncel bir sürüm (docker compose, docker-compose değil)
Disk İmaj için ~1,2 GB (-slim olan için ~860 MB), varsayılan gömme modeli için ~470 MB (EMBEDDING_DTYPE=q8 ile ~120 MB), artı belgeleriniz ve vektörleri
RAM 2 GB rahat yeter; gömme işlemi CPU-bound’dur, bellek açlığı çekmez
CPU Herhangi bir x86-64 ya da ARM64 CPU. GPU gerekmez ve kullanılmaz. Yayımlanmış imaj linux/amd64 ve linux/arm64 için derlenir, bu yüzden Apple Silicon’da emülasyonsuz çalışır
Ağ Yalnızca tek seferlik model indirmesi ve uzak kaynaklar (git, Notion, Confluence, web, S3, Google Drive, GitHub) için gerekir. Hava boşluklu (air-gapped) kurulumlar mümkündür — bkz. Gömme Modelleri

Linux, macOS ve Docker Desktop for Windows’ta (WSL 2 arka ucu) çalışır.


Yayımlanmış imajla Docker Compose (önerilen)

Klonlamaya gerek yok — yalnızca compose dosyası ve açıklamalı ortam şablonu:

mkdir contextator && cd contextator
curl -fsSLO https://raw.githubusercontent.com/Contextator/Contextator/main/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/Contextator/Contextator/main/.env.example
cp .env.example .env

.env’i düzenleyin — en azından dokümantasyonunuzu göstermelisiniz:

DOCS_HOST_PATH=/path/to/your/docs     # konteynerde /docs'a salt okunur bağlanır
PORT=3444                             # host portu
SETUP_CODE=                           # opsiyonel: ilk çalıştırma kodunu kendiniz seçin

Ardından:

docker compose up -d
docker compose logs -f                # "embedding model ready" yazısını bekleyin

http://localhost:3444/ adresini açın ve ilk hesabı oluşturun — bkz. Kurulumdaki ilk hesap.

Compose dosyası ne yapar

  • ${CONTEXTATOR_BIND:-127.0.0.1}:${PORT}:3444’ü yayımlayarak contextator adlı tek bir konteyneri çeker ve çalıştırır. Yayımlanmış imaj contextator/contextator’dır.
  • docker compose down, güncellemeler ve konteyner kaldırmadan sağ çıkan üç volume oluşturur: contextator-pgdata (veritabanı), contextator-models (indirilen modeller) ve contextator-data (yüklenen dosyalar, git checkout’ları, Notion, Confluence, doküman sitesi, S3, Google Drive ve GitHub çekimleri).
  • DOCS_HOST_PATH’i /docs’a salt okunur bağlar.
  • Siz durdurmadığınız sürece konteyneri yeniden başlatır (restart: unless-stopped).

DATABASE_URL ayarlıysa gömülü PostgreSQL başlatılmaz ve konteyner onun yerine o veritabanını kullanır — PostgreSQL’siz gelen -slim imaj da böyle çalıştırılır.

Konteynerin içinde PostgreSQL yalnızca 127.0.0.1’i dinler ve dışarı yayımlanmaz — gerektiğinde ona nasıl ulaşacağınız için bkz. Yedekleme ve Veri.


Sade docker run

Compose olmadan, aynı dört yolu kendiniz bağlayın:

docker run -d --name contextator -p 127.0.0.1:3444:3444 \
  -e SETUP_CODE=whatever-you-like \
  -v contextator-pgdata:/var/lib/postgresql/data \
  -v contextator-models:/app/.cache/models \
  -v contextator-data:/data \
  -v /path/to/your/docs:/docs:ro \
  contextator/contextator

Diğer her ayarı -e ile ekleyin — bkz. Yapılandırma.

127.0.0.1, portu yalnızca bu makinede yayınlar; Compose’un kullandığı varsayılan da budur. Örneğe başka makinelerden ulaşmak için yerine dinlenecek arayüzün adresini yazın (-p 192.168.1.20:3444:3444, ya da her arayüz için 0.0.0.0) — ve her projenin MCP erişimini token required ya da account required üzerinde tutun; yeni bir proje zaten böyle başlar. Compose’ta aynı anahtar .env içindeki CONTEXTATOR_BIND’dır.

Contextator’ı bir Kubernetes kümesinde çalıştırmak için Helm chart’ını kullanın; bkz. Kubernetes Üzerinde Çalıştırma.


Kendi imajınızı derleyin

Yukarıdaki compose dosyası contextator/contextator’ı çeker. Bunun yerine kaynaktan derlemek için — Dockerfile’da bir değişikliği denemek ya da yayımlanmış imajın kapsamadığı bir mimaride çalıştırmak için — depoyu klonlayın ve derleme override’ını üstüne katmanlayın:

git clone https://github.com/Contextator/Contextator.git contextator && cd contextator
cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

docker-compose.build.yml, imajı checkout edilmiş kaynaktan derler ve onu latest değil, bilinçli olarak contextator/contextator:source diye etiketler. Compose’un varsayılan pull_policy’si missing’tir, bu yüzden paylaşılan bir etiket iki iş akışının birbirini sessizce ezmesine yol açardı: bir kere derlersiniz ve sonraki sade bir docker compose up -d, gerçek imajı çekmek yerine eski yerel derlemenizi yayımlanmış adın altında çalıştırmaya devam ederdi. Geri kalan her şey — volume’lar, ortam değişkenleri, portlar — tam olarak docker-compose.yml’in tanımladığı şeydir.


Kurulumdaki ilk hesap

Pano bir hesaba ihtiyaç duyar ve yeni bir kurulumda hiç hesap yoktur. İlki var olana kadar her başlatma stdout’a tek seferlik bir kurulum kodu yazdırır:

┌─ Contextator first-run setup ───────────────────────────────────────────┐
│ No user accounts exist yet; the dashboard is waiting for its first one. │
│                                                                         │
│   Open   http://localhost:3444/setup                                    │
│   Code   KRTW-9MHD-2PQF                                                 │
│                                                                         │
│ A new code is printed on every start until that first account exists.   │
└─────────────────────────────────────────────────────────────────────────┘

docker compose logs -f bunu gösterir. /setup’ı açın — / zaten oraya yönlendirir — ve kodu, bir kullanıcı adı ve en az 12 karakterlik bir parola girin. O hesap root’tur ve onu oluşturmak setup’ı kalıcı olarak kapatır; döndürülecek bir şey kalmaz.

Kodu kendiniz seçmek için .env’de SETUP_CODE’u, tıpkı POSTGRES_PASSWORD’ü seçer gibi ayarlayın. Kendi seçtiğiniz kod loga yazdırılmaz. Üretilmiş biri kaybolduysa sunucuyu yeniden başlatın ve yenisini okuyun.

Bundan sonrası — daha fazla hesap, roller, proje başına üyeler — Hesaplar ve İzinler sayfasındadır.

Panoyu düz HTTP üzerinden bir LAN adresinde mi sunuyorsunuz? AUTH_COOKIE_SECURE=0 ayarlayın, yoksa tarayıcılar oturum çerezini düşürür ve oturum açma /login’e geri döner.


Bir reverse proxy arkasında

Yeni bir projenin MCP endpoint’i varsayılan olarak token required’dır, ama herhangi bir proje kendi sayfasında open’a ya da account required’a çevrilebilir (Güvenlik). Sunucu güvenmediğiniz herkesin ulaşabileceği bir yerdeyse, özel kalması gereken hiçbir projenin open’a çevrilmediğini kontrol edin ve kasıtlı olarak açık bıraktığınız her projenin önüne proxy’nin kendi kimlik doğrulamasını koyun.

Doğru yapılması gereken üç şey:

  1. Yanıtları tamponlamayın. Eski SSE transport’u uzun ömürlü bir akıştır.
  2. Panoya kendi genel URL’sini söyleyin, bastığı parçaların doğru olması için.
  3. Çerez bayrağını sabitleyin. Proxy TLS’i sonlandırır, bu yüzden uygulama şemayı yalnızca X-Forwarded-Proto’dan öğrenir. Bunu açıkça söyleyin:
PUBLIC_BASE_URL=https://docs.example.com
AUTH_COOKIE_SECURE=1

İşe yarayan bir nginx location’ı:

location / {
    proxy_pass http://127.0.0.1:3444;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_read_timeout 1h;
}

Başka bir origin’deki tarayıcıların /mcp/*’e ulaşması gerekiyorsa o origin’i ALLOWED_ORIGINS’e ekleyin. Komut satırı istemcileri hiç Origin başlığı göndermez ve her zaman izinlidir.


Kaynaktan, Docker olmadan

Geliştirme için ya da zaten bir PostgreSQL çalıştırıyorsanız kullanışlıdır.

docker compose -f docker-compose.dev.yml up -d   # localhost:5432'de PostgreSQL 16 + pgvector
cp .env.example .env

.env içinde:

DATABASE_URL=postgres://contextator:contextator@localhost:5432/contextator
ALLOWED_DOC_ROOTS=/home/me/docs          # Windows'ta C:/Users/me/docs
DATA_DIR=.data                           # git checkout'ları, yüklemeler, Notion/Confluence/site çekimleri
SECRET_KEY=                              # yalnızca özel depolar / Notion / Confluence için gerekir

Ardından:

npm install
npm run dev        # tsx watch → http://localhost:3444
npm test           # birim testleri
npm run typecheck

1.0.0’dan beri Node.js 24 ya da daha yenisini gerektirir — package.json’ın engines’indeki taban ve konteynerin taşıdığı sürüm — ve vector eklentili bir PostgreSQL 16.


Güncelleme

docker compose pull
docker compose up -d

Bunun yerine kaynaktan derliyorsanız: git pull, ardından docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.

Şema başlatmada otomatik olarak güncellenir. Veriniz volume’lardadır ve bir güncellemeden etkilenmez. Sizden bir karar isteyen üç güncelleme vardır: gömme boyutlarındaki bir değişiklik — bkz. Gömme Modelleri; 0.2.0’dan önceki bir sürümden geliyorsanız, aşağıdaki DATABASE_URL denetimi; ve ortamınızda TRUST_PROXY=1 ya da true olan bir 0.4.x’ten geliyorsanız, proxy’yi adlandırmak, çünkü 0.5.0 bu değerleri başlangıçta reddeder — bkz. Bir reverse proxy arkasında çalışmak.

0.2.0’dan önceki bir sürümden geliyorsanız: önce .env’deki DATABASE_URL’i kontrol edin. Eski .env.example dosyaları, kaynaktan çalıştırmak için DATABASE_URL=postgres://contextator:contextator@localhost:5432/contextator ile geliyordu. 0.2.0’dan itibaren konteyner bu satırı okur: kendi PostgreSQL’ini başlatmaz ve veritabanına, hiçbir şeyin dinlemediği kendi loopback’inde ulaşmaya çalışır. Bilerek harici bir veritabanı adlandırmıyorsanız, docker compose up -d’den önce .env’deki DATABASE_URL’i temizleyin. Başlatma logu seçtiği veritabanını adlandırır ve PostgreSQL gömülü bir imajda loopback adresi ayarlandığında uyarır. Veriniz her iki durumda da dokunulmadan kalır. Bkz. Konteyner sürekli yeniden başlıyor.

Etiketler. latest her zaman en yeni kararlı sürümü gösterir; 1, her 1.x güncellemesini uyumluluk politikası kapsamında almak isteyen kurulumlar için en yeni 1.x sürümünü izler; 1.0, 1.0.x hattındaki en son yamayı takip eder; 1.0.0 tek, tam ve değişmez bir sürümdür. Bilinçli olarak güncellediğiniz her şey için .env’de CONTEXTATOR_TAG’i ayarlayarak (ör. CONTEXTATOR_TAG=1.0.0) sürümlü bir etiket sabitleyin — bu, yalnızca ilk başlatmada değil, her başlatmada okunur. Bunların her biri -slim sonekiyle de bulunur (latest-slim, 1-slim, 1.0-slim, 1.0.0-slim): PostgreSQL’siz aynı uygulama, DATABASE_URL gerektirir. 1 etiketi 1.0.0’dan itibaren yayımlanır; 0.x sürümlerinin yoktur.

1.0.0 neyi vaat eder. 1.0.0’dan itibaren bir sürümün neyi bozabileceği tek bir yerde yazılıdır: uyumluluk politikası. Hangi yüzeylerin dondurulduğunu, bir kaldırmanın nasıl duyurulduğunu ve her 1.x’in önceki her 1.x’i yükselttiğini anlatır. 0.7.x’ten geliyorsanız önce oradaki “Moving from 0.7.x to 1.0.0” bölümünü ve changelog’un 1.0.0 girdilerini okuyun.


Komut satırı

0.6.0’dan beri iki imaj da, varsayılan olan ve -slim, bir contextator komutu taşır. Admin API’nin küçük bir istemcisidir; aksi halde bir CI işinde birkaç curl çağrısı ve bir yoklama döngüsü olarak yazacağınız şey için: bir git deposundan proje oluşturmak, her türden bir kaynak eklemek, indeksini beklemek, bir MCP token’ı üretmek. Zaten çalıştırdığınız imajın sürümüdür, ayrı bir indirme değildir.

docker run --rm \
  -e CONTEXTATOR_URL=https://docs.example.com -e CONTEXTATOR_TOKEN \
  contextator/contextator:1.0.0-slim \
  contextator project create handbook --git https://github.com/acme/handbook --wait

İlk argüman olarak contextator, konteynerin yalnızca o komutu çalıştırmasını sağlar: sunucu yok, veritabanı yok, model indirmesi yok. İmajın başka her başlatılışı değişmeden kalır.

Komut Ne yapar
contextator project create <ad> --git <url> Projeyi oluşturur, aynı adlı bir git kaynağı ekler ve ilk indeks çalıştırmasını kuyruğa alır; --wait çalıştırmayı zaman aşımıyla izler
contextator source add --project <ad|id> --type <tür> Var olan bir projeye her türden bir kaynak ekler ve bir indeks çalıştırmasını kuyruğa alır. Ayarlar --config-json’a ya da --config-file’a (- standart girdiyi okur) verilir, ikisi birden değil; sunucu onları doğrular. Kimlik bilgisi asla bir argüman değildir: --secret-env <DEĞİŞKEN> onu tutan değişkenin adını verir
contextator project status <ad|id> Projenin indeksinin nerede olduğu; --wait ile çalıştırma başarısızsa 5 ile çıkar
contextator token create --project <ad|id> Bir MCP token’ı üretir; secret bir kez gösterildiği için --json ya da --show-secret zorunludur. --source <ad|id> (tekrarlanabilir) onu projenin bazı kaynaklarına bağlar; --expires-in-days 30, 90 ya da 365 alır, --allowed-cidr (tekrarlanabilir) token’ı sunmasına izin verilen bir ağı adlandırır
contextator backup Var olan yedekleme bu adla; -slim değil, varsayılan imaj gerekir

CONTEXTATOR_URL ve CONTEXTATOR_TOKEN ile bağlanır; bir hesabın API token’ı ya da ADMIN_TOKEN. Token hiçbir zaman bir argüman değildir, çünkü bir argüman süreç listesinde ve kabuk geçmişinde görünür; onu bir dosyadan okumak için --token-file <yol> kullanın. Çıktı satırlar ya da --json’dır, ilerleme stderr’e, sonuç stdout’a gider ve çıkış kodları durumları ayırır (0 başarı, 2 kullanım, 3 reddedilen kimlik bilgisi, 4 bulunamadı ya da zaten var, 5 indeks çalıştırması başarısız, 6 zaman aşımı, 7 ulaşılamadı). Sunucunun sürümü komutunkiyle aynı değilse uyarır; bu yüzden ikisi için aynı imaj etiketini kullanın. npm’de yayımlanmaz.


Kaldırma

docker compose down            # konteyneri durdurur ve kaldırır — VERİ KORUNUR
docker compose down -v         # volume'ları da siler — VERİ GİDER

Orijinal dokümantasyonunuz asla değiştirilmez: /docs salt okunur bağlanır ve yerel klasör kaynakları kopyalanmak yerine olduğu yerde taranır.

Gezinmek için ok tuşları, açmak için Enter.