Cara Install Forgejo di Docker: Self-Hosted Git

Forgejo adalah platform self-hosted untuk mengelola repository Git, mirip GitHub atau GitLab, tapi berjalan penuh di server milik kita sendiri. Artikel ini membahas instalasi Forgejo lewat Docker dari nol: menyiapkan Docker Engine, menjalankan container, mengaktifkan HTTPS, sampai membuat repository pertama. Semua perintah di sini diuji dengan acuan Ubuntu Server 26.04 LTS dan Forgejo versi 16.0.3.

Apa Itu Forgejo?

Forgejo adalah perangkat lunak Git server open source yang lahir sebagai soft-fork dari Gitea pada akhir 2022. Bedanya dengan Gitea, Forgejo dikelola oleh komunitas independen di bawah naungan Codeberg, tanpa keterlibatan entitas komersial tunggal yang mengontrol arah pengembangan.

Kita bisa memakai Forgejo untuk menggantikan GitHub atau GitLab ketika tim ingin kontrol penuh atas data source code, tanpa batasan jumlah repository privat atau ketergantungan pada layanan pihak ketiga. Dibanding GitLab Community Edition yang cukup berat untuk server kecil, Forgejo jauh lebih ringan karena ditulis dengan Go dan hanya butuh satu binary untuk berjalan.

Sysadmin yang mengelola infrastruktur internal biasanya memilih Forgejo untuk menghosting kode milik tim Developer, sekaligus menjaga agar source code tidak pernah keluar dari jaringan perusahaan.

Persyaratan Sebelum Instalasi

Dokumentasi resmi Forgejo tidak mencantumkan angka pasti untuk kebutuhan CPU dan RAM minimum. Sebagai gambaran praktis, instance kecil dengan database SQLite dan beberapa pengguna bisa berjalan nyaman di 1 vCPU dan 1 GB RAM. Untuk tim dengan trafik lebih tinggi dan database PostgreSQL, alokasikan minimal 2 vCPU dan 2-4 GB RAM. Catat baik-baik: ini estimasi praktis, bukan spesifikasi resmi dari tim Forgejo, jadi tetap pantau pemakaian resource setelah instance berjalan.

Yang wajib disiapkan sebelum mulai:

Server dengan Ubuntu Server 26.04 LTS (atau distribusi Linux lain yang mendukung Docker)
Docker Engine dan plugin Docker Compose
Domain atau subdomain yang sudah mengarah ke IP server, jika ingin mengaktifkan HTTPS
Port 80, 443, dan port SSH kustom (di artikel ini kita pakai 222) yang tidak dipakai service lain
Ruang disk minimal 10 GB, dengan pertumbuhan mengikuti jumlah dan ukuran repository

Untuk database, Forgejo mendukung SQLite (tanpa instalasi tambahan), PostgreSQL versi 14 ke atas, MySQL versi 8.4 ke atas, dan MariaDB versi 10.6 ke atas. SQLite cocok untuk instance kecil atau percobaan, sedangkan PostgreSQL jadi pilihan yang lebih matang untuk production karena lebih tangguh menangani query bersamaan dari banyak user.

Instalasi Docker Engine di Ubuntu

Ikuti empat langkah berurutan berikut untuk memasang Docker Engine dari repository resmi.

Hapus package Docker versi lama yang mungkin terpasang dari repository non-resmi. Package seperti docker.io, docker-compose, atau podman-docker sering bentrok dengan Docker Engine resmi.
```
sudo apt remove docker.io docker-compose podman-docker
```

Tambahkan GPG key dan repository resmi Docker ke sistem.

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

Install Docker Engine beserta plugin Buildx dan Compose.

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verifikasi instalasi dengan menjalankan image percobaan resmi Docker. Kalau muncul pesan "Hello from Docker!", instalasi berhasil dan siap dipakai untuk menjalankan Forgejo.
```
sudo docker run hello-world
```

Menyiapkan Struktur Folder dan Compose File

Buat direktori kerja untuk menyimpan file konfigurasi dan data Forgejo. Pisahkan folder data agar mudah dibackup terpisah dari file compose.

mkdir -p ~/forgejo/{forgejo,postgres}
cd ~/forgejo

Selanjutnya buat file compose.yaml di direktori tersebut. File ini mendefinisikan service Forgejo, database, network, dan volume yang dipakai bersama.

