SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor · Güncellendi 2026-10-20

VPS üzerinde Docker ile Supabase kurulumu nasıl yapılır?

Resmi Supabase Docker yığınını kendi sunucunuzda çalıştırmanın yollarını öğrenin. Güvenlik için değiştirilmesi gereken gizli anahtarlar, RAM gereksinimleri ve güncelleme stratejileri.

Ne inşa ediyorsunuz

Supabase'i self-host etmek, resmi Docker Compose yığınını kendi sunucunuzda çalıştırmak anlamına gelir: Postgres, önünde bir REST API, bir kimlik doğrulama servisi, dosya depolama, gerçek zamanlı websockets ve Studio paneli. Bir depoyu klonlar, bir .env dosyasını düzenler ve kontrolünüz altındaki bir Supabase projesi gibi davranan on bir container başlatırsınız.

Kurulum kısadır. İşlerin ters gittiği nokta .env dosyasıdır. Bu dosya, depoda yayınlanan demo gizli anahtarlarıyla gelir ve bu varsayılan ayarlarla başlatılan bir yığın, onu bulan herkese açık hale gelir. Bu kılavuz, değiştirmeniz gereken gizli anahtarları, her servisin ne işe yaradığını, yığının gerçekte ne kadar belleğe ihtiyaç duyduğunu ve veritabanınızı silmeden nasıl güncelleyeceğinizi kapsar.

Eğer Compose sizin için yeniyse, önce VPS üzerinde Docker Compose temelleri konusunu okuyun. Aşağıdaki her şey, docker compose version komutunun halihazırda bir sürüm numarası döndürdüğünü varsayar.

Yığının gerçek içeriği

Supabase tek bir program değildir. Compose dosyası, tek bir ağ üzerinde bir dizi ayrı servisi başlatır. Hangi servisin ne işe yaradığını bilmek, karmaşık container isimlerini hata ayıklayabileceğiniz bir yapıya dönüştürür.

  • db, Supabase eklentileri yüklenmiş PostgreSQL'dir. Diğer tüm servisler onunla iletişim kurar. Bu container sağlıksız durumdaysa, diğer her şey başarısız olur.
  • api-gw, API ağ geçididir (gateway). Ağustos 2026 sürümünden itibaren Envoy çalıştırmaktadır; öncesinde kong adlı bir servis kullanılıyordu ve Kong, isteğe bağlı bir geçersiz kılma seçeneği olarak hala mevcuttur. 8000 numaralı portu dinler ve /rest/v1/, /auth/v1/ ile /storage/v1/ trafiğini ilgili arka uçlara yönlendirir. Dış dünyaya açmanız gereken tek container budur.
  • rest, PostgREST'tir. Postgres şemanızı okur ve bunu bir REST API olarak sunar; böylece yeni bir tablo, kod yazmaya gerek kalmadan yeni bir uç nokta (endpoint) haline gelir.
  • auth, GoTrue'dur. Kullanıcılarınızı tanımlayan JSON web token'larını (JWT) oluşturur.
  • storage ve imgproxy, dosya yükleme ve görüntü yeniden boyutlandırma işlemlerini yönetir.
  • realtime, veritabanı değişikliklerini websocket üzerinden yayınlar.
  • studio ve meta, kontrol paneli ve onun arkasındaki yönetici API'sidir.
  • functions, Deno tabanlı uç (edge) çalışma zamanıdır ve supavisor, Postgres bağlantı havuzlayıcısıdır (connection pooler).

Loglar ve analitik araçları (Logflare ve vector), Haziran 2026 itibarıyla varsayılan Compose dosyasından çıkarılmıştır. Bunlar artık birden fazla Compose dosyasından tek bir yığın çalıştırma bölümünde açıklanan yöntemle, sh run.sh config add logs kullanılarak etkinleştirilen isteğe bağlı bir ek dosya halindedir.

