Forgejo veya Gitea, Docker Compose, PostgreSQL ve HTTPS ile nasıl kurulur

Forgejo ve Gitea, Go ile yazılmış, kendi sunucunuzda barındırabileceğiniz hafif Git platformlarıdır. Mütevazı bir sunucuda depolar, issue'lar, pull request'ler, wiki'ler, paket kayıtları ve Actions ile yerleşik CI sunarlar. İki proje yakından ilişkilidir: Forgejo 2022 sonunda Gitea'nın bir çatalı olarak başladı, kâr amacı gütmeyen Codeberg e.V. tarafından yönetilir ve 2024 başından beri bağımsız bir çatal (hard fork) olarak geliştirilir.

Bu rehber ikisinden birini, her projenin Docker belgelerini izleyerek Docker Compose ve PostgreSQL ile kurar. HTTPS'i Caddy sağlar, SSH üzerinden Git 2222 portunda çalışır, açık kayıt kapatılır ve projelerin dump komutu ile bir PostgreSQL dökümüyle yedek alırsınız. Komutların farklı olduğu yerlerde rehber bir Forgejo ve bir Gitea sekmesi gösterir.

Adım 1 — Forgejo veya Gitea'yı seçin

Forgejo belgeleri, ara ve yama sürümlerini kendiliğinden izleyen ana sürüm etiketini (16) kullanır. Forgejo 16, bir sonraki ana sürümün devraldığı 29 Ekim 2026'ya kadar desteklenir; daha az ana sürüm yükseltmesi istiyorsanız 15 Temmuz 2027'ye kadar desteklenen LTS etiketi 15'i kullanın. Gitea belgeleri tam bir sürüme sabitler. Gitea 28.0.0 ile 1. önekini bıraktı; bu yüzden 1 imaj etiketi 1.27.x'te kalır. En yeni etiket için projenin sürümlerine bakın. Gitea'nın imajı Docker Hub'da gitea/gitea adıyla da yayınlanır.

Adım 2 — Proje klasörünü ve veritabanı parolasını oluşturun

/opt altında bir klasör oluşturun, rastgele bir PostgreSQL parolası üretin ve yalnızca kullanıcınızın okuyabileceği bir .env dosyasına kaydedin:

sudo mkdir -p /opt/forgejo
sudo chown $USER:$USER /opt/forgejo
cd /opt/forgejo
echo "POSTGRES_PASSWORD=$(openssl rand -hex 32)" > .env
chmod 600 .env

sudo mkdir -p /opt/gitea
sudo chown $USER:$USER /opt/gitea
cd /opt/gitea
echo "POSTGRES_PASSWORD=$(openssl rand -hex 32)" > .env
chmod 600 .env

Adım 3 — Compose dosyasını yazın ve konteynerleri başlatın

Aynı klasörde nano compose.yaml ile compose.yaml dosyasını oluşturun. git.example.com yerine kendi alan adınızı yazın.

services:
  server:
    image: codeberg.org/forgejo/forgejo:16
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=${POSTGRES_PASSWORD}
      - FORGEJO__server__DOMAIN=git.example.com
      - FORGEJO__server__ROOT_URL=https://git.example.com/
      - FORGEJO__server__SSH_PORT=2222
      - FORGEJO__service__DISABLE_REGISTRATION=true
    restart: always
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: postgres:18
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=forgejo
    volumes:
      - ./postgres:/var/lib/postgresql

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

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

Projelerin örneklerinden farklı olanlar ve nedenleri:

• Web portu yalnızca 127.0.0.1:3000 üzerinde yayınlanır; onu HTTPS ile Caddy sunacak. Konteynerin SSH'si ise Git istemcileri ihtiyaç duyduğu için herkese açık 2222 portunda yayınlanır.
• ROOT_URL herkese açık HTTPS adresidir. Forgejo ayrıca klon adreslerindeki SSH ana makine adını türettiği DOMAIN değerine ihtiyaç duyar; Gitea 28 artık DOMAIN okumaz ve alan adını ROOT_URL değerinden alır.
• SSH_PORT=2222 klon adreslerinde gösterilen portu değiştirir. Konteynerin SSH sunucusu konteyner içinde 22 portunda dinlemeye devam eder.
• DISABLE_REGISTRATION=true kendi kendine kaydı kapatır. Gitea 28'de bu zaten varsayılandır; Forgejo'da değildir.
• İkisi de, Gitea belgelerinin ve PostgreSQL imaj belgelerinin 18 sürümü için istediği gibi /var/lib/postgresql konumuna bağlanan postgres:18 kullanır. Forgejo'nun örneği hâlâ 12 Kasım 2026'da desteği sona eren postgres:14 gösterir.
• USER_UID ve USER_GID, konteynerdeki ve veri klasörünün sahibi olan git kullanıcısının kimliklerini belirler.

