Strapi 5 PostgreSQL, PM2 ve HTTPS ile nasıl kurulur

Strapi, Node.js üzerine kurulu açık kaynaklı bir headless CMS'tir. Editörler içeriği bir yönetim panelinde düzenler; web siteleriniz ve uygulamalarınız bu içeriği REST veya GraphQL API'leriyle okur. Bu rehber Strapi 5'i tek bir sunucuda üretim için çalıştırır: veritabanı olarak PostgreSQL, NodeSource deposundan Node.js LTS, ayrı ve root olmayan bir kullanıcı altında süreç yöneticisi olarak PM2 ve otomatik HTTPS için önde Caddy. Ayrıca Strapi'nin beklediği geliştirmeden üretime iş akışını, yedeklemeyi, güncellemeyi ve sorun gidermeyi de kurarsınız.

Adım 1 — PostgreSQL'i kurun ve veritabanını oluşturun

PostgreSQL'i dağıtımınızın arşivinden kurun ve servisin çalıştığını kontrol edin:

sudo apt update
sudo apt install postgresql
sudo systemctl status postgresql --no-pager

Ubuntu ve Debian'da PostgreSQL varsayılan olarak yalnızca localhost üzerinde dinler; bu nedenle güvenlik duvarı kuralı gerekmez. Veritabanı kullanıcısı için güçlü bir parola üretin ve Adım 3 için saklayın:

openssl rand -hex 24

Bir strapi rolü (istendiğinde parolayı yapıştırın), bu role ait bir veritabanı oluşturun ve Strapi belgelerinin istediği şema iznini verin. GRANT olmadan yeni bir veritabanı kullanıcısı public şemasında tablo oluşturamaz ve yönetim paneli 500 hatası döndürür:

sudo -u postgres createuser --pwprompt strapi
sudo -u postgres createdb --owner=strapi strapi
sudo -u postgres psql -d strapi -c "GRANT ALL ON SCHEMA public TO strapi;"

Girişi, Strapi'nin bağlanacağı gibi TCP üzerinden test edin. Parolayı girdikten sonra sorgu strapi yazar:

psql -h 127.0.0.1 -U strapi -d strapi -c "SELECT current_user;"

Adım 2 — Node.js LTS'i ve PM2'yi kurun

Bu sürümlerin çoğunda dağıtımın kendi nodejs paketi, Strapi'nin desteklediği en eski hat olan Node.js 22'den eskidir. İki yaygın seçenek vardır: Node.js'i kullanıcı başına bir ev dizinine kuran ve sürümleri sık değiştirdiğiniz geliştirme makinesinde pratik olan nvm ile tek ve sistem genelinde bir Node.js'i /usr/bin altına kuran ve diğer güvenlik güncellemelerinizle birlikte apt ile güncelleyen NodeSource apt deposu. Uzun süre çalışan bir servisi barındıran sunucuda apt deposu güncel tutması daha kolaydır ve bir kabuk profiline bağlı değildir; bu nedenle bu rehber NodeSource kullanır.

NodeSource'un elle kurulumu, dağıtımdan bağımsız nodistro adlı bir suite kullanır. İmza anahtarını ve Node.js 24 LTS deposunu ekleyin:

sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

NODE_MAJOR=24
sudo tee /etc/apt/sources.list.d/nodesource.sources <<EOF
Types: deb
URIs: https://deb.nodesource.com/node_${NODE_MAJOR}.x/
Suites: nodistro
Components: main
Signed-By: /etc/apt/keyrings/nodesource.gpg
EOF
sudo apt update
sudo apt install nodejs
node -v
npm -v

node -v bir v24 sürümü yazmalıdır. Şimdi PM2'yi global olarak kurun; böylece pm2 komutu her kullanıcının yolunda olur ve açılış betiği onu bulabilir:

sudo npm install -g pm2
pm2 --version

Adım 3 — strapi kullanıcısını ve projeyi oluşturun

Strapi'yi hiçbir zaman root olarak değil, kendi sistem kullanıcısıyla çalıştırın. Kullanıcının ev dizini /srv/strapi, projeyi ve PM2'nin durum dosyalarını tutar:

sudo adduser --system --group --home /srv/strapi --shell /bin/bash strapi
sudo -iu strapi

Artık strapi olarak bir kabuktasınız. Projeyi resmi create-strapi aracıyla oluşturun. Parametreler etkileşimli soruları önceden yanıtlar: Strapi Cloud girişini atlar, npm ve JavaScript kullanır, bağımlılıkları kurar, bir Git deposu başlatır, örnek veriyi ve anonim A/B testlerini atlar ve Adım 1'deki PostgreSQL veritabanına bağlanır. change-me yerine ürettiğiniz parolayı yazın:

