Başlarken

VeloCMS, Docker'ın çalıştığı her yerde çalışır; ister aylık 6 dolarlık bir VPS olsun, ister bir Railway servisi, isterseniz de kendi laptop'ınız. Bu rehber, kendi sunucunuzda barındırma sürecinin tamamını adım adım anlatıyor: Docker Compose kurulumu, ortam değişkenleri, medya dosyaları için Cloudflare R2, wildcard DNS ve ilk yönetici hesabınızı oluşturma. Sonuna geldiğinizde, giriş yapabileceğiniz, tıkır tıkır çalışan bir VeloCMS'iniz olacak.

Başlamadan Önce

• Docker 24+ ve Docker Compose v2
• Kontrolünüzde olan bir alan adı (veya alt alan adı)
• R2 medya depolaması için bir Cloudflare hesabı (ücretsiz paket iş görür)
• İsteğe bağlı ama önerilir: yönetilen barındırma için bir Railway hesabı

Docker Compose ile Hızlı Başlangıç

VeloCMS, hazır Docker imajlarıyla birlikte gelir; yani çalıştırmak için kaynak koduna ihtiyacınız yok. Üç komutla çalışan bir sisteminiz olabilir: Compose şablonunu indirin, gizli bilgilerinizi girin ve imajları çekin.

# 1. Create a working directory
    mkdir velocms && cd velocms
    
    # 2. Download the docker-compose template and env example
    curl -O https://velocms.org/install/docker-compose.yml
    curl -O https://velocms.org/install/.env.example
    cp .env.example .env
    # Edit .env with your secrets (POCKETBASE_ADMIN_PASSWORD, ENCRYPTION_KEY, etc.)
    
    # 3. Pull the images and start
    docker compose up -d

Zorunlu Ortam Değişkenleri

VeloCMS tüm yapılandırmasını ortam değişkenlerinden okur; ortada ne bir ayar dosyası var ne de sihirli bir durum. Kök dizindeki `.env.example` dosyası, zorunlu ve isteğe bağlı tüm değişkenleri kapsar. İşte ilk çalıştırmadan önce mutlaka ayarlamanız gerekenler:

# Core
    VELOCMS_MODE=single                # or "multi" for multi-tenant SaaS mode
    POCKETBASE_URL=http://localhost:8090
    POCKETBASE_ADMIN_EMAIL=[email protected]
    POCKETBASE_ADMIN_PASSWORD=changeme123
    
    # Public site URL (used for sitemap, OG images, canonical links)
    NEXT_PUBLIC_SITE_URL=https://yourdomain.com
    NEXT_PUBLIC_PLATFORM_DOMAIN=yourdomain.com
    
    # Encryption key — 64 hex characters (32 bytes). Generate with:
    # openssl rand -hex 32
    ENCRYPTION_KEY=<64-char-hex>
    
    # Cloudflare R2 media storage
    CLOUDFLARE_ACCOUNT_ID=<your-account-id>
    CLOUDFLARE_API_TOKEN=<your-api-token>
    R2_BUCKET_NAME=velocms-media
    R2_PUBLIC_URL=https://pub-<hash>.r2.dev
    
    # Email (Resend)
    RESEND_API_KEY=re_...
    RESEND_FROM_EMAIL=[email protected]
    
    # AI writing assistant (optional — editor AI features require this)
    GEMINI_API_KEY=AI...
    
    # Billing — only required for membership/paywall features
    STRIPE_SECRET_KEY=sk_live_...
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
    STRIPE_WEBHOOK_SECRET=whsec_...

Tekil ve Çoklu Kiracı Modları

VeloCMS, tek bir ortam değişkeniyle kontrol edilen iki modda çalışır. `VELOCMS_MODE=single` modu, kişisel bir blog veya tek bir site çalıştıran küçük bir ajans için tam aradığınız şeydir; her şey tek bir PocketBase örneğinde, son derece basit bir yapıda çalışır. `VELOCMS_MODE=multi` ise SaaS modudur: ana bir PocketBase kimlik doğrulama ve faturalandırmayı yönetirken, her kiracı kendi içeriğiyle birlikte izole edilmiş kendi PocketBase örneğine sahip olur. Zaten velocms.org'un kendisi de production'da bu çoklu modda çalışıyor.

Cloudflare R2 Kurulumu

