Directus Docker Compose, PostgreSQL ve HTTPS ile nasıl kurulur

Directus açık bir veri platformudur: bir SQL veritabanına bağlanır, size anında bir REST ve GraphQL API'si verir ve editörlerin içerik, dosya ve kullanıcıları yönettiği kod gerektirmeyen bir uygulama ekler. Ekipler onu headless CMS olarak ve web siteleri ile uygulamalar için arka uç olarak kullanır. Bu rehber Directus'u resmi dağıtım örneğini izleyerek Docker Compose ile çalıştırır: sabit sürümlü bir Directus imajı, PostGIS'li PostgreSQL, bir Redis önbelleği, yüklemeler ve eklentiler için klasörler ve otomatik HTTPS için önde Caddy. Ardından ilk yöneticiyi güvenceye alır, kurulumu nasıl yedekleyeceğinizi, geri yükleyeceğinizi ve güncelleyeceğinizi öğrenirsiniz.

Adım 1 — Proje klasörünü ve gizli değerleri oluşturun

Bu uygulamaya ait her şeyi /opt/directus içinde tutun. Veritabanı, yüklemeler ve eklentiler klasörlerini ilk başlatmadan önce oluşturun; böylece Docker onları root olarak oluşturmaz, sizin kullanıcınıza ait olurlar:

sudo mkdir -p /opt/directus
sudo chown $USER:$USER /opt/directus
cd /opt/directus
mkdir -p uploads extensions data/database

Bir imzalama anahtarı ve bir veritabanı parolası üretin:

openssl rand -hex 32
openssl rand -hex 24

SECRET token'ları imzalar. Ayarlamazsanız Directus her başlangıçta rastgele bir değer kullanır ve her yeniden başlatmadan sonra herkesin oturumu kapanır; belgeleri bu değerin üretimde güvenli bir rastgele değerle mutlaka ayarlanması gerektiğini söyler. /opt/directus/.env dosyasını nano .env ile oluşturun:

SECRET=paste-the-64-character-value
DB_PASSWORD=paste-the-48-character-value
ADMIN_EMAIL[email protected]
ADMIN_PASSWORD=change-me-to-a-long-unique-password
PUBLIC_URL=https://directus.example.com

ADMIN_EMAIL ve ADMIN_PASSWORD ilk kullanıcıyı bootstrap sırasında oluşturur. PUBLIC_URL, API'nize erişilen adrestir; Directus SSO gibi özellikler için tam URL'ye ihtiyaç duyar. Dosyayı koruyun:

chmod 600 .env

Adım 2 — Compose dosyasını yazın

/opt/directus/compose.yaml dosyasını oluşturun. Dosya resmi örneği izler ve üretim için üç değişiklik içerir: Directus yalnızca 127.0.0.1 üzerinde yayınlanır, gizli değerler .env dosyasından gelir ve her servis yeniden başlatmadan sonra kalkar.