Yığını başlatın ve kontrol edin:

docker compose up -d
docker compose ps
docker compose logs server --tail 20

İki konteyner de running olmalı, log da web sunucusunun veritabanı hatası olmadan başladığını göstermelidir. 80 ve 443 portları için güvenlik duvarı kuralları Caddy rehberinden gelir; Git SSH portunu Adım 6 ekler.

Adım 4 — Caddy ile HTTPS ekleyin

Alan adınız için /etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin:

git.example.com {
    reverse_proxy 127.0.0.1:3000
}

sudo systemctl reload caddy
curl -I https://git.example.com

Caddy bir sertifika alır ve curl kurulum sayfasının yanıt başlıklarını HTTPS üzerinden yazdırır. Caddy WebSocket bağlantılarını kendiliğinden iletir; Gitea 28 bunlara canlı bildirim sayıları için ihtiyaç duyar. Nginx veya Traefik için Nginx ve Certbot ile Traefik rehberlerine bakın ve WebSocket yükseltme başlıklarının iletildiğinden emin olun.

Adım 5 — Kurulum sihirbazını tamamlayın ve yöneticiyi oluşturun

https://git.example.com adresini hemen açın: siz bitirene kadar kurulum sayfasını herkes görebilir. Veritabanı alanları ortam değişkenlerinden zaten doldurulmuştur (PostgreSQL, db:5432 ana makinesi, kullanıcı ve veritabanı adı). Temel adresin https://git.example.com/, SSH portunun 2222 olduğunu kontrol edin. Ardından yönetici hesabı bölümünü açın, admin olmayan bir kullanıcı adı seçin, e-posta adresinizi ve uzun bir parola girin ve Install seçin.

Kayıt kapalı olduğu için yöneticiyi oluşturmanın zamanı tam olarak budur. Sayfayı yönetici oluşturmadan kapattıysanız onu komut satırından oluşturun; komut rastgele bir parola yazdırır:

docker exec -u git forgejo forgejo admin user create --admin --username git-admin --email [email protected] --random-password

docker exec -u git gitea gitea admin user create --admin --username git-admin --email [email protected] --random-password

Giriş yapın ve Site Administration bölümünü açın. Burada sürümü görür ve ekibiniz için hesap oluşturabilirsiniz. Tüm instance gizli olmalıysa service bölümüne REQUIRE_SIGNIN_VIEW=true da ekleyin (örneğin FORGEJO__service__REQUIRE_SIGNIN_VIEW=true) ve docker compose up -d komutunu yeniden çalıştırın.

İki uygulama da mailer bölümü ayarlandığında hesap etkinleştirme, parola sıfırlama ve bildirim e-postaları gönderir; örneğin environment listesine FORGEJO__mailer__ENABLED=true, FORGEJO__mailer__PROTOCOL=smtp+starttls, FORGEJO__mailer__SMTP_ADDR=smtp.example.com, FORGEJO__mailer__SMTP_PORT=587 değerlerini ve aynı biçimde FROM, USER ile PASSWD anahtarlarını ekleyin (Gitea için önek GITEA__) ve docker compose up -d çalıştırın.

Adım 6 — Güvenlik duvarını açın ve SSH üzerinden Git'i test edin

Sunucu için SSH'ye, Caddy için web portlarına ve Git için 2222 portuna izin verin:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw enable
sudo ufw status verbose

2222 portunu Docker yayınlar ve Docker ufw'yi zaten atlar; kural niyetinizi belgelemeye yarar. 3000 portu 127.0.0.1 adresine bağlı olduğu için dışarıdan erişilemez kalır.

Kullanıcı ayarlarınızda SSH / GPG keys altına açık SSH anahtarınızı ekleyin, ardından bilgisayarınızdan test edip bir depoyu klonlayın:

ssh -T -p 2222 [email protected]
git clone ssh://[email protected]:2222/your-user/your-repo.git

İlk komut kimliğinizin doğrulandığını belirten kısa bir karşılama mesajı yazdırır. İki proje de Git'in ana makinenin 22 portunu kullanmasını sağlayan SSH passthrough yöntemini belgeler; bu yöntem ana makinede ek yapılandırma gerektirir.

Yedekleme ve geri yükleme