Dua environment variable penting di sini adalah USER_UID dan USER_GID. Keduanya menentukan pemilik file di dalam volume data. Folder volume di host harus dimiliki oleh UID/GID yang sama dengan nilai ini, kalau tidak, container bisa gagal start karena masalah permission.

Memilih Database: SQLite atau PostgreSQL

SQLite adalah pilihan paling sederhana karena tidak butuh service tambahan, cocok untuk instance kecil atau evaluasi awal. Kelemahannya, SQLite kurang optimal saat banyak proses menulis ke database secara bersamaan, sesuatu yang lazim terjadi di instance dengan banyak Developer aktif.

Untuk kebutuhan production, kita pakai PostgreSQL. Berikut isi lengkap compose.yaml dengan PostgreSQL sebagai backend database:

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:16.0.3
    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=ganti-dengan-password-kuat
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: forgejo-db
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=ganti-dengan-password-kuat
      - POSTGRES_DB=forgejo
    networks:
      - forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

networks:
  forgejo:
    external: false

Wajib diperhatikan: ganti nilai ganti-dengan-password-kuat di kedua tempat dengan password yang sama dan kuat. Jangan biarkan kredensial default ini tersimpan di server production.

Format penamaan environment variable FORGEJO__database__DB_TYPE mengikuti pola FORGEJO__[SECTION]__[KEY], yang secara langsung memetakan ke isi file konfigurasi app.ini milik Forgejo. Pola ini berlaku untuk hampir semua opsi konfigurasi Forgejo, jadi kita bisa mengatur banyak hal lewat environment variable tanpa perlu masuk ke dalam container.

Menjalankan Container Forgejo

Tiga langkah berurutan berikut menjalankan Forgejo dan memastikan container benar-benar stabil.

Samakan kepemilikan folder data dengan UID/GID yang didefinisikan di compose file.
```
sudo chown -R 1000:1000 ~/forgejo/forgejo
```
Jalankan seluruh stack dengan Docker Compose.
```
sudo docker compose up -d
```
Cek status container untuk memastikan keduanya berjalan tanpa restart loop.
```
sudo docker compose ps
```

Kalau status Forgejo terus berpindah dari Up ke Restarting, cek log untuk mencari akar masalahnya, biasanya seputar koneksi database atau permission folder:

sudo docker compose logs -f forgejo

Konfigurasi Awal via Web Installer

Setelah container stabil, akses http://alamat-server:3000 dari browser. Karena kredensial database sudah diisi lewat environment variable, wizard instalasi biasanya langsung menampilkan halaman konfigurasi umum seperti nama aplikasi, URL server, dan pembuatan akun admin pertama.

Isi bagian Administrator Account Settings dengan username, email, dan password admin. Akun ini punya akses penuh ke seluruh instance, jadi gunakan password yang kuat dan unik.

Alternatifnya, kita bisa membuat akun admin lewat command line interface tanpa membuka web installer ke publik, cara yang lebih aman untuk server production:

sudo docker exec forgejo forgejo admin user create \
  --username admin \
  --password ganti-password-admin \
  --email [email protected] \
  --admin

Pendekatan CLI ini berguna kalau kita ingin menutup akses port 3000 dari luar sejak awal dan hanya membuka lewat reverse proxy setelah admin pertama dibuat.

Reverse Proxy dengan Nginx

Menjalankan Forgejo langsung di port 3000 tanpa reverse proxy bukan praktik yang disarankan untuk production. Nginx sebagai reverse proxy memudahkan kita mengatur HTTPS, domain, dan header keamanan di satu tempat.

Install Nginx lewat package manager.
```
sudo apt install nginx
```

Buat file konfigurasi baru di /etc/nginx/conf.d/forgejo.conf.

server {
    listen 80;
    listen [::]:80;
    server_name git.contoh.com;
    merge_slashes off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
        client_max_body_size 512M;
    }
}

Header X-Real-IP dan X-Forwarded-For penting supaya Forgejo mencatat IP asli Visitor atau Developer yang mengakses, bukan IP internal Nginx. Opsi merge_slashes off mencegah Nginx menggabungkan garis miring berurutan pada URL, yang bisa mengganggu beberapa endpoint Git. Nilai client_max_body_size 512M menaikkan batas ukuran upload, penting untuk push repository berukuran besar.

Uji konfigurasi lalu reload Nginx.

sudo nginx -t
sudo systemctl reload nginx

Mengaktifkan HTTPS dengan Let's Encrypt

Setelah domain mengarah ke server dan Nginx berjalan normal di port 80, saatnya aktifkan HTTPS. Pastikan port 80 dan 443 sudah terbuka di firewall sebelum lanjut.

