Gitea Kurulumu: Docker, PostgreSQL, Nginx ve SSH ile Kendi Git Sunucunuz

Gitea nedir, kimler için uygundur?

Gitea, MIT lisanslı açık kaynaklı bir Git hizmetidir (Gitea Docs: What is Gitea (sistem gereksinimleri, lisans)). Küçük ekipler, ajanslar, kodunu şirket dışına çıkarmak istemeyen geliştiriciler ve GitHub'daki bir depoyu yansılamak (mirror) isteyenler için uygundur. 1 Kasım 2026 itibarıyla son kararlı sürüm v28.2.0'dır (GitHub: go-gitea/gitea sürümleri).

1. Adım: Kullanıcı ve klasör

Docker ve Compose kurulu olmalı (Docker Compose başlangıç rehberi). Belgeye göre host üzerindeki veri klasörünün sahibi, compose dosyasındaki USER_UID ve USER_GID değerleriyle aynı olmalı; aksi halde konteyner açılmayabilir. Bu yüzden ayrı bir git kullanıcısı açıp UID/GID değerini not alıyoruz:

sudo adduser --system --group --disabled-password --home /home/git git
id git          # ornek cikti: uid=110(git) gid=113(git)

sudo mkdir -p /opt/gitea/gitea /opt/gitea/postgres
sudo chown -R git:git /opt/gitea/gitea

Kullanıcı yönetimine yabancıysanız Linux kullanıcı ve grup yönetimi yazısına bakın.

2. Adım: docker-compose.yml (PostgreSQL ile)

Aşağıdaki dosya, Gitea Docs: Installation with Docker sayfasındaki PostgreSQL örneğinden türetildi. Değişikliklerimiz: web portu yalnızca 127.0.0.1'e bağlandı, SSH için host portu 2222 seçildi, şifreler .env dosyasına taşındı ve birkaç app.ini ayarı ortam değişkeniyle verildi. Belge, app.ini içindeki her ayarın GITEA__bolum__ANAHTAR=deger biçimindeki bir ortam değişkeniyle verilebileceğini belirtir.

# /opt/gitea/.env
UID_GIT=110
GID_GIT=113
DB_PASSWORD=GUCLU_BIR_SIFRE

networks:
  gitea:
    external: false

services:
  server:
    image: docker.gitea.com/gitea:28.2.0
    container_name: gitea
    environment:
      - USER_UID=${UID_GIT}
      - USER_GID=${GID_GIT}
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${DB_PASSWORD}
      - GITEA__server__DOMAIN=git.example.com
      - GITEA__server__SSH_DOMAIN=git.example.com
      - GITEA__server__ROOT_URL=https://git.example.com/
      - GITEA__server__SSH_PORT=2222
      - GITEA__service__DISABLE_REGISTRATION=true
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: docker.io/library/postgres:18
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql

cd /opt/gitea
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f server

3. Adım: Kurulum sihirbazı ve yönetici hesabı

Konteyner ilk açıldığında Gitea, kurulum sihirbazını gösterir. Sihirbaz tamamlanana kadar adrese ulaşan herkes kurulumu yapabilir; bu yüzden sihirbazı Nginx'i açmadan önce bir SSH tüneliyle tamamlamanızı öneririz:

# Kendi bilgisayarinizda
ssh -L 3000:127.0.0.1:3000 kullanici@sunucu-ip
# Tarayicida: http://localhost:3000

• Veritabanı alanları ortam değişkenlerinden dolu gelir. Belgeye göre compose içindeki veritabanı servisi kullanıldığında sunucu adı db olmalıdır.
• Site başlığını, SSH sunucu alanını ve temel URL'yi kontrol edin; https://git.example.com/ olmalı.
• Sihirbazı tamamlayın. Kurulumdan sonra yapılandırma /data/gitea/conf/app.ini, yani host üzerinde /opt/gitea/gitea/gitea/conf/app.ini dosyasına yazılır.

Kayıtları kapattığımız için yönetici hesabını komut satırından oluşturmak güvenli bir yoldur. Gitea Docs: Gitea Command Line sayfasındaki admin user create komutu konteyner içinde git kullanıcısıyla çalıştırılır:

sudo docker exec -u git gitea gitea admin user create \
  --username yonetici --email yonetici@example.com \
  --password 'GECICI_GUCLU_SIFRE' --admin