Aşağıdaki kaynak gereksinimlerinin bu seviyede olmasının nedeni bu listedir. Yalnızca bir veritabanı değil, bir veritabanı ve ona destek veren on farklı servis çalıştırıyorsunuz.

Boyutlandırma: 8 GB RAM için plan yapın

Temmuz 2026 itibarıyla, kendi verileriniz veya trafiğiniz eklenmeden önce, temiz bir kurulumda yığın (stack) yaklaşık 2,5 ila 3 GB yerleşik bellek tüketmektedir. Bu ölçümde, analitik servisi ve Studio Node.js süreci en büyük iki tüketici konumundaydı. Analitik artık varsayılan yığının bir parçası değildir; bu nedenle yalnızca günlük geçersiz kılma (logs override) özelliğini açarsanız bellek tüketir. 2 GB RAM'e sahip bir sunucu, container'ları başlatacak ancak ardından çekirdeğin bellek yetersizliği (out of memory killer) mekanizması nedeniyle birini kaybedecektir; bu durum, container'ın 137 çıkış koduyla sürekli yeniden başlatılmasıyla kendini gösterir. Ekim 2026'da kontrol edilen Supabase'in kendi self-hosting belgeleri, minimum gereksinim olarak 4 GB RAM, 2 CPU çekirdeği ve 40 GB SSD; önerilen olarak ise 8 GB RAM, 4 çekirdek ve 80 GB SSD belirtmektedir.

Güvendiğiniz her türlü iş yükü için 8 GB RAM ve 4 vCPU tahsis edin. 4 GB, ağır bir sorgu ile bir Studio oturumunun aynı anda yavaş çalışacağını kabul ederseniz, tek kişilik bir geliştirme örneği için yeterli olabilir. Disk alanı da önemlidir; çünkü Postgres, depolama birimi ve günlükleri etkinleştirirseniz günlük verilerinin tamamı proje dizini altında tutulur. 40 GB ile başlayın ve kullanımı izleyin. Bir plan seçmeden önce servisleri saymak, self-host ettiğiniz her şey için edinilmesi gereken iyi bir alışkanlıktır; çünkü PhotoPrism ve Immich gibi uygulamaların da ciddi RAM alt sınırları vardır: Ekim 2026'da kontrol edilen Immich hızlı başlangıç sayfası, en az 6 GB RAM ve 2 CPU çekirdeği talep etmektedir. Eğer bu, projenizin henüz ihtiyaç duyduğundan daha büyük bir sunucuysa, Supabase'in ücretsiz bulut planının neleri içerdiğini inceleyin; 500 MB sınırının altında kalan ve bir hafta boyunca boşta kalmayan küçük bir uygulama, orada ücretsiz olarak çalışabilir.

Kurulum: resmi depoyu klonlayın

Desteklenen yöntem, docker dizinini ana depodan kendi proje dizininize kopyalar. Bu ayrım önemlidir; çünkü daha sonra yapılacak bir git pull işlemi, .env dosyanızın üzerine yazamaz.

