Установка и настройка Forgejo на VPS: создание собственного

1. Що таке Forgejo і чому це найкращий вибір у 2026 році

Forgejo (вимовляється як «фор-джей-о») — це форк Gitea, створений спільнотою у відповідь на комерціалізацію оригінального проєкту. У 2026 році Forgejo став стандартом де-факто для тих, хто шукає «золоту середину» між важковаговим GitLab та занадто аскетичними рішеннями на зразок SourceHut.

Основна філософія Forgejo — "Liberated Software". Це означає, що всі функції, включаючи просунутий CI/CD та реєстр пакетів, доступні безкоштовно та з відкритим вихідним кодом. На відміну від Gitea, де деякі корпоративні функції можуть бути обмежені або орієнтовані на платних клієнтів, Forgejo розвивається як проєкт, що належить спільноті.

Ключові переваги для власника VPS:

• Низьке споживання ресурсів: У режимі очікування Forgejo споживає менше 200 МБ оперативної пам'яті.
• Бінарна сумісність: Якщо ви раніше використовували Gitea, перехід на Forgejo займає 5 хвилин без втрати даних.
• Вбудований CI/CD: Більше не потрібно налаштовувати складні зв'язки з Jenkins або Drone CI. Forgejo Actions розуміє синтаксис YAML-файлів GitHub Actions.
• Єдиний інструмент: Код, тікети (issues), канбан-дошки, вікі та реєстр контейнерів знаходяться в одному інтерфейсі.

2. Порівняння Forgejo з альтернативами (GitLab, Gitea, GitHub)

При виборі Git-платформи для хостингу на власному сервері важливо розуміти різницю у ресурсовитратах та функціоналі. Нижче наведена порівняльна таблиця актуальних рішень на 2026 рік.

GitLab є потужним комбайном, але його встановлення на дешевий VPS часто призводить до "зависань" через нестачу пам'яті. Forgejo ж ідеально підходить для індивідуальних розробників та команд до 50 осіб, які працюють на бюджетному залізі.

3. Який VPS-конфіг потрібен під цю задачу

Хоча Forgejo вкрай невимогливий, продуктивність вашого Git-хостингу буде напряму залежати від швидкості дискової підсистеми та об'єму оперативної пам'яті для кешування Git-об'єктів.

Мінімальні вимоги (1-3 користувача, маленькі проєкти):

• CPU: 1 ядро
• RAM: 1 ГБ
• Disk: 20 ГБ SSD/NVMe
• OS: Ubuntu 24.04 LTS або Debian 13

Рекомендовані вимоги (команда, CI/CD, Docker Registry):

• CPU: 2-4 ядра (важливо для швидкої збірки контейнерів у CI/CD)
• RAM: 4 ГБ (дозволяє тримати в кеші БД та ефективно працювати ранерам)
• Disk: 50+ ГБ NVMe (обсяг залежить від кількості Docker-образів, що зберігаються)
• Мережа: 1 Гбіт/с (для швидкого завантаження/вивантаження великих репозиторіїв)

Для стабільної роботи системи, особливо якщо ви плануєте активно використовувати Forgejo Actions для збірки проєктів, найкраще підійде відповідний VPS з виділеними ресурсами, щоб процеси збірки не сповільнювали роботу веб-інтерфейсу.

Локація сервера також має значення: вибирайте дата-центр з мінімальним пінгом до ваших розробників, оскільки протоколи Git (SSH/HTTPS) чутливі до затримок при передачі безлічі дрібних файлів.

4. Підготовка сервера: базова безпека та системні утиліти

Перш ніж встановлювати Docker, необхідно убезпечити сервер. Ми налаштуємо брандмауер, створимо окремого користувача та встановимо захист від брутфорсу.

Оновіть список пакетів і систему до актуального стану:

sudo apt update && sudo apt upgrade -y

Встановіть необхідні базові інструменти:

sudo apt install -y curl wget git vim ufw fail2ban software-properties-common

Налаштуйте брандмауер UFW. Нам знадобляться порти 22 (SSH), 80 (HTTP), 443 (HTTPS) і порт 2222 для Git через SSH (щоб не конфліктувати з основним SSH-сервером системи):

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw enable

Налаштування Fail2Ban допоможе захистити SSH від підбору паролів. Створіть локальний конфіг:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Створіть системного користувача, від імені якого працюватиме Forgejo (для безпеки не рекомендується запускати сервіс від root, навіть всередині контейнера):

sudo adduser --disabled-password --gecos "" git

5. Встановлення Docker та Docker Compose