Install Certbot beserta plugin Nginx-nya.

sudo apt install certbot python3-certbot-nginx

Jalankan Certbot untuk domain yang dituju. Certbot otomatis menyisipkan konfigurasi SSL ke file Nginx yang sudah dibuat sebelumnya dan mengalihkan trafik HTTP ke HTTPS.
```
sudo certbot --nginx -d git.contoh.com
```

Sertifikat Let's Encrypt berlaku 90 hari, tapi paket certbot di Ubuntu sudah menyertakan systemd timer yang menjalankan perpanjangan otomatis. Cek jadwalnya dengan:

sudo systemctl list-timers | grep certbot

Konfigurasi DOMAIN, SSH_DOMAIN, dan ROOT_URL di app.ini

Setelah HTTPS aktif dan domain sudah resolve ke server lewat Nginx, saatnya menyesuaikan beberapa opsi inti Forgejo yang menentukan bagaimana instance ini membentuk URL, baik untuk tautan web, payload webhook, maupun URL clone yang ditampilkan di halaman repository.

File konfigurasi utama Forgejo ada di ~/forgejo/forgejo/gitea/conf/app.ini pada host, hasil mapping dari volume ./forgejo:/data yang sudah dibuat sejak awal instalasi (path di dalam container: /data/gitea/conf/app.ini). Buka file ini dengan editor teks, cari section [server], lalu sesuaikan tiga opsi berikut:

[server]
DOMAIN         = git.contoh.com
ROOT_URL       = https://git.contoh.com/
SSH_DOMAIN     = git.contoh.com
SSH_PORT       = 222

DOMAIN dipakai Forgejo untuk membangun URL internal dan cookie domain. Nilainya harus sama dengan domain publik yang diakses lewat Nginx, kalau berbeda, beberapa fitur seperti redirect login atau webhook bisa salah alamat.
ROOT_URL adalah URL lengkap yang muncul di tautan web, isi payload webhook, dan clone URL HTTPS di halaman repository. Wajib pakai skema https:// karena SSL sudah di-terminate di Nginx, bukan di Forgejo sendiri.
SSH_DOMAIN dan SSH_PORT menentukan domain dan port yang ditampilkan Forgejo di tab SSH pada tombol Clone. Samakan SSH_PORT dengan pemetaan port 222 yang sudah diatur di compose.yaml, supaya URL clone SSH yang ditampilkan di web langsung benar tanpa perlu diedit manual oleh Developer.

Simpan perubahan, lalu restart container agar konfigurasi baru terbaca:

sudo docker compose restart forgejo

Setup SSH untuk Operasi Git

Port SSH Forgejo sudah dipetakan ke 222 di host lewat compose.yaml sebelumnya, supaya tidak bentrok dengan SSH daemon utama server yang biasanya memakai port 22. Karena port-nya tidak standar dan tiap Developer punya key khusus untuk Forgejo, langkah paling praktis adalah menyimpan detail koneksi ini di SSH client config milik masing-masing user, supaya tidak perlu mengetik ulang port dan path key setiap kali push atau pull. Developer mengikuti lima langkah berurutan berikut.

Generate key pair SSH khusus untuk Forgejo di komputer masing-masing. Memberi nama file terpisah (bukan id_ed25519 default) memudahkan kalau user sudah punya key lain untuk keperluan berbeda.
```
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519_forgejo
```
Tambahkan entry berikut ke file ~/.ssh/config milik user (buat file ini kalau belum ada).
```
Host git.contoh.com
    HostName git.contoh.com
    Port 222
    User git
    IdentityFile ~/.ssh/id_ed25519_forgejo
    IdentitiesOnly yes
```
Dengan konfigurasi ini, SSH client otomatis memakai port 222 dan key yang benar setiap kali host-nya cocok dengan git.contoh.com, tanpa perlu menambahkan opsi -p 222 atau -i secara manual di setiap perintah.
Salin isi public key (~/.ssh/id_ed25519_forgejo.pub), lalu tempelkan di menu Settings > SSH / GPG Keys pada akun Forgejo masing-masing user.
Uji koneksi dari sisi client. Berkat ~/.ssh/config, port dan key sudah otomatis terpakai. Kalau muncul pesan sambutan dari Forgejo yang menyebutkan username, koneksi SSH sudah berfungsi.
```
ssh -T [email protected]
```
Clone repository lewat SSH. Karena port sudah didefinisikan di ~/.ssh/config, format URL-nya jadi sesederhana clone SSH biasa tanpa perlu menyisipkan nomor port.
```
git clone [email protected]:username/nama-repo.git
```

