Forgejo

Обзор

Forgejo — свободный Git-сервис для команд и личных проектов. Он объединяет репозитории, code review, задачи, проекты, wiki, releases и package registry, не передавая исходный код внешней платформе.

Этот рецепт запускает закреплённый rootless-образ Forgejo 16.0.3 рядом с PostgreSQL 17. Web-интерфейс и встроенный SSH-сервер привязаны к localhost; открытая регистрация отключена. Forgejo Actions и runner намеренно не входят в рецепт.

Безопасность и публикация

Полный smoke-тест прошёл на amd64 и arm64; backup и restore ещё не проходили практическую проверку. Перед публикацией web нужен HTTPS reverse proxy. SSH следует открывать только после настройки администратора, ключей и firewall. Репозитории, вложения и конфигурация находятся в /var/lib/gitea; база хранится отдельно в PostgreSQL.

Пошаговая инструкция

1. Проверьте сервер

Нужны Ubuntu 22.04+ или Debian 12+, Docker Engine и Compose v2.24+. Выделите минимум 1 CPU, 512 МБ RAM и 5 ГБ диска; рекомендуется 1 ГБ RAM и отдельный запас под Git-репозитории, packages и резервные копии.

docker --version
docker compose version

2. Настройте рецепт

mkdir -p ~/services/forgejo
cd ~/services/forgejo
cp .env.example .env
chmod 600 .env
openssl rand -base64 36

Запишите результат последней команды в POSTGRES_PASSWORD, замените git.example.com реальным доменом и не публикуйте .env. FORGEJO_HTTP_PORT и FORGEJO_SSH_PORT задают локальные порты, FORGEJO_DOMAIN, FORGEJO_SSH_DOMAIN и FORGEJO_ROOT_URL — внешние адреса, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD — доступ к БД, FORGEJO_DATA_VOLUME и FORGEJO_DB_VOLUME — volumes, FORGEJO_BACKUP_DIR — каталог архивов.

3. Запустите и создайте администратора

docker compose config
docker compose pull
docker compose up -d --wait
curl --fail http://127.0.0.1:3000/api/healthz
read -rsp 'Пароль администратора: ' FORGEJO_ADMIN_PASSWORD
docker compose exec forgejo forgejo admin user create --admin --must-change-password --username admin --email admin@example.com --password "$FORGEJO_ADMIN_PASSWORD"
unset FORGEJO_ADMIN_PASSWORD

Пароль не записывается в shell history, но кратковременно передаётся процессу внутри контейнера; сразу смените его через UI. Открытая регистрация отключена. Постоянные данные Forgejo находятся в /var/lib/gitea.

Запуск на VPS

Оставьте оба bind на 127.0.0.1. Публикуйте web через HTTPS proxy. SSH сначала проверяйте через туннель: ssh -L 2222:127.0.0.1:2222 user@server и затем ssh -p 2222 git@localhost. Для публичного Git over SSH замените только bind SSH в compose.yaml на адрес VPS, например ${SERVER_IP}:${FORGEJO_SSH_PORT}:2222, добавьте SERVER_IP в .env и разрешите этот TCP-порт в firewall. Web-порт 3000 оставьте локальным.

Доступ в локальной сети

Предпочтительны VPN или SSH-туннель. Если proxy находится на другом LAN-узле, замените web bind на конкретный приватный IP сервера и разрешите соединения только от proxy. Не используйте 0.0.0.0 без firewall.

Домен и HTTPS

Замените домен в .env и одном файле из proxy/. Caddy получает сертификат автоматически, Nginx ожидает Certbot, Traefik использует resolver letsencrypt. Proxy должен передавать Host, X-Forwarded-Proto и клиентский адрес. Если Traefik работает в контейнере, замените 127.0.0.1 на доступный host gateway.

Резервное копирование

chmod +x backup.sh restore.sh
./backup.sh

Скрипт останавливает Forgejo, делает native pg_dump, архивирует полный data volume и снова запускает сервис. Это согласует Git-репозитории, вложения и БД. Зашифруйте архив: в нём есть приватный код, ключи и конфигурация. Храните копию вне сервера и регулярно проверяйте восстановление.

Восстановление

Восстановление необратимо заменяет data volume и базу. Используйте ту же версию Forgejo, проверьте .env, затем:

./restore.sh ./backups/forgejo-YYYYMMDDTHHMMSSZ.tar
docker compose ps
curl --fail http://127.0.0.1:3000/api/healthz

Процедура ещё не проверена практическим restore-тестом; сначала испытайте её на отдельном сервере.

Обновление

Создайте backup, прочитайте release notes и upgrade guide. Образ закреплён прямо в compose.yaml; замените 16.0.3-rootless на проверенную точную версию и выполните docker compose pull && docker compose up -d --wait. При переходе на новую major-ветку нужны ручная проверка требований и forgejo doctor check --all.

Откат

Не запускайте старый образ поверх мигрированной БД. Верните прежний тег образа и восстановите полный pre-update архив через restore.sh. После миграций откат без восстановления согласованной копии не поддерживается.

Остановка и удаление

docker compose down сохраняет данные. После проверки backup полное удаление:

docker compose down
docker volume rm forgejo-data forgejo-database
rm -rf ~/services/forgejo

Источники: Docker и rootless, upgrade и backup и configuration cheat sheet.

Диагностика

Forgejo не становится healthy

docker compose ps
docker compose logs --tail=200 forgejo database
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q forgejo)"

Проверьте пароль БД, свободное место и доступ к volumes. Endpoint /api/healthz должен вернуть JSON со status: pass.

Ошибка permission denied в /var/lib/gitea

Rootless-контейнер работает как UID/GID 1000. Не меняйте user без переноса владельца данных. Для bind mount заранее выполните chown -R 1000:1000.

В clone URL неверный домен или порт

Проверьте FORGEJO_ROOT_URL, FORGEJO_DOMAIN, FORGEJO_SSH_DOMAIN и FORGEJO_SSH_PORT, затем пересоздайте контейнер: docker compose up -d --force-recreate.

SSH недоступен извне

Это безопасное поведение: порт привязан к localhost. Сначала проверьте его через туннель. Для публичного доступа следуйте разделу VPS, измените только SSH bind и проверьте firewall командой ssh -vvv -p 2222 git@git.example.com.

Ошибка 502 от reverse proxy

Проверьте curl http://127.0.0.1:3000/api/healthz, адрес upstream и доступность localhost из контекста proxy. Контейнерный proxy не видит localhost хоста.