cPanel'de Python Uygulaması (Flask/Django) Yayınlama

PHP dosyalarını sunucuya atmaya alışkın biri Python'a geçtiğinde ilk şaşkınlığı, app.py dosyasını public_html altına yükleyip tarayıcıda açmaya çalıştığında yaşar: karşısına ya ham kaynak kod ya da bir hata sayfası çıkar. Sebep basittir. Apache, PHP'yi her istekte kendi motoruyla yorumlar; ama Python bir web uygulaması olarak çalışmak için ayakta duran, istekleri bekleyen bir uygulama sunucusuna ihtiyaç duyar. İşte cPanel'in Setup Python App aracı tam olarak bu boşluğu doldurur ve Phusion Passenger üzerinden Flask, Django, FastAPI gibi WSGI tabanlı uygulamalarınızı tek ekrandan yayına almanızı sağlar.

Bu rehberde Setup Python App'in perde arkasında nasıl çalıştığını, Python sürümü ile uygulama kökü ve URL seçimini, otomatik oluşan sanal ortamı, pip ile bağımlılık kurulumunu ve passenger_wsgi.py giriş noktasını adım adım ele alacağız. Hem küçük bir Flask uygulamasını hem de tam bir Django projesini gerçek komutlarla yayına alacak, ortam değişkeni, statik dosya ve yeniden başlatma gibi günlük operasyon adımlarını da işleyeceğiz. cPanel'e yeni başlıyorsanız önce cPanel nedir yazımıza göz atmanızı, tam izolasyon isteyen senaryolar için de Docker'a giriş rehberimizi incelemenizi öneririz.

Neden Python cPanel'de PHP'den Farklı Çalışır?#

PHP, Apache içine gömülü çalışan bir dildir; gelen her istekte ilgili .php dosyası anlık olarak yorumlanır ve çıktı üretilir. Python web uygulamaları ise bu modele uymaz. Bir Flask ya da Django projesi, başlatıldığında bellekte kalan, rotaları (route) dinleyen ve isteklere yanıt üreten uzun ömürlü bir süreçtir. Bu süreç ile web sunucusu arasındaki köprü WSGI (Web Server Gateway Interface) standardıyla kurulur.

cPanel bu köprüyü Phusion Passenger ile sağlar. Passenger, Apache'ye entegre çalışan ve Python uygulamanızı gerektiğinde başlatıp yöneten bir uygulama sunucusudur. Siz "Setup Python App" ekranından bir uygulama tanımladığınızda, arka planda şunlar olur: sizin için izole bir sanal ortam (virtualenv) oluşturulur, bu ortamın Passenger tarafından tanınması için gerekli Apache yönlendirmeleri yazılır ve uygulamanızın giriş noktası olan passenger_wsgi.py dosyası aranır. Yani PHP'deki gibi "dosyayı at, çalışsın" mantığı yerine, "bir uygulama süreci tanımla ve onu yönet" mantığı geçerlidir.

Bu yapının pratik sonucu şudur: kodunuzu değiştirdiğinizde tarayıcıyı yenilemek yetmez; çalışan süreci yeniden başlatmanız gerekir. Ayrıca uygulamanız bir hata verdiğinde bunu doğrudan tarayıcıda değil, Passenger'ın günlük kayıtlarında görürsünüz. Bu farkları baştan bilmek, ilerideki bölümlerde karşılaşacağınız pek çok "neden çalışmıyor" sorusunun cevabını da peşinen verir.

Setup Python App ile Yeni Uygulama Oluşturmak#

cPanel ana ekranında Software grubundaki Setup Python App simgesine tıklayın ve Create Application butonuna basın. Karşınıza çıkan form, uygulamanızın kimliğini belirleyen üç kritik alan içerir. Bunları doğru doldurmak, ilerideki tüm adımların temelini oluşturur.

Python version için projenizin desteklediği güncel bir sürümü (mümkünse 3.10 ve üzeri) seçin; sunucuda hangi sürümlerin kurulu olduğu barındırma paketinize göre değişir. Application root, kodunuzun yaşayacağı klasördür ve genellikle public_html dışında, ev dizininizin altında tutulur — bu, kaynak kodun ziyaretçilere doğrudan açık olmamasını sağlar. Application URL ise uygulamanın adresidir; ana alan adı, bir alt alan adı (subdomain) ya da bir alt dizin olabilir.

Formu doldurup Create dediğinizde cPanel, belirttiğiniz dizini oluşturur, o dizine özel bir sanal ortam kurar ve içine örnek bir passenger_wsgi.py ile requirements.txt yerleştirir. Uygulama listesinin en üstünde, size şuna benzer bir komut gösterilir; bunu SSH ile bağlandığınızda çalıştırarak doğrudan sanal ortamın içine girersiniz:

