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
- Yayımlanmış imajla Docker Compose (önerilen)
- Sade
docker run - Kendi imajınızı derleyin
- Kurulumdaki ilk hesap
- Bir reverse proxy arkasında
- Kaynaktan, Docker olmadan
- Güncelleme
- Komut satırı
- Kaldırma
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ımlayarakcontextatoradlı tek bir konteyneri çeker ve çalıştırır. Yayımlanmış imajcontextator/contextator’dır.docker compose down, güncellemeler ve konteyner kaldırmadan sağ çıkan üç volume oluşturur:contextator-pgdata(veritabanı),contextator-models(indirilen modeller) vecontextator-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=0ayarlayı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:
- Yanıtları tamponlamayın. Eski SSE transport’u uzun ömürlü bir akıştır.
- Panoya kendi genel URL’sini söyleyin, bastığı parçaların doğru olması için.
- Ç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.