У 2026 році використання Docker є стандартом для self-hosted сервісів. Це спрощує оновлення та перенесення Forgejo на інший сервер.

Встановіть офіційний репозиторій Docker:

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

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Встановіть Docker Engine та Docker Compose Plugin:

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

Додайте поточного користувача до групи docker, щоб запускати команди без sudo:

sudo usermod -aG docker $USER

Примітка: після цієї команди потрібно перелогінитися в терміналі.

6. Розгортання Forgejo: Docker Compose та база даних

Ми будемо використовувати PostgreSQL як базу даних, оскільки вона надійніша за SQLite при зростанні кількості репозиторіїв та активному використанні CI/CD.

Створіть робочу директорію:

mkdir -p ~/forgejo && cd ~/forgejo

Створіть файл docker-compose.yml з наступною конфігурацією:

services:
  server:
    image: codeberg.org/forgejo/forgejo:10
    container_name: forgejo
    restart: always
    environment:
      - USER_UID=1001
      - USER_GID=1001
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=your_strong_password
    volumes:
      - ./data:/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: postgres:16-alpine
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=your_strong_password
      - POSTGRES_DB=forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

Важливо: Замініть your_strong_password на реальний пароль. Зверніть увагу, що веб-інтерфейс Forgejo ми прокидаємо на 127.0.0.1:3000. Це робиться для того, щоб він не був доступний ззовні напряму, а тільки через наш Reverse Proxy (Caddy).

Запустіть контейнери:

docker compose up -d

7. Налаштування Reverse Proxy та автоматичного HTTPS через Caddy

Caddy — це сучасний веб-сервер, який автоматично отримує та оновлює SSL-сертифікати від Let's Encrypt. Це набагато простіше, ніж налаштовувати Nginx з Certbot.

Встановіть Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Відредагуйте /etc/caddy/Caddyfile:

git.yourdomain.com {
    reverse_proxy localhost:3000
    
    header {
        # Налаштування безпеки
        Strict-Transport-Security "max-age=31536000;"
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
}

Замініть git.yourdomain.com на ваш реальний домен, який має бути направлений на IP вашого VPS (A-запис). Перезапустіть Caddy:

sudo systemctl restart caddy

Тепер ви можете відкрити https://git.yourdomain.com у браузері та завершити встановлення Forgejo через веб-інтерфейс. Перший зареєстрований користувач автоматично стане адміністратором.

8. Налаштування Forgejo Actions: запуск CI/CD раннера

Forgejo Actions — це потужна вбудована система автоматизації. Для її роботи потрібен окремий компонент — Runner, який буде виконувати команди збірки.

Спочатку увімкніть підтримку Actions у Forgejo. Відкрийте файл конфігурації всередині контейнера або додайте змінну оточення в docker-compose.yml:

# Додайте в секцію environment сервісу server в docker-compose.yml:
- FORGEJO__actions__ENABLED=true

Тепер додамо сервіс раннера в наш docker-compose.yml:

  runner:
    image: codeberg.org/forgejo/runner:6.0
    container_name: forgejo-runner
    restart: always
    depends_on:
      - server
    volumes:
      - ./runner-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - FORGEJO_INSTANCE_URL=https://git.yourdomain.com
      - FORGEJO_RUNNER_REGISTRATION_TOKEN=ВАШ_ТОКЕН_З_АДМІНКИ
      - FORGEJO_RUNNER_NAME=vps-runner
      - FORGEJO_RUNNER_LABELS=ubuntu-latest:docker://node:20-bullseye,debian-latest:docker://debian:bookworm

Щоб отримати FORGEJO_RUNNER_REGISTRATION_TOKEN, зайдіть в панель управління Forgejo: Site Administration -> Actions -> Runners -> Create new Runner.

Запустіть раннер:

docker compose up -d runner

Тепер будь-який репозиторій, в якому є файл .forgejo/workflows/build.yml, буде автоматично запускати збірку на вашому VPS.

9. Налаштування вбудованого Docker Registry

Forgejo дозволяє зберігати Docker-образи прямо в репозиторії проєкту. Це позбавляє від необхідності використовувати Docker Hub або платні аналоги.

За замовчуванням реєстр пакетів увімкнено. Щоб авторизуватися в ньому з локальної машини, використовуйте стандартну команду docker login:

docker login git.yourdomain.com

Використовуйте ваше ім'я користувача та пароль (або Personal Access Token, що безпечніше). Приклад тегування та пушу образа:

docker tag my-app:latest git.yourdomain.com/username/my-app:latest
docker push git.yourdomain.com/username/my-app:latest

Всі образи зберігаються в папці /data/packages всередині контейнера Forgejo, що дозволяє легко керувати дисковим простором.

10. Бекапи та регламент обслуговування

Відсутність бекапів — головна помилка при self-хостингу. В Forgejo потрібно бекапити три речі: базу даних, конфігураційні файли (app.ini) і самі репозиторії.

Створіть простий скрипт бекапу backup.sh:

#!/bin/bash
BACKUP_DIR="/home/user/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
mkdir -p $BACKUP_DIR

# Бекап бази даних
docker exec forgejo-db-1 pg_dump -U forgejo forgejo > $BACKUP_DIR/db_$TIMESTAMP.sql

# Бекап даних Forgejo (конфіги і репозиторії)
tar -czf $BACKUP_DIR/data_$TIMESTAMP.tar.gz ./data

# Видалення старих бекапів (старше 7 днів)
find $BACKUP_DIR -type f -mtime +7 -delete

Додайте виконання скрипта в crontab (crontab -e), щоб він запускався кожної ночі о 3:00:

0 3   * /bin/bash /home/user/forgejo/backup.sh

Оновлення Forgejo: Процес оновлення вкрай простий завдяки Docker. Достатньо змінити версію образу в docker-compose.yml та виконати:

docker compose pull
docker compose up -d

11. Troubleshooting + FAQ

Помилка: "SSH connection refused" при спробі git push

Перевірте, що ви використовуєте правильний порт. За замовчуванням SSH в нашому конфігу працює на порту 2222. Ваш URL репозиторію має виглядати так: ssh://[email protected]:2222/user/repo.git. Також переконайтеся, що ваш публічний SSH-ключ додано до профілю Forgejo.

Який VPS-конфіг мінімально підійде для Forgejo?

Для комфортної роботи одного розробника достатньо 1 ГБ RAM та 1 ядра CPU. Однак, якщо ви включите Forgejo Actions (CI/CD), при запуску компіляції (наприклад, на Go або Rust) споживання пам'яті може миттєво підскочити до 2-4 ГБ. Для таких задач краще брати тариф з 4 ГБ оперативної пам'яті.

Що вибрати — VPS або dedicated для цієї задачі?

Для більшості команд до 20 осіб VPS — ідеальний вибір. Dedicated-сервер варто розглядати тільки в двох випадках: якщо обсяг вашого коду та артефактів (Docker Registry) перевищує 1-2 ТБ, або якщо вам потрібна абсолютна ізоляція ресурсів для важких CI/CD процесів, які не повинні впливати на чутливість інтерфейсу Git.

Як обмежити реєстрацію нових користувачів?

Після створення свого облікового запису адміністратора, зайдіть в Site Administration -> Configuration та встановіть DISABLE_REGISTRATION = true. Це запобіжить створенню облікових записів сторонніми людьми на вашому публічному сервері.

Forgejo споживає занадто багато місця на диску, що робити?

Основними споживачами місця зазвичай є Docker Registry та логи білдів. Регулярно очищайте старі образи та налаштуйте політику утримання (Retention Policy) в налаштуваннях пакетів Forgejo. Також перевірте папку /data/tmp, іноді там можуть накопичуватися тимчасові файли після невдалих імпортів.

Чи можна перенести дані з GitHub?

Так, Forgejo має вбудований інструмент міграції. Він дозволяє імпортувати не тільки код, але й Issues, Pull Requests, Wiki і навіть Milestone. Для цього достатньо вказати URL репозиторію GitHub і ваш Personal Access Token.

12. Висновки та наступні кроки

Ми успішно розгорнули професійне середовище розробки на власному VPS. Тепер у вас є повний контроль над своїм кодом, образами контейнерів і процесами автоматизації, без залежності від політики сторонніх хмарних провайдерів.

Що ми отримали:

• Приватний Git-хостинг з високою продуктивністю.
• Автоматичний SSL через Caddy.
• Власну систему CI/CD, сумісну з GitHub Actions.
• Docker Registry для зберігання приватних образів.

Куди рухатися далі:

1. Моніторинг: Налаштуйте експорт метрик Forgejo в Prometheus і візуалізуйте їх в Grafana, щоб відстежувати навантаження на сервер.
2. Безпека: Налаштуйте двофакторну аутентифікацію (2FA) для свого аккаунта.
3. Зовнішнє сховище: Якщо плануєте зберігати терабайти даних, налаштуйте зберігання об'єктів (LFS і пакети) в S3-сумісному сховищі.

Self-hosting — це не тільки економія коштів, але й важливий крок до цифрового суверенітету вашої команди або проєкту. Forgejo надає для цього всі необхідні інструменти, залишаючись простим і надійним рішенням.