Yüklenen tüm medya dosyaları (resimler, videolar, dosya ekleri) R2'de tutulur. S3 uyumlu olması ve sıfır 'egress' ücreti sunması, özellikle bol fotoğraflı bir blog barındırıyorsanız büyük avantaj. Bir 'bucket' oluşturacak, nesne yazma izinlerine sahip bir API token'ı üretecek ve herkese açık URL'yi alacaksınız.

# 1. Log into https://dash.cloudflare.com → R2 Object Storage
    # 2. Create a bucket: "velocms-media" (or any name you prefer)
    # 3. Under bucket settings, enable Public Access → note the r2.dev URL
    # 4. Create an API Token with:
    #    - Object Read & Write permissions on your bucket
    #    - Copy the token value — you only see it once
    # 5. Set in .env.local:
    CLOUDFLARE_ACCOUNT_ID=<from Cloudflare dashboard top-right>
    CLOUDFLARE_API_TOKEN=<the token you just copied>
    R2_BUCKET_NAME=velocms-media
    R2_PUBLIC_URL=https://pub-<hash>.r2.dev

Wildcard DNS Ayarları

Eğer çoklu kiracı modunda çalışıyorsanız, her kiracı kendi alt alan adına sahip olur (örneğin, `alice.alanadiniz.com`). Sunucunuza işaret eden bir wildcard DNS kaydına ve Cloudflare'in bu kaydı proxy'lemediği (gri bulut) bir ayara ihtiyacınız olacak. Ana alan adı ise Cloudflare proxy'li (turuncu bulut) kalmalı.

# Add these two records in Cloudflare DNS:
    Type   Name             Content               Proxy status
    A      yourdomain.com   <your-server-IP>      Proxied (orange cloud)
    A      *.yourdomain.com <your-server-IP>      DNS only (grey cloud)
    
    # The wildcard MUST be grey cloud — Cloudflare's proxy doesn't support
    # wildcard certificates on free plans, and Railway handles TLS for subdomains.

İlk Yönetici Hesabını Oluşturma

Docker Compose çalışmaya başladığında, PocketBase yönetici arayüzünü 8090 portunda açar. Bu adresi ilk ziyaret ettiğinizde, sizden bir süper kullanıcı oluşturmanız istenir; işte bu sizin yönetici hesabınız olacak. Bundan sonra, bu bilgilerle VeloCMS'e `/login` adresinden giriş yapabilirsiniz.

# Navigate to PocketBase admin (while Docker is running):
    open http://localhost:8090/_/
    
    # Create your superuser email + password when prompted.
    # Then visit the VeloCMS admin panel:
    open http://localhost:3000/login

Railway'e Dağıtım

Production ortamı için önerdiğimiz platform Railway. Docker build'lerini, sıfır kesintili dağıtımları, otomatik TLS'i ve özel alan adlarını kutudan çıktığı gibi hallediyor. Herkese açık repo kullanıma sunulduğunda (2026 3. çeyrek, `github.com/VeloCMS` adresinde), Railway `git push` ile otomatik dağıtım yapacak. O zamana kadar, doğrudan Railway Docker registry'sini kullanabilir veya yönetilen barındırma için `[email protected]` adresinden bize ulaşabilirsiniz.

# Install Railway CLI
    npm install -g @railway/cli
    
    # Login and link to your project
    railway login
    railway link
    
    # Set production env vars (do this before the first deploy)
    railway variables --set "VELOCMS_MODE=multi" --skip-deploys
    railway variables --set "POCKETBASE_URL=https://your-pb.up.railway.app" --skip-deploys
    railway variables --set "NEXT_PUBLIC_SITE_URL=https://yourdomain.com" --skip-deploys
    # ... (set all other vars from .env.example / public/install/.env.example)
    
    # Deploy — Railway auto-deploys from the VeloCMS Docker image
    railway up

İşte bu kadar. İlk dağıtım bittiğinde, her şeyin yolunda olduğunu doğrulamak için Railway servis URL'nizi ziyaret edin. Bir şeyler ters giderse build log'larına göz atın; Railway'in log görüntüleyicisi başlangıç hatalarını bulmak için gerçekten çok işe yarıyor.

Referans

Ortam Değişkenleri

Kurulum Adımlarının Özeti

Tekil ve Çoklu Kiracı Modları

Docker İmaj Referansı