cd /srv/strapi
npx create-strapi@latest app --skip-cloud --no-run --javascript --use-npm --install --no-example --git-init --no-enable-ab-tests --dbclient=postgres --dbhost=127.0.0.1 --dbport=5432 --dbname=strapi --dbusername=strapi --dbpassword=change-me

npx bir kez create-strapi paketini indirip indiremeyeceğini sorar; y yanıtını verin. Parametrelerin kapsamadığı soruları da yanıtlayın. Ekibiniz TypeScript tercih ediyorsa --javascript yerine --typescript kullanın; bu durumda Adım 4'teki yapılandırma dosyası config/server.ts olur ve module.exports yerine export default kullanır. Komut bitince projeyi listeleyin:

cd /srv/strapi/app
ls -a

config, src, public, package.json ve bir .env dosyası görmelisiniz.

Adım 4 — Üretim ayarlarını yapılandırın

create-strapi, APP_KEYS, API_TOKEN_SALT, ADMIN_JWT_SECRET, TRANSFER_TOKEN_SALT, JWT_SECRET ve ENCRYPTION_KEY için yeni üretilmiş değerlerle ve veritabanı ayarlarıyla bir .env dosyası yazar. Gizli değerleri ekrana basmadan yalnızca ortam değişkeni adlarını listeleyin:

cut -d= -f1 .env

Dosyayı nano .env ile açın ve şu satırları içerdiğinden emin olun. Strapi'yi yalnızca Caddy erişebilsin diye 127.0.0.1 adresine bağlayın, genel adresinizi girin ve isterseniz telemetriyi kapatın:

HOST=127.0.0.1
PORT=1337
PUBLIC_URL=https://cms.example.com
APP_KEYS=generated-value-1,generated-value-2,generated-value-3,generated-value-4
API_TOKEN_SALT=generated-value
ADMIN_JWT_SECRET=generated-value
TRANSFER_TOKEN_SALT=generated-value
JWT_SECRET=generated-value
ENCRYPTION_KEY=generated-value
DATABASE_CLIENT=postgres
DATABASE_HOST=127.0.0.1
DATABASE_PORT=5432
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=change-me
DATABASE_SSL=false
STRAPI_TELEMETRY_DISABLED=true

Bir gizli değer eksikse (örneğin .env dosyası Git'te olmayan mevcut bir projeyi klonladıysanız) her değeri openssl rand -base64 32 ile üretin; APP_KEYS virgülle ayrılmış birkaç değer alır. Ardından dosyayı yalnızca sahibinin okuyabileceği hale getirin:

chmod 600 .env

Sonra Strapi'ye genel adresini ve tek bir reverse proxy arkasında çalıştığını bildirin. config/server.js dosyasını nano config/server.js ile açın ve içeriğini şununla değiştirin:

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  url: env('PUBLIC_URL', 'https://cms.example.com'),
  proxy: {
    koa: true,
    maxIpsCount: 1,
  },
  app: {
    keys: env.array('APP_KEYS'),
  },
});

proxy.koa: true, Strapi'nin Caddy'nin gönderdiği X-Forwarded-* başlıklarına güvenmesini sağlar; maxIpsCount: 1 bu güveni tam olarak tek bir proxy ile sınırlar. Strapi'nin Caddy rehberi, maxIpsCount ayarlanmazsa sayının sınırsız kabul edildiğini belirtir. Bu dosyadaki değişiklikler yönetim panelinin yeniden derlenmesini gerektirir; bunu bir sonraki adımda yaparsınız.

Adım 5 — Derleyin, PM2 ile başlatın ve ilk yöneticiyi oluşturun

Yönetim panelini derleyin. NODE_ENV değişkenini yalnızca derleme komutunun kendisinde verin: Strapi'nin PM2 rehberi, bunu tüm oturum için dışa aktarmanın npm'in derlemenin ihtiyaç duyduğu geliştirme bağımlılıklarını atlamasına yol açtığını belirtir.

NODE_ENV=production npm run build

PM2 yapılandırmasını /srv/strapi/app içinde nano ecosystem.config.js ile oluşturun:

module.exports = {
  apps: [
    {
      name: 'strapi',
      cwd: '/srv/strapi/app',
      script: 'npm',
      args: 'start',
      env: {
        NODE_ENV: 'production',
      },
    },
  ],
};

npm start, otomatik yeniden yükleme olmadan çalışan üretim modu strapi start komutunu çalıştırır. Uygulamayı başlatın ve Strapi hazır olduğunda HTTP/1.1 204 No Content döndüren sağlık uç noktasını kontrol edin:

pm2 start ecosystem.config.js
pm2 list
curl -I http://127.0.0.1:1337/_health

