# 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: 2026-11-04
- Kaynak: https://contextator.com/tr/docs/installation/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
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](#gereksinimler)
- [Yayımlanmış imajla Docker Compose (önerilen)](#yayımlanmış-imajla-docker-compose-önerilen)
- [Sade `docker run`](#sade-docker-run)
- [Kendi imajınızı derleyin](#kendi-imajınızı-derleyin)
- [Kurulumdaki ilk hesap](#kurulumdaki-ilk-hesap)
- [Bir reverse proxy arkasında](#bir-reverse-proxy-arkasında)
- [Kaynaktan, Docker olmadan](#kaynaktan-docker-olmadan)
- [Güncelleme](#güncelleme)
- [Komut satırı](#komut-satırı)
- [Kaldırma](#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](/tr/docs/embedding-models/) |

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:

```bash
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:

```bash
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:

```bash
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](#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](/tr/docs/backup-and-data/).

---

## Sade `docker run`

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

```bash
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](/tr/docs/configuration/).

`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](/tr/docs/kubernetes/).

---

## 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:

```bash
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](/tr/docs/accounts-and-permissions/) 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](/tr/docs/security/)).
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:

```bash
PUBLIC_BASE_URL=https://docs.example.com
AUTH_COOKIE_SECURE=1
```

İşe yarayan bir nginx location'ı:

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

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

`.env` içinde:

```bash
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:

```bash
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

```bash
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](/tr/docs/embedding-models/); 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](/tr/docs/configuration/#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](/tr/docs/troubleshooting/#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ı](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md) 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ı](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md). 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](https://github.com/Contextator/Contextator/blob/main/CHANGELOG.md)'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](/tr/docs/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.

```bash
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'ı](/tr/docs/accounts-and-permissions/) 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

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