> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diyanet.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Hızlı Başlangıç

> Local geliştirme ortamını Docker ile tek komutta ayağa kaldırma

Bu sayfa **dev** ortamını sıfırdan çalıştırmayı anlatır. Stage/Prod için [Operasyon › Docker Stage](/operations/docker-stage) ve [Docker Prod](/operations/docker-prod) sayfalarına bakın.

<Note>
  Dev ortamında her servis **kendi host port'unda** çalışır; reverse-proxy yoktur. `docker-compose.override.yml` otomatik yüklenir ve tüm altyapıyı (Postgres, Redis, RabbitMQ, Keycloak, Seq, pgAdmin, …) container'lardan getirir.
</Note>

## Ön koşullar

<Steps>
  <Step title="Docker Desktop çalışıyor">
    `docker compose version` v2 dönmeli. Windows'ta WSL 2 backend açık.
  </Step>

  <Step title="Portlar boş">
    `5005, 3000, 3001, 5432, 6379, 5672, 15672, 8080, 5341, 5342, 5050` boş olmalı.
  </Step>

  <Step title="(Opsiyonel) .NET 10 + Node 22">
    Container dışında geliştirme/debug için. Sadece çalıştıracaksanız gerekmez.
  </Step>
</Steps>

Detay için [Ön Gereksinimler](/getting-started/prerequisites).

## 1. Repoyu klonla

```bash theme={null}
git clone https://github.com/cihandelipinar/diyanet-clean-architecture.git
cd diyanet-clean-architecture
```

## 2. `.env` dosyasını hazırla

Dev compose, repo kökündeki `.env` dosyasını okur. Örnekten kopyalayın ve `CHANGE_ME` değerlerini doldurun:

```bash theme={null}
cp .env.example .env
```

Doldurulması gereken kritik değişkenler:

```text theme={null}
# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=guclu_bir_sifre
POSTGRES_DB=DiyanetCleanArchitecture

# Redis
REDIS_PASSWORD=guclu_bir_sifre

# RabbitMQ
RABBITMQ_USER=admin
RABBITMQ_PASSWORD=guclu_bir_sifre

# JWT (uzunluk önemli)
JWT_BACKOFFICE_SECRET=en_az_32_karakter_rastgele
JWT_OTP_SECRET=en_az_64_karakter_rastgele

# Keycloak (dev container)
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=admin

# pgAdmin
PGADMIN_EMAIL=admin@example.com
PGADMIN_PASSWORD=admin
```

<Warning>
  `JWT_BACKOFFICE_SECRET` en az **32**, `JWT_OTP_SECRET` en az **64** karakter olmalıdır; aksi halde token imzalama başlatılırken hata verir. Tüm `.env*` dosyaları `.gitignore`'dadır, commit edilmez.
</Warning>

Tüm değişkenlerin tam listesi için [Operasyon › Ortam Değişkenleri](/operations/env-variables).

## 3. Her şeyi başlat

```bash theme={null}
docker compose up -d --build
```

Bu komut:

1. `docker-compose.yml` (base: API + 2 SPA) + `docker-compose.override.yml`'i (dev altyapı) birleştirir.
2. API'yi (multi-stage .NET 10 imajı) ve iki SPA'yı (Vite build → nginx) derler.
3. PostgreSQL, Redis, RabbitMQ, Keycloak, Seq, pgAdmin, RedisInsight, Prometheus, Grafana'yı ayağa kaldırır.

İlk derleme birkaç dakika sürebilir. Durumu izleyin:

```bash theme={null}
docker compose ps
docker compose logs -f diyanetcleanarchitecture-api
```

## 4. Veritabanı migration'ları

`appsettings.Development.json` içinde `Services:Migration:AutoDeploy: true` olduğundan, API açılışında **`MigrationService`** otomatik `Database.MigrateAsync()` çalıştırır ve şemayı oluşturur. Ayrıca `DistrictSeeder` 973 ilçeyi, `DevDataSeeder` bootstrap admin'leri yükler.

Migration'ı elle uygulamak isterseniz:

```bash theme={null}
docker exec diyanetcleanarchitecture-api \
  dotnet ef database update \
  --project src/DiyanetCleanArchitecture.Infrastructure.EFCore \
  --startup-project src/DiyanetCleanArchitecture.API
```

Detay: [Veri Katmanı › Migration'lar](/data/migrations).

## 5. Servislere erişim

| Servis                 | URL                                                            | Giriş                                 |
| ---------------------- | -------------------------------------------------------------- | ------------------------------------- |
| **Website SPA**        | [http://localhost:3000](http://localhost:3000)                 | Keycloak (vatandaş)                   |
| **Admin SPA**          | [http://localhost:3001](http://localhost:3001)                 | Keycloak (personel)                   |
| **API**                | [http://localhost:5005](http://localhost:5005)                 | —                                     |
| **Swagger / Scalar**   | [http://localhost:5005/swagger](http://localhost:5005/swagger) | —                                     |
| **Keycloak Admin**     | [http://localhost:8080](http://localhost:8080)                 | `admin` / `KEYCLOAK_ADMIN_PASSWORD`   |
| **pgAdmin**            | [http://localhost:5050](http://localhost:5050)                 | `PGADMIN_EMAIL` / `PGADMIN_PASSWORD`  |
| **RabbitMQ UI**        | [http://localhost:15672](http://localhost:15672)               | `RABBITMQ_USER` / `RABBITMQ_PASSWORD` |
| **Seq (loglar)**       | [http://localhost:5342](http://localhost:5342)                 | — (dev'de auth yok)                   |
| **Hangfire Dashboard** | [http://localhost:5005/jobs](http://localhost:5005/jobs)       | `admin` / `admin`                     |
| **RedisInsight**       | [http://localhost:5540](http://localhost:5540)                 | —                                     |
| **Prometheus**         | [http://localhost:9090](http://localhost:9090)                 | —                                     |
| **Grafana**            | [http://localhost:3030](http://localhost:3030)                 | `admin` / `admin`                     |

## 6. Keycloak provisioning

Dev'de Keycloak **otomatik** kurulur: `KeycloakProvisioning:Enabled: true` olduğundan API açılışta `diyanet-vatandas-dev-realm` ve `diyanet-yonetim-dev-realm` realm'lerini, client'larını, protokol mapper'larını ve test kullanıcılarını oluşturur (`RunOnce`).

Test kullanıcıları oluşturmak/güncellemek için PowerShell yardımcıları:

```powershell theme={null}
./scripts/create-keycloak-dev-users.ps1
./scripts/set-keycloak-test-user-attributes.ps1
```

Detay: [Keycloak › Provisioning](/keycloak/provisioning).

## Faydalı komutlar

```bash theme={null}
# Canlı log
docker compose logs -f diyanetcleanarchitecture-api

# Tek servisi yeniden derle + başlat
docker compose up -d --build diyanetcleanarchitecture-api

# Tek servisi yeniden başlat
docker compose restart rabbitmq

# Durdur (veri korunur)
docker compose down

# Sıfırla (volume'lar dahil — TÜM veri silinir)
docker compose down -v
```

Tüm komut referansı: [Operasyon › Komutlar](/operations/commands).

## Sorun mu çıktı?

<AccordionGroup>
  <Accordion title="API 'connection refused' (Postgres/Redis) veriyor">
    Altyapı container'ları henüz hazır değil olabilir. `docker compose ps` ile `healthy` durumu bekleyin; API `depends_on` ile health bekler ama ilk kalkışta retry görebilirsiniz.
  </Accordion>

  <Accordion title="Keycloak login açılmıyor / realm yok">
    Provisioning birkaç saniye sürer. `docker compose logs -f diyanetcleanarchitecture-api` içinde `[Keycloak Provisioning]` satırlarını izleyin. Bkz. [Keycloak › Troubleshooting](/keycloak/troubleshooting).
  </Accordion>

  <Accordion title="Port çakışması">
    İlgili host port'unu kullanan başka bir süreç var. `docker compose down` sonrası port'u boşaltın veya `docker-compose.override.yml`'de port eşlemesini değiştirin.
  </Accordion>
</AccordionGroup>