source /home/kullanici/virtualenv/apps/flaskapp/3.11/bin/activate && cd /home/kullanici/apps/flaskapp

Bu komutu bir kenara not edin; bağımlılık kurmaktan Django yönetim komutlarını çalıştırmaya kadar her şeyi bu aktif ortam içinde yapacaksınız.

Sanal Ortam ve Bağımlılık Kurulumu (pip + requirements)#

Setup Python App'in en değerli özelliği, her uygulama için ayrı bir sanal ortam üretmesidir. Bu sayede A uygulamanız Django 4.2 kullanırken B uygulamanız Django 5.1 kullanabilir; kütüphaneler birbirine karışmaz. Sanal ortam, sizin ev dizininizde virtualenv/ altında oluşturulur ve yalnızca o uygulamaya aittir.

Bağımlılık eklemenin iki yolu vardır. Küçük projelerde cPanel arayüzündeki Configuration files alanına requirements.txt yazıp Run Pip Install butonuna basmak yeterlidir. Ancak asıl güçlü yöntem SSH ile ortamı etkinleştirip pip komutlarını doğrudan çalıştırmaktır:

# Uygulamanın sanal ortamını etkinleştir (Create ekranındaki komut)
source /home/kullanici/virtualenv/apps/flaskapp/3.11/bin/activate
cd /home/kullanici/apps/flaskapp

# Tekil paket kurmak
pip install flask gunicorn

# Ya da tüm bağımlılıkları dosyadan kurmak (önerilen)
pip install -r requirements.txt

Projelerinizde bağımlılıkları her zaman bir requirements.txt dosyasında sabitlemenizi öneririz; bu, sunucuda kurulan sürümlerin yerel makinenizle aynı olmasını garanti eder ve "bende çalışıyordu" sorunlarını ortadan kaldırır. Sürümleri sabitlemek için tipik bir dosya şöyle görünür:

Flask==3.0.3
gunicorn==22.0.0
python-dotenv==1.0.1
SQLAlchemy==2.0.31

Kurduğunuz paketleri doğrulamak ve mevcut ortamın bir kopyasını çıkarmak için pip freeze komutunu kullanın:

pip freeze > requirements.txt   # mevcut ortamı dosyaya dök
pip list                        # kurulu paketleri listele

Paylaşımlı planlarda pip install sırasında bellek ya da işlemci sınırlarına takılırsanız, derlenmesi ağır olan paketleri (örneğin bazı bilimsel kütüphaneler) --no-cache-dir bayrağıyla kurmayı deneyebilir ya da hazır "wheel" sürümlerini tercih edebilirsiniz. Sınırların sık sık yolunuza çıktığı büyük projelerde tam kök yetkisi veren bir VDS sunucu çözümüne geçmek en kalıcı çözümdür.

passenger_wsgi.py: Uygulamanızın Giriş Noktası#

Passenger, uygulamanızı başlatmak için uygulama kökünüzdeki passenger_wsgi.py dosyasını arar ve bu dosyanın içinde application adında bir WSGI nesnesi bulmayı bekler. Bu isim ve konum sabittir; değiştiremezsiniz. Dolayısıyla tüm mesele, framework'ünüzün WSGI uygulamasını bu application değişkenine bağlamaktan ibarettir.

En yalın hâliyle, doğrudan çalışan bir "merhaba dünya" giriş noktası şöyledir:

# passenger_wsgi.py
import sys, os

# Uygulama kök dizinini Python yoluna ekle
sys.path.insert(0, os.path.dirname(__file__))

def application(environ, start_response):
    start_response("200 OK", [("Content-Type", "text/plain; charset=utf-8")])
    return [b"Merhaba, Passenger calisiyor!"]

Gerçek projelerde ise bu dosya yalnızca bir köprü görevi görür: asıl uygulamanızı içeri aktarır ve application adıyla dışa verir. Örneğin app.py içinde app adında bir Flask nesneniz varsa:

# passenger_wsgi.py
import sys, os

sys.path.insert(0, os.path.dirname(__file__))

from app import app as application

Buradaki from app import app as application satırı işin can alıcı noktasıdır: app.py dosyanızdaki app nesnesini alıp Passenger'ın beklediği application ismine bağlar. Bu köprüyü kurduğunuz sürece uygulama kodunuzu istediğiniz gibi organize edebilir, passenger_wsgi.py dosyasını sade tutabilirsiniz. Bir sonraki iki bölümde bunu Flask ve Django için ayrı ayrı somutlaştıracağız.

