Kurulum

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
• Kaldırma

---

Gereksinimler

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

• ${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 ç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).

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 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.

---

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 ve Notion çekimleri
SECRET_KEY=                              # yalnızca özel depolar / Notion için gerekir

Ardından:

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

Node.js 22 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 tek güncelleme, gömme boyutlarındaki bir değişikliktir — bkz. Gömme Modelleri.

Etiketler. latest her zaman en yeni kararlı sürümü gösterir; 0.2, 0.2.x hattındaki en son yamayı takip eder; 0.2.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=0.2.0) sürümlü bir etiket sabitleyin — bu, yalnızca ilk başlatmada değil, her başlatmada okunur.

---

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.