--must-change-password seçeneği varsayılan olarak açık olduğu için ilk girişte bu geçici şifreyi değiştirmeniz istenir. Şifre kabuk geçmişinde kalabileceğinden işlem bitince history kaydını temizlemeyi düşünün. Girişten sonra Ayarlar > Güvenlik bölümünden iki adımlı doğrulamayı açın; Gitea TOTP ve WebAuthn tabanlı donanım anahtarlarını destekler (Gitea Docs: Multi-factor Authentication).

4. Adım: Nginx ve Let's Encrypt

Gitea Docs: Reverse Proxies sayfası, ROOT_URL'nin doğru ayarlanmasını, Host ve X-Forwarded-Proto başlıklarının iletilmesini, X-Real-IP başlığının vekil tarafından ayarlanmasını ve /-/ws adresindeki WebSocket bağlantısı için HTTP/1.1 ile Upgrade/Connection başlıklarının geçirilmesini ister. Belgedeki Nginx örneği şöyle:

# /etc/nginx/sites-available/gitea
server {
    listen 80;
    server_name git.example.com;

    location / {
        client_max_body_size 512M;
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d git.example.com

client_max_body_size küçük kalırsa büyük dosya yüklemelerinde "413 Request Entity Too Large" hatası alırsınız. Belge, Gitea'yı bir alt dizinde (örneğin /gitea/) yayınlamayı genellikle önermez; ayrı bir alt alan adı kullanın. Nginx temelleri için Nginx yapılandırma rehberi, sertifika için Let's Encrypt rehberi.

5. Adım: SSH ile klonlama seçenekleri

Rootful imaj kendi içinde bir OpenSSH sunucusu çalıştırır; konteyner içinde 22 numaralı porttadır. Host'un kendi SSH servisi de 22'yi kullandığı için çakışmayı çözmenin belgelenmiş iki yolu vardır:

Gitea Docs: Configuration Cheat Sheet sayfasına göre SSH_PORT klon adresinde gösterilen porttur, SSH_DOMAIN ise klon adresindeki alan adıdır ve boş bırakılırsa ROOT_URL'deki alan adı kullanılır. Kullanıcılar SSH anahtarlarını Ayarlar > SSH / GPG Anahtarları bölümüne ekler. İstemci tarafında portu her seferinde yazmamak için SSH config dosyası kullanabilirsiniz:

# ~/.ssh/config
Host git.example.com
    Port 2222
    User git

2222 portunu dış dünyaya açtığınız için fail2ban ile deneme saldırılarını sınırlamayı düşünün; Gitea belgesinde bir fail2ban kurulum sayfası da bulunuyor.

app.ini temelleri

Ortam değişkenleri her konteyner başlangıcında app.ini'ye yazılır. Doğrudan dosyayı düzenlemeyi tercih ederseniz değişiklikten sonra docker compose restart server çalıştırın. Sık kullanılan anahtarlar:

Gitea Actions ve runner

Gitea Docs: Actions Quick Start sayfasına göre Actions 1.21.0'dan beri varsayılan olarak açıktır, ancak işleri çalıştırmak için ayrı bir Gitea Runner gerekir. Belge, Gitea'yı yavaşlatmaması için runner'ı Gitea'dan ayrı bir makinede çalıştırmayı önerir. Runner, belgede verilen önceden derlenmiş ikili dosyayla veya gitea/runner Docker imajıyla kurulabilir; işleri izole Docker konteynerlerinde çalıştırmak için runner makinesinde Docker gerekir.

# Runner makinesinde (token: Site Yonetimi > Actions > Runners)
gitea-runner register --no-interactive --instance https://git.example.com --token RUNNER_TOKEN
gitea-runner daemon

Belge, --instance için 127.0.0.1 veya localhost gibi geri döngü adreslerinin kötü bir fikir olduğunu, çünkü iş konteynerlerinin de bu adrese bağlanacağını vurgular. Token; site, organizasyon veya depo düzeyinde ilgili ayar sayfasındaki Runners bölümünden alınır.

Güncelleme

Belgedeki adımlar: önce verinin konteyner dışında durduğundan emin olun ve yedek alın, sabit bir sürüm kullanıyorsanız compose dosyasındaki etiketi yeni sürüme çevirin, sonra imajı çekip konteyneri yeniden oluşturun.

cd /opt/gitea
# docker-compose.yml icinde 28.2.0 etiketini yeni surumle degistirin
sudo docker compose pull
sudo docker compose up -d

Ana sürüm atlamadan önce GitHub'daki sürüm notlarında kırıcı değişiklikleri okuyun. Sistem paketlerinin güncellenmesi için sunucu güncelleme ve yama yönetimi yazısına bakın.

Yedekleme ve geri yükleme

Gitea Docs: Backup and Restore sayfası iki önemli noktanın altını çizer: tutarlı bir yedek için Gitea yedekleme sırasında durdurulmalıdır ve veritabanı için yerel döküm araçları (pg_dump, mysqldump) gitea dump'ın SQL çıktısına tercih edilebilir. Docker kurulumunda basit ve tutarlı bir yöntem şudur:

cd /opt/gitea
sudo docker compose stop server
sudo docker compose exec -T db pg_dump -U gitea gitea | gzip > /root/yedek/gitea-db-$(date +%F).sql.gz
sudo tar -czf /root/yedek/gitea-data-$(date +%F).tar.gz -C /opt/gitea gitea .env docker-compose.yml
sudo docker compose start server

Gitea'nın kendi gitea dump komutu da konteyner içinden çalıştırılabilir; belge bunun için RUN_USER ile aynı kullanıcıyla ve geçici dizinin içinde çalışmayı şart koşar. Geri yükleme için hazır bir komut yoktur: dosyalar yerine taşınır, veritabanı dökümü geri yüklenir ve kurulum yöntemi veya dizin değiştiyse gitea admin regenerate hooks ile Git kancaları yeniden üretilir; aksi halde push işlemleri başarısız olur. Yedekleri sunucu dışına taşımak için rsync rehberi ve veritabanı yedekleme stratejileri yazılarına bakın.

Forgejo hakkında kısa not

Forgejo, Gitea'dan doğmuş ayrı bir projedir. Forgejo: Comparison with Gitea sayfasına göre Forgejo Ekim 2022'de oluşturuldu, önce "soft-fork" olarak sunuldu ve 2024 başında kod tabanı Gitea'dan ayrışmaya başlayan bir "hard-fork" oldu. Forgejo FAQ sayfasına göre Forgejo v9.0 ve sonrası GPL v3+ lisanslıdır. Yani artık birebir yer değiştirilebilir iki ürün değildir; birinden diğerine geçiş planlıyorsanız ilgili projenin geçiş belgesini okuyun.

Sık karşılaşılan sorunlar

Sık Sorulan Sorular

Gitea için en az ne kadar kaynak gerekir?

Resmî belgeye göre küçük ekipler ve projeler için genellikle 2 CPU çekirdeği ve 1 GB RAM yeterlidir. CI işlerini aynı sunucuda çalıştıracaksanız daha fazla kaynak gerekir; belge zaten runner'ı ayrı makinede çalıştırmayı önerir.

SQLite ile kurabilir miyim?

Evet. Belgedeki en basit compose örneği veritabanı servisi içermez ve SQLite kullanır. Ancak veritabanı türünü sonradan değiştirmek iyi test edilmemiş bir süreçtir; belge son veritabanı türünü ilk kurulumda seçmenizi önerir. Ekip kullanımında PostgreSQL daha rahat bir seçimdir.

Gitea Actions, GitHub Actions iş akışlarımı çalıştırır mı?

Gitea Actions, GitHub Actions ile büyük ölçüde uyumlu olacak şekilde tasarlanmıştır ve varsayılan olarak eylemleri github.com'dan çeker (DEFAULT_ACTIONS_URL = github). Yine de her iş akışının birebir çalışacağını varsaymayın; belgedeki karşılaştırma sayfasından farkları kontrol edin. GitHub tarafı için GitHub Actions ile VPS'e deploy yazımıza bakabilirsiniz.

Kayıtları neden kapatmalıyım?

İnternete açık bir Gitea'da açık kayıt, istenmeyen hesapların ve spam depoların oluşmasına yol açabilir. DISABLE_REGISTRATION = true ile hesapları yalnızca yönetici açar; tamamen özel bir kurulum için REQUIRE_SIGNIN_VIEW = true da ekleyebilirsiniz.

Gitea ile Forgejo aynı şey mi?

Hayır. Forgejo, Gitea'dan çatallanan ve 2024'ten beri kod tabanı ayrışan bağımsız bir projedir; v9.0'dan itibaren lisansı da farklıdır (GPL v3+). Bu rehberdeki komutlar Gitea içindir.

Yazılım ve hizmet adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen projeler veya şirketlerle ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Coolify ile kendi PaaS'ınız · Portainer ile Docker yönetimi · Uptime Kuma ile site izleme · GitHub Actions ile VPS deploy · Docker Compose rehberi · Reverse proxy nedir · VPS güvenlik sertleştirme