Flask Uygulamasını Yayınlamak#

Flask, tek dosyalık küçük projelerden büyük yapılara kadar esneyen hafif bir framework olduğu için Setup Python App ile en kolay eşleşen seçeneklerden biridir. Uygulama kökünüzde (apps/flaskapp) basit bir app.py oluşturalım:

# app.py
from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/")
def anasayfa():
    return "<h1>Clou.TR uzerinde Flask calisiyor</h1>"

@app.route("/durum")
def durum():
    return jsonify(servis="flask", durum="ayakta")

if __name__ == "__main__":
    app.run(debug=True)

Ardından passenger_wsgi.py dosyasını bu uygulamayı içeri aktaracak şekilde ayarlayın:

# passenger_wsgi.py
import sys, os
sys.path.insert(0, os.path.dirname(__file__))
from app import app as application

Bağımlılıklarınızı kurun, uygulamayı yeniden başlatın ve tarayıcıda açın:

source /home/kullanici/virtualenv/apps/flaskapp/3.11/bin/activate
cd /home/kullanici/apps/flaskapp
pip install flask
touch tmp/restart.txt   # Passenger'a "yeniden başla" der (aşağıda anlatılıyor)

Uygulama URL'nizi ziyaret ettiğinizde başlığı görüyorsanız Flask yayında demektir. Buradan sonrası standart Flask geliştirmesidir: şablonlar (templates/), statik varlıklar (static/), veritabanı bağlantısı ve iş mantığınızı ekleyebilirsiniz. Canlıda debug=True kullanmayın; hata ayıklama modu, hassas bilgileri hata sayfalarında açığa çıkarır ve üretim ortamında güvenlik riski oluşturur. Uygulamanızın herkese açık kısmını bir alan adına bağlarken trafiği şifrelemek için mutlaka bir SSL sertifikası kurmayı ve gerekiyorsa WAF katmanını devreye almayı ihmal etmeyin.

Django Uygulamasını Yayınlamak#

Django, kendi proje yapısı ve yönetim komutları olan tam donanımlı bir framework olduğu için birkaç ek adım gerektirir; ama mantık aynıdır. Diyelim ki uygulama kökünüzde django-admin startproject config . ile bir proje oluşturdunuz. Bu durumda WSGI nesneniz config/wsgi.py içinde hazır gelir ve passenger_wsgi.py bunu şöyle içeri aktarır:

# passenger_wsgi.py
import sys, os
sys.path.insert(0, os.path.dirname(__file__))
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")

from config.wsgi import application

Django'da yayına almadan önce üç ayarı mutlaka gözden geçirin. Öncelikle settings.py içinde DEBUG = False yapın ve ALLOWED_HOSTS listesine kendi alan adınızı ekleyin; aksi halde Django gelen istekleri reddeder:

# config/settings.py
DEBUG = False
ALLOWED_HOSTS = ["app.siteniz.com", "www.siteniz.com", "siteniz.com"]

STATIC_URL = "/static/"
STATIC_ROOT = os.path.join(BASE_DIR, "public/static")

Ardından SSH üzerinden veritabanı tablolarını oluşturun ve statik dosyaları toplayın. collectstatic, tüm uygulamalardaki CSS/JS dosyalarını tek bir dizinde toplar ki web sunucusu bunları doğrudan sunabilsin:

source /home/kullanici/virtualenv/apps/djangoapp/3.11/bin/activate
cd /home/kullanici/apps/djangoapp

pip install -r requirements.txt
python manage.py migrate            # veritabanı tablolarını oluştur
python manage.py collectstatic      # statik dosyaları topla
python manage.py createsuperuser     # yönetici hesabı oluştur

Django'nun yönetim paneli ve karmaşık uygulamaları, paylaşımlı ortamlarda bellek açısından Flask'a göre daha talepkârdır. Veritabanı olarak MySQL kullanacaksanız cPanel'in MySQL Databases bölümünden veritabanını ve kullanıcıyı oluşturup bağlantı bilgilerini settings.py içine (tercihen ortam değişkeni olarak) girin. Trafiği artan ya da arka planda sürekli çalışan görevler (Celery gibi) gereken Django projeleri için bir sanal sunucu ya da VDS planı, paylaşımlı hostinge göre çok daha rahat bir alan sunar.

Ortam Değişkenleri, Statik Dosyalar ve Yeniden Başlatma#

