Kurulum

İki yol var:

Docker: önerilen yol. PostgreSQL ve Redis birlikte gelir.
Elle kurulum: Python ile; SQLite ya da kendi PostgreSQL sunucunuz.

Her iki yolda da mağaza tarayıcıdaki kurulum sihirbazıyla (/kurulum) kurulur. Sihirbaz şu adımlardan geçer:

Sistem kontrolü
Veritabanı
Yönetici hesabı
Firma bilgileri: yasal sayfalar için zorunlu.
Renk paleti ve logo
Demo içerik

Önemli: Sunucuyu başlattıktan sonra sihirbazı hemen tamamlayın. Kurulum bitene kadar /kurulum adresine ulaşan herkes yönetici hesabını oluşturabilir. Kurulum bitince sihirbaz kapanır ve bir daha açılmaz.

1. Docker ile kurulum

Gerekenler: Docker Engine ve Docker Compose v2 (docker compose version).

unzip cms-<sürüm>.zip && cd cms-<sürüm>
cp .env.example .env

.env dosyasında POSTGRES_PASSWORD satırını doldurun. Yalnızca harf ve rakam kullanın. Rastgele bir değer

üretmek için:

python3 -c "import secrets; print(secrets.token_hex(24))"

Ardından:

docker compose up -d --build
docker compose logs -f web        # "Kurulum bekliyor" satırını görünce Ctrl+C

Sonra sihirbazı açın:

Kendi bilgisayarınızda: http://127.0.0.1:8000/kurulum
Sunucuda: önce HTTPS bölümündeki ters vekili kurun, sonra https://alanadiniz.com/kurulum.

Sihirbazın veritabanı adımında "Veritabanı adresi sunucu ortamından geliyor" yazar. Docker Compose PostgreSQL'i kendisi

bağlar, bu adımda bir şey seçmeniz gerekmez.

Docker kurulumunun düzeni

Ne	Nerede
Ayar dosyası (gizli anahtar), kurulum kilidi	`instance/`
Yüklenen görseller	`static/uploads/`
Eklenti iş kuyrukları	`data/`
Veritabanı	`postgres_data` Docker birimi

Port: varsayılan 127.0.0.1:8000. Değiştirmek için .env dosyasındaki CMS_PORT ve CMS_BIND ayarlarını kullanın.
Açılışta: kurulum tamamlanmışsa açılışta veritabanı sürümleri kendiliğinden uygulanır. Kapatmak için: RUN_DB_UPGRADE_ON_START=0.

Sık kullanılan komutlar:

docker compose ps
docker compose logs -f web
docker compose exec web flask --app app yonetici-olustur      # yeni yönetici
docker compose restart web
docker compose down                                           # durdurur; veriler kalır

Tarayıcısız kurulum: Sihirbazı komutla doldurmak (barındırma betikleri, otomasyon) için:

CMS_YONETICI_SIFRE='...' flask --app app kurulum-yap --firma "Örnek Ticaret" --telefon "0000 000 00 00"     --eposta [email protected] --adres "Örnek Mah. No:1" --tema butik [--palet krem] [--profil butik|yok]

Şifre verilmezse sorulur. Docker'da: docker compose exec -e CMS_YONETICI_SIFRE web flask --app app kurulum-yap ....

Mağazayı geçici olarak kapatmak: flask --app app magaza-askiya-al [--neden "..."] vitrini ziyaretçiye kapatır

("geçici olarak kapalı" sayfası, 503); panel açık kalır ve üstünde uyarı görünür. flask --app app magaza-ac geri açar.

Aynı işi instance/askida dosyasını oluşturmak ve silmek yapar; yeniden başlatmak gerekmez.

2. Elle kurulum (Docker olmadan)

Gerekenler:

Python 3.9 veya üstü (önerilen 3.12)
İsteğe bağlı: PostgreSQL 13+ ve Redis

unzip cms-<sürüm>.zip && cd cms-<sürüm>
python3 -m venv venv
venv/bin/pip install -r requirements.txt          # Windows: venv\Scripts\pip install -r requirements.txt
cp .env.example .env

Deneme (kendi bilgisayarınızda)

venv/bin/flask --app app run --port 8000

http://127.0.0.1:8000/kurulum adresini açın. Veritabanı adımında SQLite seçebilirsiniz; dosya instance/site.db

olarak oluşturulur. flask run yalnızca deneme içindir.

Sunucuda (Linux)

Gizli anahtarı üretin. Bu adım, birden çok işçi aynı anda açıldığında hepsinin aynı anahtarı okumasını sağlar:
```
venv/bin/flask --app app kurulum-durumu
```

Uygulamayı Gunicorn ile çalıştırın:

venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 app:app

Gunicorn'u bir systemd hizmeti olarak çalıştırın. Örnek /etc/systemd/system/cms.service dosyası (magaza kullanıcısı örnektir):

[Unit]
Description=CMS
After=network.target postgresql.service

[Service]
User=magaza
WorkingDirectory=/srv/cms
ExecStartPre=/srv/cms/venv/bin/flask --app app kurulum-durumu
ExecStart=/srv/cms/venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 --access-logfile - app:app
Restart=always

[Install]
WantedBy=multi-user.target

Veritabanı

PostgreSQL için boş bir veritabanı ve kullanıcı oluşturun. Bilgileri sihirbazın veritabanı adımına girin ya da .env dosyasına DATABASE_URL=postgresql://kullanici:parola@localhost:5432/magaza yazın.
SQLite küçük mağazalar için yeterlidir; aynı anda çok yazma gereken yoğun sitelerde PostgreSQL kullanın.