services:
  database:
    image: postgis/postgis:17-3.5
    volumes:
      - ./data/database:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: "directus"
      POSTGRES_PASSWORD: "${DB_PASSWORD}"
      POSTGRES_DB: "directus"
    healthcheck:
      test: ["CMD", "pg_isready", "--host=localhost", "--username=directus"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_interval: 5s
      start_period: 30s
    restart: unless-stopped

  cache:
    image: redis:7
    healthcheck:
      test: ["CMD-SHELL", "[ $$(redis-cli ping) = 'PONG' ]"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_interval: 5s
      start_period: 30s
    restart: unless-stopped

  directus:
    image: directus/directus:12.5.0
    ports:
      - "127.0.0.1:8055:8055"
    volumes:
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
    depends_on:
      database:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget --spider -q http://localhost:8055/server/ping || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_interval: 5s
      start_period: 30s
    environment:
      SECRET: "${SECRET}"
      DB_CLIENT: "pg"
      DB_HOST: "database"
      DB_PORT: "5432"
      DB_DATABASE: "directus"
      DB_USER: "directus"
      DB_PASSWORD: "${DB_PASSWORD}"
      CACHE_ENABLED: "true"
      CACHE_AUTO_PURGE: "true"
      CACHE_STORE: "redis"
      REDIS: "redis://cache:6379"
      ADMIN_EMAIL: "${ADMIN_EMAIL}"
      ADMIN_PASSWORD: "${ADMIN_PASSWORD}"
      PUBLIC_URL: "${PUBLIC_URL}"
    restart: unless-stopped

Dosya hakkında birkaç not:

• Sabit sürüm. Directus üretimde belirli bir sürüme sabitlemeyi önerir; çünkü sabit bir etiket, konteyner yeniden başladığında daha yeni bir sürümle değiştirilmez. Bu rehber Ekim 2026'da kontrol edildiğinde en yeni sürüm 12.5.0 idi. Güncel etiketi Directus sürümler sayfasında veya Docker Hub'da bulun ve kullanmadan önce kırıcı değişiklik notlarını okuyun.
• Veritabanı. Resmi örnek, coğrafi uzantılara sahip PostgreSQL olan PostGIS imajını kullanır. PostgreSQL verisi ./data/database içinde durur ve ana makineye hiç yayınlanmaz.
• Yüklemeler ve eklentiler. Yüklenen dosyalar ./uploads, özel eklentiler ./extensions içinde saklanır; ikisi de konteyner güncellemelerinden etkilenmez.
• Port. 127.0.0.1:8055, Directus'u genel arayüzün dışında tutar. Docker'ın yayınladığı portlar ufw kurallarını atlar; portu gerçekten koruyan şey loopback adresine bağlamaktır.

Adım 3 — Directus'u başlatın ve kontrol edin

docker compose up -d
docker compose ps
docker compose logs -f directus

İlk başlatmada Directus şemasını PostgreSQL'e kurar ve .env dosyasındaki bilgilerle yönetici kullanıcıyı oluşturur. Sunucunun başladığını bildirdiğinde log takibini Ctrl+C ile bırakın. Ardından docker compose ps çıktısında üç servis de healthy görünmelidir. Giriş gerektirmeyen canlılık uç noktasını test edin:

curl -s http://127.0.0.1:8055/server/ping

pong görmelisiniz. Directus konteyner içinde yetkisiz node kullanıcısıyla çalışır; kullanıcı kimliğini kontrol edip yüklemeler klasörünün sahibiyle karşılaştırın:

docker compose exec directus id
ls -ln /opt/directus

id komutunun yazdığı uid, uploads ve extensions klasörlerinin sahibinden farklıysa klasörleri bu kimliğe verin; örneğin konteyner uid=1000 bildiriyorsa sudo chown -R 1000:1000 uploads extensions kullanın.

Adım 4 — Directus'u Caddy ile HTTPS üzerinden yayınlayın

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin:

directus.example.com {
    reverse_proxy 127.0.0.1:8055
}

Caddy'yi yeniden yükleyin ve güvenlik duvarında yalnızca SSH ve web trafiğine izin verin:

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Genel uç noktayı curl -s https://directus.example.com/server/ping ile kontrol edin. Caddy sertifikayı ilk ziyarette alır ve otomatik olarak yeniler. Bunun yerine Nginx kullanmak için Nginx ve Certbot rehberine bakın; Traefik de çalışır.

Adım 5 — İlk yöneticiyi güvenceye alın

https://directus.example.com adresini açın. Varsayılan olarak kök adres /admin altındaki uygulamaya yönlendirir. ADMIN_EMAIL ve ADMIN_PASSWORD ile giriş yapın, ardından:

1. Kullanıcı profilinizi açın, yalnızca parola yöneticinizde bulunan yeni bir parola belirleyin ve iki adımlı doğrulamayı açın.
2. Yönetici girişini paylaşmak yerine erişmesi gereken diğer kişiler için uygun rollere sahip, isimli hesaplar oluşturun.

İki ADMIN_ değişkeni yalnızca Directus boş bir veritabanını kurarken işe yarar; sonradan değiştirmek hesabı değiştirmez. İki satırı da .env dosyasından ve compose.yaml içindeki environment bölümünden kaldırın, ardından konteyneri yeniden oluşturun:

docker compose up -d

Directus parola sıfırlama ve kullanıcı daveti e-postaları gönderir; bunları bir relay üzerinden göndermek için EMAIL_TRANSPORT değerini smtp yapın, directus servisinin environment bölümüne EMAIL_FROM, EMAIL_SMTP_HOST (örneğin smtp.example.com), EMAIL_SMTP_PORT (STARTTLS kullanan 587), EMAIL_SMTP_USER ve EMAIL_SMTP_PASSWORD değişkenlerini ekleyin ve docker compose up -d komutunu yeniden çalıştırın.

Yedekleme ve geri yükleme

Durum üç yerde tutulur: PostgreSQL veritabanı, uploads ve extensions klasörleri ve compose.yaml ile .env dosyalarınız (SECRET ve veritabanı parolası bunlarda). Veritabanını, Directus çalışmaya devam ederken tutarlı bir anlık görüntü alan PostgreSQL'in kendi aracıyla dökün ve dosyaları tarihli adlarla arşivleyin:

sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
chmod 700 /opt/backups
cd /opt/directus
docker compose exec -T database pg_dump -U directus -Fc directus > /opt/backups/directus-db-$(date +%F).dump
tar czf /opt/backups/directus-files-$(date +%F).tar.gz -C /opt/directus uploads extensions compose.yaml .env

Geri yüklemek için Directus'u durdurun, veritabanını yeniden oluşturun, dökümü yükleyin ve dosyaları açın. Tarihleri kendi yedeğinizinkilerle değiştirin:

cd /opt/directus
docker compose stop directus
docker compose exec -T database dropdb -U directus --force directus
docker compose exec -T database createdb -U directus directus
docker compose exec -T database pg_restore -U directus -d directus < /opt/backups/directus-db-2026-10-09.dump
tar xzf /opt/backups/directus-files-2026-10-09.tar.gz -C /opt/directus
docker compose up -d

Yeni bir sunucuda Docker'ı kurun, /opt/directus klasörünü oluşturun, önce dosya arşivini oraya açın (compose.yaml ve .env bunun içindedir), yalnızca veritabanını docker compose up -d database ile başlatın ve ardından geri yükleme komutlarını çalıştırın. Yedeklerinizi sunucunun dışına da kopyalayın ve zaman zaman bir geri yükleme deneyin.

Directus'u güncelleme

Directus daha yeni bir imaj başladığında veritabanı geçişlerini otomatik olarak uygular; bu da sürüm düşürmenin veritabanı geri yüklemesi gerektirdiği anlamına gelir. Her güncellemeden önce:

1. Sürümler sayfasındaki notları, özellikle "Potential Breaking Changes" bölümünü okuyun; Directus bu adımı kritik derecede önemli sayar, çünkü değişiklikler ortam değişkenlerini, API'leri, SDK'yı ve eklentileri etkileyebilir.
2. Yukarıdaki gibi yedek alın.

Ardından compose.yaml içindeki image: directus/directus: satırındaki etiketi yeni sürümle değiştirin ve uygulayın:

cd /opt/directus
nano compose.yaml
docker compose pull
docker compose up -d
docker compose logs -f directus

Geçişler bitip sunucu başlayana kadar logları izleyin, sonra giriş yapıp ana koleksiyonlarınızı ve eklentilerinizi test edin. postgis/postgis etiketindeki PostgreSQL ana sürümünü değiştirmeyin: yeni bir ana sürüme geçmek yalnızca yeni bir imaj değil, döküm ve geri yükleme gerektirir. docker compose pull, redis:7 imajını da kendi ana sürümü içinde yeniler.

Sorun giderme

Yüklemeler izin hatasıyla başarısız oluyor

Ana makinedeki uploads klasörü, konteyner içindeki node kullanıcısından farklı bir kullanıcı kimliğine ait; çoğu zaman Docker onu root olarak oluşturduğu için. docker compose exec directus id çıktısını ls -ln /opt/directus ile karşılaştırın ve sahibi Adım 3'te gösterildiği gibi sudo chown -R ile düzeltin.

Her yeniden başlatmadan sonra herkesin oturumu kapanıyor

SECRET ayarlanmamış; bu yüzden Directus her başlangıçta yeni bir rastgele değer üretiyor. Adım 1'deki gibi .env dosyasına sabit bir değer ekleyin ve konteyneri docker compose up -d ile yeniden oluşturun.

DB_PASSWORD değiştirildikten sonra Directus veritabanına bağlanamıyor

PostgreSQL POSTGRES_PASSWORD değerini yalnızca boş bir veri klasörünü ilk kez hazırlarken uygular; .env dosyasını sonradan değiştirmek veritabanında eski parolayı bırakır. Eski parolayı geri koyun ya da önce PostgreSQL içinde docker compose exec database psql -U directus -c "ALTER USER directus PASSWORD 'new-password';" ile değiştirip ardından .env dosyasını güncelleyin.

Veritabanı imajı ARM sunucuda çekilemiyor

Docker Hub, postgis/postgis imajını yalnızca amd64 için listeler; bu nedenle arm64 sunucu eşleşen bir manifest bulunmadığını bildirir. Bu yığın için x86-64 bir sunucu kullanın ya da coğrafi alanlara hiç ihtiyacınız yoksa ilk başlatmadan önce imajı resmi postgres:17 imajıyla değiştirin.

E-postalardaki bağlantılar veya giriş yönlendirmeleri yanlış adresi kullanıyor

PUBLIC_URL eksik, hâlâ bir yer tutucu değerde ya da http:// kullanıyor. Onu sitenizin tam https:// adresine ayarlayın ve docker compose up -d çalıştırın.

Sonraki adımlar

• Kod öncelikli bir headless CMS ile karşılaştırın: Strapi nasıl kurulur.
• Bu kurulumun arkasındaki Compose temellerini Docker Compose temelleri rehberinde tazeleyin.
• Directus projeleri için sunucu seçeneklerini Directus hosting sayfasında inceleyin.
• Depolama bağdaştırıcıları, e-posta ve ölçekleme için resmi Directus self-hosting belgelerini okuyun.