Üretim uygulamalarında veritabanı şifresi, gizli anahtar (SECRET_KEY) ve API tokenları gibi hassas değerleri kod içine yazmamalısınız. Setup Python App arayüzü, "Environment variables" bölümünde bu değişkenleri tanımlamanıza izin verir; buraya eklediğiniz her değişken uygulamanız çalışırken os.environ üzerinden okunabilir. Alternatif olarak python-dotenv ile bir .env dosyası kullanabilirsiniz:

# app.py veya settings.py başında
import os
from dotenv import load_dotenv
load_dotenv()

SECRET_KEY = os.environ["SECRET_KEY"]
DB_PASSWORD = os.environ.get("DB_PASSWORD", "")

.env dosyasını daima uygulama kökünde, public_html dışında tutun ve sürüm kontrolüne (git) eklemeyin. Böylece gizli anahtarlarınız ne ziyaretçiye ne de depoya sızar.

Statik dosyalar Python barındırmasının en çok kafa karıştıran konusudur. Passenger, Python kodunu çalıştırır ama CSS/JS/görsel gibi statik varlıkları framework üzerinden servis etmek verimsizdir. En temiz yaklaşım, statik dosyaları uygulama URL'nizin altındaki bir static dizinine yönlendirip Apache'nin doğrudan sunmasına izin vermektir. Django'da bunu STATIC_ROOT + collectstatic ile, Flask'ta ise static/ klasörünü web köküne bağlayarak yaparsınız. Gerektiğinde uygulama kökündeki .htaccess ile statik istekleri Passenger'dan ayırabilirsiniz:

# public_html/.htaccess (örnek)
RewriteEngine On
RewriteRule ^static/ - [L]

Son olarak yeniden başlatma: Python uygulaması bellekte çalışan bir süreç olduğu için kodu her değiştirdiğinizde süreci tazelemeniz gerekir. Bunun iki yolu vardır — arayüzdeki Restart butonu ya da uygulama kökündeki tmp/restart.txt dosyasına dokunmak. İkinci yöntem SSH ve otomasyon için idealdir:

mkdir -p tmp
touch tmp/restart.txt   # Passenger bir sonraki istekte uygulamayı yeniden yükler

Bu tek satır, uygulamanızı kesintisiz biçimde yeniden başlatır; ziyaretçiler bir sonraki istekte güncel kodu görür. Kod dağıtımınızı otomatikleştirmek isterseniz cPanel Git ile dağıtım yazımızdaki .cpanel.yml akışına bu touch komutunu ekleyerek her deploy sonrası otomatik yeniden başlatma kurabilirsiniz.

Paylaşımlı Hosting mi, VDS/Sanal Sunucu mu?#

Python projenizi nerede barındıracağınız, projenin büyüklüğüne ve ihtiyaçlarına bağlıdır. Setup Python App'li paylaşımlı hosting, küçük ve orta ölçekli projeler için hızlı ve ekonomik bir başlangıçtır; ancak arka plan işçileri (worker), WebSocket, uzun süren görevler ya da özel sistem paketleri gerektiren projeler tam kök yetkisi ister. Aşağıdaki tablo iki yaklaşımı karşılaştırır:

Karar verirken şu basit ölçüyü kullanabilirsiniz: Uygulamanız yalnızca HTTP istekleri işleyen, veritabanına bağlanan klasik bir web uygulamasıysa paylaşımlı hosting fazlasıyla yeterlidir. Ama düzenli çalışan zamanlanmış görevler, kuyruk işçileri, gerçek zamanlı bağlantılar ya da apt install ile sistem seviyesinde kütüphane gerektiren bir yapı kuruyorsanız, kontrolü tamamen elinize alan bir sunucuya geçin. Kendi sunucusunu yönetmek istemeyenler için sunucu yönetimi hizmetimiz, Gunicorn + Nginx kurulumundan güvenlik güncellemelerine kadar tüm operasyonu sizin adınıza üstlenir. Farklı barındırma türlerinin ayrıntılı karşılaştırması için web hosting sayfamızı da inceleyebilirsiniz.

Sıkça Sorulan Sorular#

cPanel'de her Python sürümünü kullanabilir miyim?#

Kullanabileceğiniz sürümler, barındırma sunucusunda kurulu olan Python yorumlayıcılarıyla sınırlıdır ve Setup Python App'in açılır menüsünde listelenir. Çoğu güncel cPanel sunucusunda 3.8'den 3.11 veya 3.12'ye kadar birkaç seçenek bulunur. Projeniz belirli bir sürüm gerektiriyorsa ve o sürüm listede yoksa, barındırma sağlayıcınızdan eklenmesini talep edebilir ya da tam kontrol için bir VDS tercih edebilirsiniz.

passenger_wsgi.py dosyasının adını değiştirebilir miyim?#