Durum bilgisi üç yerde tutulur: PostgreSQL veritabanı, veri klasörü (depolar, ekler, LFS nesneleri ve app.ini ile birlikte ./forgejo veya ./gitea) ve compose.yaml ile .env dosyalarınız. Gitea'nın yedekleme belgeleri tam tutarlı bir yedek için instance'ın kapatılması gerektiğini söyler; Forgejo ise belirli bir ana ait anlık görüntü veya kapatma önerir. Bu nedenle aşağıdaki rutin veritabanını döker, dosyaları arşivlerken server konteynerini kısa süreliğine durdurur ve yeniden başlatır:

sudo mkdir -p /opt/backups && sudo chown $USER:$USER /opt/backups
cd /opt/forgejo
docker compose exec -T db pg_dump -U forgejo forgejo > /opt/backups/forgejo-db-$(date +%F).sql
docker compose stop server
sudo tar czf /opt/backups/forgejo-files-$(date +%F).tar.gz compose.yaml .env forgejo
docker compose start server

sudo mkdir -p /opt/backups && sudo chown $USER:$USER /opt/backups
cd /opt/gitea
docker compose exec -T db pg_dump -U gitea gitea > /opt/backups/gitea-db-$(date +%F).sql
docker compose stop server
sudo tar czf /opt/backups/gitea-files-$(date +%F).tar.gz compose.yaml .env gitea
docker compose start server

İki proje ayrıca yapılandırmayı, veri klasörünü (data/), depoları (repos/) ve bir SQL dosyasını tek bir zip'te toplayan bir dump komutu sunar. Yükseltmelerden önce ve farklı bir düzene taşınırken kullanışlıdır. Forgejo'nun yükseltme rehberi, yeni bir veritabanına yüklenirken bilinen sorunları olduğu için zip içindeki SQL dosyasına güvenmemeyi önerir; bu yüzden pg_dump dosyasını da saklayın. İki imaj da yapılandırmasını /data/gitea/conf/app.ini konumunda tutar:

docker exec -u git -w /tmp forgejo forgejo dump -c /data/gitea/conf/app.ini -f /tmp/forgejo-dump.zip
docker cp forgejo:/tmp/forgejo-dump.zip /opt/backups/forgejo-dump-$(date +%F).zip
docker exec -u git forgejo rm /tmp/forgejo-dump.zip

docker exec -u git -w /tmp gitea gitea dump -c /data/gitea/conf/app.ini -f /tmp/gitea-dump.zip
docker cp gitea:/tmp/gitea-dump.zip /opt/backups/gitea-dump-$(date +%F).zip
docker exec -u git gitea rm /tmp/gitea-dump.zip

Her yedeği sunucunun dışına kopyalayın.

Geri yükleme. Docker kurulu yeni bir sunucuda kullanıcınıza ait boş proje klasörünü oluşturun, dosya arşivini içine açın, yalnızca veritabanını başlatın, PostgreSQL bağlantı kabul etmeye başlayınca SQL dökümünü yükleyin, ardından uygulamayı öncekiyle aynı imaj etiketiyle başlatın:

sudo mkdir -p /opt/forgejo && sudo chown $USER:$USER /opt/forgejo
sudo tar xzf /opt/backups/forgejo-files-2026-10-09.tar.gz -C /opt/forgejo
cd /opt/forgejo
docker compose up -d db
docker compose exec db pg_isready -U forgejo
docker compose exec -T db psql -U forgejo -d forgejo < /opt/backups/forgejo-db-2026-10-09.sql
docker compose up -d server

sudo mkdir -p /opt/gitea && sudo chown $USER:$USER /opt/gitea
sudo tar xzf /opt/backups/gitea-files-2026-10-09.tar.gz -C /opt/gitea
cd /opt/gitea
docker compose up -d db
docker compose exec db pg_isready -U gitea
docker compose exec -T db psql -U gitea -d gitea < /opt/backups/gitea-db-2026-10-09.sql
docker compose up -d server

psql çalıştırmadan önce pg_isready sunucunun bağlantı kabul ettiğini bildirene kadar komutu tekrarlayın. Bunun yerine bir dump zip'inden geri yüklemek için Gitea'nın yedekleme belgelerindeki ve Forgejo'nun Docker imajı için de geçerli olan geri yükleme yöntemini izleyin: arşivi konteyner içinde açın, data/ klasörünü /data/gitea içine ve repos/ klasörünü /data/git/repositories içine kopyalayın, yapılandırmayı /data/gitea/conf/app.ini konumuna geri koyun, chown -R git:git /data çalıştırın, veritabanı dökümünü yükleyin ve admin regenerate hooks ile bitirin. Ardından giriş yapıp birkaç depoyu, issue'yu ve eki açın.