Redis isteğe bağlıdır. Tanımlı değilse hız sınırları ve önbellek bellekte tutulur. Birden çok Gunicorn işçisi

kullanıyorsanız hız sınırlarının ortak tutulması için Redis önerilir:

RATELIMIT_STORAGE_URI=redis://localhost:6379/0.

3. HTTPS ve alan adı

Uygulama üretimde oturum çerezini yalnızca HTTPS üzerinden gönderir. Bu nedenle sunucuda önüne HTTPS sağlayan bir

ters vekil koyun ve .env dosyasına şunu ekleyin:

TRUST_PROXY=1

Site HTTP ile açılırsa sihirbazın sistem kontrolü "HTTPS" maddesinde uyarır. Kendi bilgisayarınızda

127.0.0.1 / localhost ile yapılan denemeler bu kuraldan muaftır.

Caddy ile (sertifikayı kendisi alır) — /etc/caddy/Caddyfile:

magaza.com, www.magaza.com {
    reverse_proxy 127.0.0.1:8000
}

Nginx ile (sertifika için örneğin certbot --nginx):

server {
    server_name magaza.com www.magaza.com;
    client_max_body_size 20m;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
    }
    listen 443 ssl;
    # ssl_certificate ... (certbot ekler)
}

HTTPS'siz, uzaktan yapılan kısa bir deneme için SESSION_COOKIE_SECURE=false ve CMS_BIND=0.0.0.0

kullanılabilir. Bu ayarlarla siteyi yayına almayın.

4. Eklentiler ve lisans

Kurulu eklentiler Panel → Eklentiler sayfasında listelenir; oradan açılıp kapatılır. Kapatılan eklentinin verileri

silinmez.

Ücretli eklenti eklemek (örnek: kampanya-1.0.0.zip):

Zip'i mağazanın plugins/ klasörüne açın. Sonuç plugins/kampanya/plugin.json olmalı.
Uygulamayı yeniden başlatın:
- Docker: docker compose up -d --build. Eklentinin tabloları açılışta kendiliğinden oluşturulur.
- Elle kurulum: venv/bin/flask --app app db upgrade heads, ardından hizmeti yeniden başlatın.
Panel → Eklentiler'de eklentinin satırına lisans anahtarınızı (CMS1....) girin ve eklentiyi açın.

Lisans anahtarı alan adınıza bağlıdır. localhost ve 127.0.0.1 üzerinde lisans her zaman geçerlidir.

Zamanlanmış görevler: Bazı eklentilerin düzenli çalışması gereken komutları vardır. Bunları sunucunun

crontab'ına ekleyin. Elle kurulumda docker compose exec -T web flask yerine venv/bin/flask kullanın:

# Döviz eklentisi: kur güncelleme (saat başı)
0 * * * *  cd /srv/cms && docker compose exec -T web flask --app app kur-guncelle
# Kampanyalar: süresi dolan kampanyaları bitirme (her 10 dakikada)
*/10 * * * *  cd /srv/cms && docker compose exec -T web flask --app app campaign-expire

5. Yedekleme

Yedeklenecekler:

veritabanı
instance/ (gizli anahtar ve ayarlar)
static/uploads/ (görseller)
.env

# Docker + PostgreSQL
docker compose exec -T db pg_dump -U cms cms > yedek-$(date +%F).sql
tar czf dosyalar-$(date +%F).tar.gz instance static/uploads .env

# Geri yükleme (boş veritabanına)
docker compose exec -T db psql -U cms cms < yedek-2026-01-01.sql

SQLite kullanıyorsanız instance/site.db dosyasını uygulama dururken kopyalayın.

instance/config.env dosyasındaki gizli anahtar kaybolursa açık oturumlar kapanır; veriler etkilenmez.

6. Güncelleme

Yedek alın (yukarıda).
Yeni sürümün dosyalarını eskilerin üzerine açın. Şunlara dokunmayın:
- .env
- instance/
- static/uploads/
- data/
- Ayrı aldığınız ücretli eklentilerin plugins/<kod>/ klasörleri
Uygulamayı yeniden başlatın:
- Docker: docker compose up -d --build. Veritabanı sürümleri açılışta uygulanır.
- Elle kurulum: venv/bin/pip install -r requirements.txt, ardından venv/bin/flask --app app db upgrade heads, sonra hizmeti yeniden başlatın.

7. Sorun giderme

Belirti	Çözüm
Sihirbazda "Oturum süresi doldu"	Site HTTPS'siz açılmış. Sistem kontrolündeki HTTPS maddesine bakın (Bölüm 3)
`POSTGRES_PASSWORD .env dosyasinda tanimlanmali`	`.env` dosyasında `POSTGRES_PASSWORD` boş
"FLASK_SECRET_KEY güvensiz" hatası	`.env` dosyasındaki `FLASK_SECRET_KEY` satırını boş bırakın; anahtar kendiliğinden üretilir
"Bu veritabanında zaten ... tablo var"	Kurulum yalnızca boş veritabanına yapılır. Yeni bir veritabanı kullanın
Kurulumu baştan yapmak	Uygulamayı durdurun, veritabanını boşaltın, `instance/installed.lock` dosyasını silin, yeniden başlatın
Şifre unutuldu	`flask --app app yonetici-olustur` ile yeni bir yönetici açın (Docker'da başına `docker compose exec web`)
Eklenti panelde görünmüyor	Klasör yapısı `plugins/<kod>/plugin.json` olmalı; yeniden başlatın ve kayıtlara (`docker compose logs web`) bakın

Elle kurulan ya da taşınan bir veritabanı: Veritabanında şema ve yönetici varsa sihirbazı kapatmak için

flask --app app kurulum-kilitle komutunu çalıştırın.