Bir yönetici oluşana kadar /admin sayfası, onu açan herkese bir kayıt formu gösterir. Site herkese açılmadan önce ilk yöneticiyi komut satırından oluşturun. Komutu parametresiz çalıştırın ve ad, e-posta ve parola sorularını yanıtlayın:

npx strapi admin:create-user

Şimdi PM2'nin açılışta başlamasını sağlayın. strapi kabuğundan çıkın, strapi kullanıcısı için systemd birimini üretin ve mevcut süreç listesini kaydedin:

exit
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u strapi --hp /srv/strapi
sudo -iu strapi pm2 save
systemctl status pm2-strapi --no-pager

Birimin adı pm2-strapi'dir ve active görünmelidir. Bir uygulama eklediğinizde veya adını değiştirdiğinizde pm2 save komutunu yeniden çalıştırın. Son olarak, Strapi'nin PM2 rehberinin önerdiği gibi PM2'nin kendi loglarının diski doldurmasını önleyin:

sudo -iu strapi pm2 install pm2-logrotate
sudo -iu strapi pm2 set pm2-logrotate:max_size 10M
sudo -iu strapi pm2 set pm2-logrotate:retain 7

Adım 6 — Strapi'yi Caddy ile HTTPS üzerinden yayınlayın

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. Caddy sertifikayı kendisi alır ve yeniler:

cms.example.com {
    reverse_proxy 127.0.0.1:1337
}

sudo systemctl reload caddy

Güvenlik duvarında yalnızca SSH ve web trafiğine izin verin. Strapi yalnızca 127.0.0.1 üzerinde dinlediği için 1337 portu kapalı kalır:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ss -tlnp | grep 1337

Son komut 0.0.0.0:1337 değil, 127.0.0.1:1337 göstermelidir. Genel uç noktayı curl -I https://cms.example.com/_health ile kontrol edin, ardından https://cms.example.com/admin adresini açıp Adım 5'teki hesapla giriş yapın. Nginx mi tercih ediyorsunuz? Aynı hedefle Nginx ve Certbot rehberini kullanın; Traefik de çalışır.

Adım 7 — İçerik türlerini geliştirmede değiştirin, sonra dağıtın

Sunucuda Strapi, Content-Type Builder'ın kapalı olduğu üretim modunda çalışır. Strapi'nin SSS sayfası nedenini açıklar: şemalar src/api/article/content-types/article/schema.json gibi dosyalardır ve değiştirilmeleri yeniden başlatma gerektirir. Sunucuyu bir dağıtım hedefi olarak kullanın:

1. Projeyi özel bir Git deposuna gönderin. Strapi'nin ürettiği .gitignore dosyası .env ve node_modules dosyalarını dışarıda bırakmalıdır; git check-ignore .env ile doğrulayın.
2. Projeyi iş istasyonunuza klonlayın, npm install ve npm run develop çalıştırın ve içerik türlerini orada tasarlayın veya değiştirin.
3. Commit edin, gönderin ve sunucuda dağıtın.

Sunucudaki kopyayı deponuza bağlamak için /srv/strapi/app içinde strapi olarak şunları çalıştırın (strapi kullanıcısının depoyu okuyabilmesi gerekir, örneğin salt okunur bir deploy anahtarıyla):

git status
git remote add origin [email protected]:team/cms.git
git push -u origin HEAD

Her dağıtım bundan sonra şöyle görünür:

sudo -iu strapi
cd /srv/strapi/app
git pull
npm ci
NODE_ENV=production npm run build
pm2 restart strapi --update-env

Strapi başlarken veritabanı şemasını senkronize eder; kaldırılan bir alan, kaldırılan veri demektir. Şema değişikliklerini dağıtmadan önce yedek alın.

Yedekleme ve geri yükleme

Durumu üç şey tutar: PostgreSQL veritabanı, public/uploads içindeki yüklenen dosyalar (varsayılan yerel yükleme sağlayıcısı) ve .env içindeki gizli değerler. Kodun kendisi Git'te durur. Özel bir yedek klasörü oluşturun ve her şeyi tarihli adlarla dökün:

sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
chmod 700 /opt/backups
sudo -u postgres pg_dump -Fc strapi > /opt/backups/strapi-db-$(date +%F).dump
sudo tar czf /opt/backups/strapi-files-$(date +%F).tar.gz -C /srv/strapi/app public/uploads .env

pg_dump, Strapi çalışmaya devam ederken tutarlı bir anlık görüntü üretir. Strapi'nin kendi strapi export komutu içeriği ortamlar arasında taşımak için kullanışlıdır; ancak yönetici kullanıcıları ve API token'larını içermez, bu yüzden yedeğin yerini tutmaz, ona eklenir. İsterseniz strapi olarak çalıştırın (arşiv şifrelenmemiştir; onu veritabanı dökümü kadar dikkatli saklayın):

