# 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-09-21
- 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)
- [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 GB, 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) 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

- `${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](/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 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/).

---

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

Ardından:

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

```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 tek güncelleme, gömme boyutlarındaki bir değişikliktir — bkz.
[Gömme Modelleri](/tr/docs/embedding-models/).

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

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