Forgejo veya Gitea güncelleme

Önce tam bir yedek alın ve sürüm notlarını okuyun. Yama ve ara sürümler aynı etiketi yeniden çekerek gelir; ana sürümler için compose.yaml içindeki etiketi değiştirmeniz gerekir.

cd /opt/forgejo
docker exec -u git forgejo forgejo manager flush-queues
docker compose pull
docker compose up -d
docker exec -u git forgejo forgejo doctor check --all --log-file /tmp/doctor.log

cd /opt/gitea
docker compose pull
docker compose up -d
docker compose logs server --tail 50

Forgejo'da güncellemeden önce kuyrukları boşaltmak resmi yöntemin parçasıdır; ardından forgejo doctor check --all hiçbir sorun bildirmemelidir. Forgejo anlamsal sürümlemeyi izler; bu yüzden yalnızca ilk sayının değişmesi (örneğin 16'dan 17'ye) uyumsuz değişiklikler içerebilir ve elle kontrol gerektirir; yükseltme rehberi bu durumda yedeği zorunlu sayar. Forgejo rehberi ayrıca, yedeğe geri dönmek henüz zahmetsizken yükseltmeden hemen sonra web arayüzünde tipik işleri test etmeyi önerir.

Gitea'da imaj etiketini yeni sürüme göre düzenleyin, ardından çekip yeniden başlatın. 28.0.0 sürüm notları uyumsuz değişiklikleri listeler: [server] DOMAIN artık okunmaz, siz açmadıkça kendi kendine kayıt kapalıdır, Actions çalıştırmaları varsayılan olarak 400 gün sonra silinir ve canlı bildirimler proxy üzerinden WebSocket gerektirir. Gitea veritabanını ilk başlangıçta taşır; bu yüzden geri dönmek yedeği geri yüklemek anlamına gelir.

PostgreSQL ana sürümünü (postgres:18) etiketi düzenleyerek değiştirmeyin: yeni bir ana sürüm döküm ve geri yükleme gerektirir.

Sorun giderme

Yeniden başlatmadan sonra kurulum sayfası yine görünüyor

Konteyner kayıtlı app.ini dosyasını bulamıyor. Volume satırının ./forgejo:/data (veya ./gitea:/data) olduğunu, Compose'u proje klasöründen başlattığınızı ve ls ./forgejo/gitea/conf/ (veya ./gitea/gitea/conf/) çıktısında app.ini bulunduğunu kontrol edin.

Klon adresleri 22 portunu gösteriyor veya SSH parola istiyor

SSH_PORT=2222 eksik ya da anahtarınız hesabınıza eklenmemiş. Ortam değişkenini düzeltin, docker compose up -d çalıştırın, anahtarı ayarlarınıza ekleyin ve adresin ssh://[email protected]:2222/... biçimini kullanın. ssh -T -p 2222 [email protected] ile test edin.

pq: password authentication failed for user

PostgreSQL parolayı yalnızca boş bir veri klasörünü ilk kez hazırlarken ayarlar. .env içindeki POSTGRES_PASSWORD değerini sonradan değiştirdiyseniz eski değeri geri koyun veya parolayı PostgreSQL içinde ALTER USER ile değiştirip .env dosyasını buna göre güncelleyin.

server konteyneri /data üzerindeki izin hatalarıyla yeniden başlıyor

Veri klasörünün sahibi USER_UID ve USER_GID değerlerinden farklı bir kullanıcı. Forgejo belgeleri bu durumda konteynerin başlamayabileceğini belirtir. compose.yaml içindeki kimliklere uyacak şekilde sudo chown -R 1000:1000 /opt/forgejo/forgejo (veya Gitea yolu) ile düzeltin.

Gitea 28'de bildirim sayıları güncellenmiyor

Gitea 28 canlı bildirimleri WebSocket'e taşıdı. Caddy bunları kendiliğinden iletir; Nginx'te location bloğuna Upgrade ve Connection başlıklarını ekleyin. Aksi hâlde Gitea yoklama (polling) yöntemine geri döner.

Sonraki adımlar

• Kendi CI/CD'sine sahip hepsi bir arada bir DevOps platformu mu tercih edersiniz? GitLab CE kurulumu rehberine bakın.
• Uygulamaları doğrudan depolarınızdan Coolify ile dağıtın.
• Kod barındırma için sunuculara Gitea hosting sayfasında göz atın.
• Resmi Forgejo belgelerini ve Gitea belgelerini okuyun.