sudo -iu strapi
cd /srv/strapi/app
npm run strapi export -- --no-encrypt -f /srv/strapi/export-$(date +%F)
exit

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

sudo -iu strapi pm2 stop strapi
sudo -u postgres dropdb strapi
sudo -u postgres createdb --owner=strapi strapi
sudo -u postgres pg_restore -d strapi < /opt/backups/strapi-db-2026-10-09.dump
sudo tar xzf /opt/backups/strapi-files-2026-10-09.tar.gz -C /srv/strapi/app
sudo chown -R strapi:strapi /srv/strapi/app/public/uploads /srv/strapi/app/.env
sudo -iu strapi pm2 start strapi

Yeni bir sunucuda önce Adım 1–3'ü çalıştırın (proje oluşturmak yerine deponuzu klonlayarak), sonra geri yükleyin. Yedekleri sunucunun dışına da kopyalayın, örneğin rsync ile başka bir makineye; ara sıra bir geri yükleme denemesi yapın.

Strapi'yi güncelleme

Strapi'yi sunucuda değil geliştirme ortamında yükseltin; çünkü resmi yükseltme aracı kodunuzu düzenler. Önce sürüm notlarını okuyun ve yedek alın. Geliştirme kopyanızda değişiklikleri önce deneme çalıştırmasıyla görün, sonra uygulayın:

npx @strapi/upgrade minor --dry
npx @strapi/upgrade minor

patch ve minor mevcut ana sürümünüz içinde kalır. major bir sonraki ana sürüme geçer, ancak mevcut ana sürümün en son minor ve patch sürümünde olmanızı ister; latest bir onaydan sonra ana sürümleri de aşabilir. Araç bağımlılıkları günceller ve codemod'ları çalıştırır; veri taşımaz. Değişiklikleri inceleyin, npm run develop ile test edin, commit edin ve Adım 7'deki rutinle dağıtın.

Node.js yama sürümleri sudo apt update && sudo apt upgrade ile gelir. Yeni bir Node.js ana hattına geçmek için depo dosyasındaki NODE_MAJOR değerini Strapi'nin desteklediği başka bir sürüme çevirin, yükseltin, yeniden derleyin ve PM2 belgelerinin önerdiği gibi PM2'nin açılış betiğini yeniden üretin: pm2 unstartup çalıştırın, ardından Adım 5'teki pm2 startup komutunu tekrarlayın. PM2'nin kendisini sudo npm install -g pm2 ile güncelleyin, sonra strapi olarak pm2 update çalıştırın.

Sorun giderme

Yeni kurulumda yönetim paneli 500 hatası döndürüyor

Veritabanı kullanıcısı public şemasında tablo oluşturamıyor. Adım 1'deki GRANT ALL ON SCHEMA public TO strapi; komutunu çalıştırın, ardından strapi kullanıcısıyla pm2 restart strapi komutunu verin.

Derleme JavaScript heap out of memory hatasıyla duruyor veya süreç sonlandırılıyor

Yönetim paneli derlemesi boştaki bellekten fazlasına ihtiyaç duyuyor. Diğer ağır süreçleri durdurun, geçici bir swap dosyası ekleyin veya Strapi'nin önerdiği en az 4 GB belleğe sahip bir sunucuya geçin. Bellek yetersizliğinden sonlandırılan süreçler için free -h ve dmesg | tail çıktısına bakın.

Sunucuda Content-Type Builder kapalı

Üretim modunda bu beklenen davranıştır. İçerik türlerini bir geliştirme kopyasında oluşturup değiştirin ve Adım 7'de anlatıldığı gibi dağıtın.

Yönetim paneli istekleri localhost'a veya düz HTTP'ye gidiyor

PUBLIC_URL eksik veya yanlış ya da yönetim paneli config/server.js değiştirilmeden önce derlenmiş. .env dosyasını ve url ayarını düzeltin, NODE_ENV=production npm run build ile yeniden derleyin ve pm2 restart strapi --update-env çalıştırın.

Strapi yeniden başlatmadan sonra geri gelmiyor

Açılış birimi eksik veya süreç listesi kaydedilmemiş. systemctl status pm2-strapi ile kontrol edin, Adım 5'teki pm2 startup ve pm2 save komutlarını tekrarlayın ve logları strapi olarak pm2 logs strapi --lines 100 ile okuyun.

Sonraki adımlar

• Başka bir self-hosted headless CMS ile karşılaştırın: Directus nasıl kurulur.
• Otomatik HTTPS hakkında daha fazlasını Caddy reverse proxy rehberinde öğrenin.
• Strapi projeleri için sunucu seçeneklerini Strapi hosting sayfasında inceleyin.
• Cluster modu ve yüklemeler için nesne depolama gibi ileri konular için Strapi'nin dağıtım belgelerini okuyun.