Hayır, bu dosyanın adı ve konumu Passenger tarafından sabitlenmiştir. Passenger uygulamanızı başlatırken uygulama kökünüzde tam olarak passenger_wsgi.py adlı dosyayı arar ve içinde application adlı bir WSGI nesnesi bulmayı bekler. Kodunuzu istediğiniz gibi başka dosyalara bölebilirsiniz, ancak bu giriş noktası dosyasının adını ve içindeki application değişkenini değiştiremezsiniz.

Kodumu güncelledim ama değişiklikler görünmüyor, neden?#

Python uygulaması bellekte çalışan uzun ömürlü bir süreç olduğu için, dosyayı değiştirmek tek başına yeterli değildir; çalışan süreci yeniden başlatmanız gerekir. Bunu Setup Python App arayüzündeki Restart butonuyla ya da uygulama kökünde touch tmp/restart.txt komutunu çalıştırarak yapabilirsiniz. Yeniden başlatmadan sonra bir sonraki istekte güncel kodunuz devreye girer.

Django'da statik dosyalarım (CSS/JS) yüklenmiyor ne yapmalıyım?#

Bu sorunun en yaygın sebebi collectstatic komutunun çalıştırılmamış olması ya da STATIC_ROOT yolunun web sunucusunun erişebileceği bir dizine ayarlanmamasıdır. Önce settings.py içinde STATIC_ROOT değerinin doğru olduğundan emin olun, ardından sanal ortamı etkinleştirip python manage.py collectstatic komutunu çalıştırın. Statik dizini uygulama URL'nizin altında Apache'nin doğrudan servis edebileceği bir konuma bağlamak da performansı artırır.

Uygulamam hata veriyor ama tarayıcıda ayrıntı görünmüyor, logları nerede bulurum?#

Üretim ortamında hata ayrıntıları güvenlik gereği tarayıcıda gösterilmez; bunun yerine Passenger ve uygulama günlüklerine bakmanız gerekir. cPanel'in Errors bölümü ile uygulama kökünüzdeki stderr çıktısını içeren log dosyaları ilk bakacağınız yerlerdir. SSH ile bağlanıp uygulamayı elle python passenger_wsgi.py şeklinde çalıştırmak da içe aktarma (import) hatalarını hızlıca görmenin pratik bir yoludur. cPanel loglarını genel olarak cPanel hata kayıtları yazımızda ele alıyoruz.

Flask ile Django arasında cPanel için hangisi daha kolay?#

İkisi de Setup Python App ile sorunsuz çalışır, ancak Flask daha az yapılandırma gerektirdiği için ilk yayına alma açısından biraz daha basittir; tek bir app.py ve iki satırlık bir passenger_wsgi.py ile ayağa kalkar. Django ise migrate, collectstatic ve ALLOWED_HOSTS gibi ek adımlar ister ama karşılığında hazır yönetim paneli, ORM ve güvenlik katmanları sunar. Küçük bir API ya da mikro servis için Flask, tam donanımlı bir web uygulaması için Django daha mantıklı bir tercihtir.

Kapanış#

cPanel'in Setup Python App aracı, geçmişte yalnızca kök yetkili sunucularda mümkün olan Python uygulama barındırmasını, paylaşımlı hostingde birkaç tıkla erişilebilir hâle getirir. Passenger'ın WSGI köprüsü sayesinde Flask, Django ya da FastAPI projelerinizi izole bir sanal ortamda, kendi bağımlılıklarıyla ve temiz bir passenger_wsgi.py giriş noktasıyla yayına alabilirsiniz. Python sürümü seçiminden pip install'e, ortam değişkenlerinden touch tmp/restart.txt ile yeniden başlatmaya kadar tüm akışı bir kez kurduğunuzda, günlük geliştirme döngünüz oldukça akıcı hâle gelir. Konuya bütünsel bakmak isterseniz cPanel nedir ve tam izolasyon için Docker'a giriş yazılarımız iyi birer tamamlayıcıdır.

Python projelerinizi Setup Python App desteğiyle hızlıca yayına almak istiyorsanız Clou.TR'nin web hosting planları bu iş için hazırdır. Arka plan görevleri, tam kök yetkisi ya da yüksek trafik gerektiren büyük uygulamalar için VDS ve sanal sunucu çözümlerimizi inceleyebilir, kurulumu bize bırakmak isterseniz sunucu yönetimi hizmetimizden yararlanabilirsiniz. Projeniz hangi ölçekte olursa olsun, ekibimiz doğru altyapıyı seçmenizde ve ilk yayına almada size yol gösterir.