Membuat Repository Pertama

Tiga langkah berurutan berikut menguji alur kerja Git secara end-to-end di instance yang baru dipasang.

Login ke dashboard Forgejo di https://git.contoh.com, lalu klik tombol New Repository. Isi nama repository, deskripsi singkat, dan pilih visibility (public atau private) sesuai kebutuhan tim.
Clone repository yang baru dibuat ke komputer lokal lewat HTTPS atau SSH.
```
git clone https://git.contoh.com/username/nama-repo.git
cd nama-repo
```

Push commit pertama untuk memastikan alur autentikasi sampai penyimpanan di server berjalan normal.

echo "# Nama Repo" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Kalau push berhasil tanpa error, seluruh rantai instalasi, dari container, database, reverse proxy, HTTPS, sampai SSH, sudah terkonfirmasi berfungsi.

Backup dan Update Forgejo

Forgejo menyediakan perintah bawaan forgejo dump yang mengompresi database, repository, log, dan data pendukung lain ke satu file arsip. Jalankan dari dalam container:

sudo docker exec forgejo forgejo dump -f /data/forgejo-backup.zip

Karena folder /data di dalam container terhubung ke ~/forgejo/forgejo di host lewat volume, file backup otomatis muncul di folder tersebut dan bisa langsung disalin ke penyimpanan terpisah. Jadwalkan perintah ini lewat cron agar backup berjalan rutin, misalnya setiap malam.

Update ke versi Forgejo terbaru mengikuti tiga langkah berurutan berikut.

Buka compose.yaml dan ganti tag image forgejo ke versi yang dituju.
Tarik image baru.
```
sudo docker compose pull forgejo
```
Restart container dengan image yang baru.
```
sudo docker compose up -d forgejo
```

Cek dulu changelog resmi sebelum update ke versi mayor baru. Beberapa rilis besar membawa perubahan skema database yang butuh proses migrasi otomatis saat container pertama kali start, jadi pastikan backup terbaru sudah tersedia sebelum proses ini dijalankan.

Keamanan Dasar yang Wajib Diaktifkan

Beberapa langkah berikut layak jadi standar minimum sebelum instance dipakai serius oleh tim:

Batasi akses firewall hanya ke port 80, 443, dan port SSH kustom (222). Jangan buka port 3000 langsung ke internet, karena traffic ke port itu seharusnya hanya lewat Nginx di localhost.
Nonaktifkan pendaftaran user terbuka lewat FORGEJO__service__DISABLE_REGISTRATION=true di compose file, kecuali instance memang ditujukan untuk publik.
Aktifkan autentikasi dua faktor untuk akun admin, supaya Attacker yang berhasil mencuri password tetap tidak bisa masuk tanpa faktor kedua.
Pantau log akses SSH dan HTTP secara berkala untuk mendeteksi percobaan brute force lebih dini.

Troubleshooting Masalah Umum

Beberapa masalah yang paling sering muncul saat instalasi:

Container terus restart setelah docker compose up. Penyebab paling umum adalah folder volume yang belum sesuai kepemilikan UID/GID. Jalankan lagi sudo chown -R 1000:1000 ~/forgejo/forgejo, lalu restart container.

Nginx menampilkan error 502 Bad Gateway. Biasanya berarti container Forgejo belum berjalan atau proxy_pass menunjuk ke port yang salah. Cek dengan docker compose ps dan pastikan port 3000 di proxy_pass cocok dengan port yang dipetakan di compose file.

Koneksi SSH ditolak (connection refused). Cek apakah port 222 sudah terbuka di firewall server dan tidak bentrok dengan service lain. Jalankan sudo ss -tulpn | grep 222 untuk memastikan port benar-benar didengarkan oleh container.

Push atau pull ditolak dengan pesan permission denied. Pastikan public key sudah tertaut ke akun yang benar di menu SSH Keys, dan user punya hak akses write ke repository tujuan.

Kesimpulan

Forgejo di Docker memberi kita Git server sendiri yang ringan, cepat dijalankan, dan mudah dipelihara lewat satu file compose.yaml. Dari sisi resource, instance ini jauh lebih hemat dibanding GitLab, tanpa kehilangan fitur inti yang dibutuhkan tim Developer sehari-hari: pull request, issue tracker, dan Actions untuk automasi CI/CD.