git clone --depth 1 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/* supabase-project
cp supabase/docker/.env.example supabase-project/.env
cd supabase-project
docker compose pull

docker compose pull komutu birkaç gigabaytlık imaj indirir. İşlem, her servisin Pulled olarak işaretlenmesiyle tamamlanmalıdır. Burada alınan bir manifest unknown hatası, sabitlenmiş imaj etiketinin yukarı akışta (upstream) kaldırıldığı anlamına gelir; bu durumda çözüm, etiketleri elle düzenlemek yerine deponun daha yeni bir kopyasını çekmektir.

İlk başlatmadan önce değiştirmeniz gereken gizli bilgiler

Bunu stack'i başlatmadan önce yapın, başlattıktan sonra değil. Bu değerlerin birçoğu ilk açılışta verilere yazılır, bu nedenle bunları daha sonra değiştirmek veritabanını sıfırlamanız gerektiği anlamına gelir.

Depo, iki API anahtarı dahil olmak üzere her değeri yeni JWT gizli anahtarınızla imzalanmış şekilde doğru biçimde üreten bir oluşturucu içerir.

sh utils/generate-keys.sh --update-env

Bu betik; JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY, SECRET_KEY_BASE, REALTIME_DB_ENC_KEY, VAULT_ENC_KEY, PG_META_CRYPTO_KEY, Logflare token'ları, S3 protokol anahtarları ve MINIO_ROOT_PASSWORD için yeni değerleri .env dosyasına yazar. Ekim 2026 itibarıyla, POSTGRES_PASSWORD ve DASHBOARD_PASSWORD için de rastgele değerler atar. Herhangi bir standart Ubuntu imajında bulunan openssl aracına ihtiyaç duyar. Artık veritabanı parolasını da yeniden yazdığı için, bu betiği yalnızca ilk başlatmadan önce --update-env ile çalıştırın; verilerin zaten mevcut olduğu bir stack üzerinde asla çalıştırmayın.

.env dosyasında manuel olarak kontrol etmeye değer iki değer daha vardır:

  • POSTGRES_PASSWORD. Betik buraya rastgele onaltılık (hex) değerler atar, bu güvenlidir. Eğer kendi değerinizle değiştirecekseniz, yalnızca harf ve rakam kullanın. Buradaki noktalama işaretleri, çeşitli servislerin dizeleri birleştirerek oluşturduğu bağlantı dizgilerini bozar. Oluşan hata, ayrıştırma hatası yerine kimlik doğrulama hatası gibi görünür; bu da kullanıcıları yanlış yerde arama yapmaya yönlendirir.
  • DASHBOARD_USERNAME ve DASHBOARD_PASSWORD. Bunlar Studio için temel kimlik doğrulama bilgileridir. Betik rastgele bir parola atar ancak kullanıcı adını varsayılan supabase değerinde bırakır. Varsayılan parola kelimesi this_password_is_insecure_and_should_be_updated şeklindedir, bu yüzden betiği atladıysanız şimdi değiştirin.

ANON_KEY ve SERVICE_ROLE_KEY değerlerinin neden rastgele belirlenemeyeceğini anlayın. Her ikisi de JWT_SECRET ile imzalanmış JWT'lerdir. Ağ geçidi (gateway) yalnızca .env içindeki tam anahtarları kabul eder ve arkasındaki servisler imzayı JWT_SECRET ile doğrular; bu nedenle eşleşmeyen bir anahtar HTTP 401 hatasıyla reddedilir. Varsayılan Envoy ağ geçidi 401 Unauthorized yanıtını verir; Kong 3.9 çalıştıran mevcut Kong geçersiz kılma (override) ayarı da {"message":"Unauthorized"} yanıtını döndürür. Mart 2026 öncesindeki kurulumlar, {"message":"Invalid authentication credentials"} yanıtını veren Kong 2.8 kullanıyordu. Bu, en yaygın self-hosting hatasıdır: operatör JWT_SECRET değerini değiştirmiş ancak demo anahtarlarını tutmuştur. Her üçünü de her zaman birlikte oluşturun.

SERVICE_ROLE_KEY değerine root parolası gibi davranın. Bu değer, satır düzeyi güvenliği (row level security) tamamen devre dışı bırakır. Yalnızca sunucu tarafındaki kodda bulunmalıdır, başka hiçbir yerde değil.

SITE_URL değerini uygulamanızın adresine, API_EXTERNAL_URL değerini ise sonuna /auth/v1 eklenmiş şekilde API'nin genel adresine ayarlayın; örneğin https://supabase.example.com/auth/v1. SUPABASE_PUBLIC_URL değerini, yol (path) bilgisi olmadan aynı genel adrese ayarlayın. Auth servisi, e-posta doğrulama ve OAuth geri çağırma bağlantılarını bu değerlerden oluşturur; bu yüzden bunları localhost varsayılanlarında bırakmak, tüm kullanıcılarınızı kendi makinelerine yönlendirmenize neden olur.

Ardından elinizdekileri kontrol edin:

sh run.sh secrets

Servisi başlatın ve sağlıklı çalıştığını doğrulayın

sh run.sh start
docker compose ps

run.sh start, docker compose up -d --wait komutunu sarmalar; bu nedenle sağlık kontrolleri geçene kadar işlem sonlanmaz. Her servis running (healthy) veya running durumunu göstermelidir. Postgres, diğer servisler bağlanmadan önce başlatma betiklerini çalıştırdığı için ilk açılış iki ila dört dakika sürer.

Eğer bir container sürekli yeniden başlatılıyorsa, servis adına göre log kayıtlarını inceleyin:

docker compose logs db
docker compose logs auth

Studio bu aşamadan sonra 8000 numaralı port üzerinde erişilebilir durumdadır ve belirlediğiniz dashboard kullanıcı adı ile parolasını isteyecektir.

8000 numaralı portu genel internete açmayın

8000 numaralı port üzerindeki ağ geçidi, şifrelenmemiş HTTP protokolünü kullanır. Tüm API anahtarları ve kullanıcı parolaları ağ üzerinden açık metin olarak iletilir. Studio kimlik bilgileri ise şifreleme değil, yalnızca base64 kodlaması kullanan temel kimlik doğrulama (basic authentication) yöntemine dayanır.

Bu servisin önüne bir reverse proxy yerleştirin, TLS (transport layer security) sonlandırma işlemini burada yapın ve ağ geçidini yalnızca loopback adresine bağlayarak dış erişimi engelleyin. docker-compose.yml içerisinde api-gw servisi altındaki port satırı 127.0.0.1:${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}}:8000/tcp şeklinde güncellenmeli ve proxy yönlendirmesi buna göre yapılmalıdır. Ağustos 2026'da Envoy'a geçişten önceki kurulumlarda, aynı port satırı kong adlı servisin altında yer alır. Birden fazla Compose uygulaması önünde Traefik rehberi, sertifika tarafındaki yapılandırmayı ele almaktadır. Aynı proxy, sunucudaki diğer tüm servislerin önünde konumlandırılarak; bu yığından 90'ların video dükkanı konseptiyle yeniden oluşturulmuş bir Jellyfin kütüphanesi gibi daha basit servislere kadar her biri için yeni bir port açmak yerine alan adı üzerinden erişim sağlar. Eğer bir panel yalnızca sizin kullanımınız içinse, proxy kullanmak yerine loopback portuna bir SSH tüneli üzerinden erişmeyi tercih edin; self-hosted open-kritt uygulaması, tarama arayüzünü tamamen genel internete kapatmak için aynı yöntemi kullanır.

Ayrıca güvenlik duvarı üzerinden diğer portları da kapatın; çünkü Docker, kendi iptables kurallarını yazarak portları dış dünyaya açar ve bu kurallar standart bir ufw yapılandırması tarafından görülmez. Bu durumun yarattığı risk Docker container'larının ufw kurallarınızı neden görmezden geldiği başlıklı yazıda açıklanmıştır.

Veritabanını yedekleyin, dizini değil

Postgres verileri ./volumes/db/data yolundaki bir bind mount içerisinde tutulur. Container çalışırken bu dizini kopyalamak, tutarsız bir kopyaya yol açar; çünkü Postgres yazma işlemlerini önbelleğe alır ve disk üzerindeki dosyalar yalnızca bir checkpoint anında tutarlı hale gelir. Bu yedeği geri yüklemek genellikle çalışsa da bazen son işlemleri sessizce kaybetmenize neden olabilir; bu da bir yedekleme için olabilecek en kötü hata senaryosudur.

Bunun yerine dump alın. pg_dumpall komutu container içerisinde çalışır ve tutarlı bir anlık görüntü oluşturur:

docker exec -t supabase-db pg_dumpall -U postgres > supabase-$(date +%F).sql

Yedeğe güvenmeden önce dosyanın boş olmadığını doğrulayın. Ardından bu dump dosyalarını belirli bir zaman çizelgesine göre sunucudan dışarı aktarın; restic ile şifreli uzak yedekleme bu işlem içindir. Sessizce başarısız olan zamanlanmış bir dump, hiç yedek almamakla aynıdır; bu nedenle cron veya systemd göreviniz sıfır olmayan bir çıkış kodu döndürdüğünde telefonunuza bildirim göndermesini sağlayın. Aynı zamanda .env dosyanızı da yedekleyin. JWT_SECRET dosyasını kaybetmek, verilen tüm token'ların geçersiz kalması ve saklanan tüm şifreli sırların okunamaması anlamına gelir.

Yüklenen dosyalar ./volumes/storage dizininde bulunur ve bunlar standart dosyalar olduğu için doğrudan kopyalanmaları yeterlidir.

Veri kaybı olmadan güncelleme

Supabase, imaj sürümlerini docker-compose.yml içerisinde sabitler; bu sayede siz müdahale etmediğiniz sürece hiçbir şey değişmez. Sürüm sabitleme, manuel olarak oluşturduğunuz her yığın (stack) için uygulanması gereken bir yöntemdir. Kendi kendine barındırılan bir RustDesk relay sunucusunun, değişken etiketler (moving tags) yerine iki sunucu imajını sabitlemesinin nedeni budur: yükseltme işlemi, vaktinizin olduğu bir sabah kendi tercihinizle yapacağınız bir eylem olmalıdır. Her seferinde önce bir dump (yedek) alın.

docker compose pull
sh run.sh recreate

recreate komutu yığını durdurur ve yeni imajlarla yeniden başlatır. Verileriniz container içinde değil, ana makine üzerindeki bind mount noktalarında yaşadığı için korunur. Büyük bir sürüm atlaması yapmadan önce depodaki CHANGELOG.md dosyasını okuyun; çünkü Postgres ana sürüm yükseltmesi, recreate tarafından gerçekleştirilmeyen ayrı bir adımdır. Postgres 17, Haziran 2026'dan beri varsayılan sürümdür. Postgres 15 üzerindeki mevcut bir kurulum, sudo bash utils/upgrade-pg17.sh kullanılarak bu sürüme taşınır. Bu araç, verileri yerinde taşımak için pg_upgrade kullanır ve her ana adımda onay ister. Bu işlem için tüm container'ların çalışıyor olması ve veritabanı boyutunuzun en az iki katı artı 5 GB boş disk alanına sahip olmanız gerekir. Supabase, işleme başlamadan önce kendi bağımsız yedeğinizi almanızı yine de önerir.

Compose dosyasındaki değişiklikleri uygulamak için proje dizininden sh update.sh komutunu çalıştırın veya nelerin değişeceğini önceden görmek için sh update.sh --dry-run komutunu kullanın. Bu komut, yukarı akış (upstream) dosyalarını sizin düzenlemelerinizle birleştirir; .env içindeki mevcut değerlerin üzerine asla yazmaz (yalnızca yeni anahtarlar ekler) ve yazma işleminden önce yapılandırmanızı backups/ altında arşivler (veritabanı hariç). .supabase-version dosyası olmayan bir kurulum, --from ve başlangıçta kullanılan sürümü gerektirir. Bu durum, özellikle kong servisini api-gw ile değiştiren ve docker-compose.yml güncellemesi gerektiren Ağustos 2026 sürümü için önemlidir. Manuel yöntem de hala geçerlidir: yukarı akış deposunu tekrar klonlayın ve .env dosyasının üzerine yazmamaya dikkat ederek docker dizinini projenizin üzerine kopyalayın.

Veritabanı dahil her şeyi yok eden ve .env dosyasını varsayılan ayarlara döndüren (eskisi .env.old olarak saklanır) tam sıfırlama işlemi ayrı bir betiktir ve onay ister:

sh reset.sh

FAQ

API çağrılarım neden "Invalid authentication credentials" hatası veriyor?

Bu hata mesajı, Mart 2026 öncesindeki kurulumlarda kullanılan Kong 2.8 ağ geçidinden kaynaklanmaktadır. Varsayılan Envoy ağ geçidi ve Kong 3.9 çalıştıran güncel Kong yapılandırması, aynı sorunu basit bir 401 Unauthorized hatası olarak raporlar. Her iki durumda da gönderdiğiniz anahtar, .env içindeki ANON_KEY veya SERVICE_ROLE_KEY ile eşleşmiyordur ya da bu anahtarlar .env içinde bulunan JWT_SECRET ile imzalanmamıştır. Henüz veri içermeyen bir yığında, üçünü birden sh utils/generate-keys.sh --update-env ile yeniden oluşturun. Çalışan bir yığında ise betiği bayrak kullanmadan çalıştırın ve hayır yanıtını verin; böylece sadece yeni değerleri yazdırır. Ardından JWT_SECRET, ANON_KEY ve SERVICE_ROLE_KEY değerlerini manuel olarak .env içine kopyalayın ve POSTGRES_PASSWORD kısmına dokunmayın. Son olarak servislerin yeni değerleri okuması için sh run.sh recreate komutunu çalıştırın.

2 GB RAM kapasiteli bir VPS üzerinde self-hosted Supabase çalıştırabilir miyim?

Güvenilir bir şekilde çalışmaz. Supabase'in kendi self-hosting belgeleri, Ekim 2026 itibarıyla minimum 4 GB RAM önermektedir. Temmuz 2026'da yapılan ölçümlerde, artık isteğe bağlı olan günlükleme servisleri dahil edildiğinde yığının boşta yaklaşık 3 GB RAM tükettiği görülmüştür. 2 GB kapasiteli bir sunucuda konteynerler "out of memory killer" tarafından sonlandırılır ve docker compose ps içinde 137 çıkış kodunu görürsünüz. Üretim ortamı için 8 GB kullanın, bireysel geliştirme için ise 4 GB'ı alt sınır olarak kabul edin.

Self-hosted Supabase edge functions içeriyor mu?

Evet. Compose dosyası, Deno tabanlı functions çalışma zamanını içerir ve ./volumes/functions altına yerleştirdiğiniz her şeyi servis eder. Barındırılan platformun küresel dağıtım ağını içermediği için fonksiyonlarınız tek bir sunucuda ve tek bir konumda çalışır.

Postgres veritabanına doğrudan nasıl bağlanırım?

Sunucu üzerinde etkileşimli bir kabuk için docker exec -it supabase-db psql -U postgres kullanın. Harici bir istemci için, 5432 numaralı port üzerinden Supavisor aracılığıyla, postgres.<POOLER_TENANT_ID> kullanıcısı ve POSTGRES_PASSWORD parolanız ile bağlanın. Bu portu internete açmayın. Bağlantıyı bir VPN veya SSH tüneli üzerinden sağlayın.

Kimlik doğrulama onay e-postalarım neden localhost adresine yönlendiriyor?

.env içindeki SITE_URL ve API_EXTERNAL_URL değerleri varsayılan ayarlarında bırakılmıştır. Kimlik doğrulama servisi, tüm onay ve parola sıfırlama bağlantılarını bu iki değere göre oluşturur; dolayısıyla kendisine belirtilen adresi gönderir. Her iki değeri de gerçek genel URL adresinizle güncelleyin ve yığını yeniden oluşturun.

Bu yazı işinize yaradı mı?