Установка Gitea на Debian 11 с PostgreSQL (из бинарника)

Введение

Gitea — это свободное, с открытым исходным кодом решение для self-hosted Git-серверов, написанное на Go. Это компактное и быстрое приложение, доступное в виде статического бинарного файла, которое можно запускать на Windows, Linux и macOS. Gitea подходит как легковесная альтернатива GitLab: работает быстро, масштабируется и простое в эксплуатации.

Кратко: Gitea предоставляет веб-интерфейс для репозиториев, встроенный редактор файлов, баг-трекер, управление ветвями, встроенную вики, поддержку LFS, контейнерный реестр и несколько СУБД (PostgreSQL, MySQL, MariaDB, SQLite).

Определение: self-hosted — развёртывание ПО на сервере, контролируемом вами, а не сторонним SaaS-провайдером.

Что вы получите из этой инструкции

• Полный набор команд для установки Gitea из бинарника на Debian 11.
• Настройка PostgreSQL с SCRAM-SHA-256 и созданием базы для Gitea.
• Создание системного пользователя git и systemd-сервиса для запуска Gitea.
• Примеры конфигурации app.ini, настройка почты и советы по обновлению.
• Рекомендации безопасности, тесты приёмки, чек-листы для ролей и сценарии восстановления.

Требования

• Сервер с установленным Debian 11.
• Доступ с правами sudo или root.
• Открытые порты (3000 для HTTP по умолчанию, 22 для SSH, 5432 для PostgreSQL при удалённом доступе).

Шаг 1 — Обновление системы

Перед началом обновите пакеты:

sudo apt-get update -y
sudo apt-get upgrade -y

Важно: всегда делайте снапшот/резервную копию перед обновлением в production-среде.

Шаг 2 — Установка и настройка PostgreSQL

Gitea поддерживает PostgreSQL, MySQL/MariaDB и SQLite. В этом руководстве используется PostgreSQL.

1. Добавьте репозиторий PostgreSQL:

sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

2. Импортируйте ключ подписания репозитория:

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

3. Установите PostgreSQL:

sudo apt-get update
sudo apt-get -y install postgresql

4. Запустите службу и включите автозапуск:

sudo systemctl start postgresql
sudo systemctl enable postgresql
sudo systemctl status postgresql

По умолчанию PostgreSQL использует md5 для паролей на некоторых версиях. Для повышения безопасности переключитесь на SCRAM-SHA-256, который устойчивее к перебору.

Откройте конфигурационный файл (путь зависит от версии PostgreSQL, в примере — 14):

sudo vim /etc/postgresql/14/main/postgresql.conf

Измените и/или добавьте строки:

listen_addresses = 'localhost, 134.122.38.45'
password_encryption = scram-sha-256

Замените IP на ваш(и). Сохраните файл и перезапустите PostgreSQL:

sudo systemctl restart postgresql

5. Создайте роль и базу данных для Gitea:

sudo -u postgres psql

В psql выполните:

CREATE ROLE gitea WITH LOGIN PASSWORD 'secure@123';
CREATE DATABASE giteadb;
GRANT ALL PRIVILEGES ON DATABASE giteadb TO gitea;
\q

Замените ‘secure@123’ на надежный пароль. Запишите имя пользователя, пароль и имя базы — они понадобятся при настройке Gitea.

6. Настройка контроля доступа (pg_hba.conf):

Откройте /etc/postgresql/14/main/pg_hba.conf и убедитесь, что локальные соединения принимаются через scram-sha-256:

host    all             all             127.0.0.1/32            scram-sha-256

Если требуется удалённый доступ для конкретной подсети или хоста, добавьте:

host    giteadb         gitea           134.122.38.0/32         scram-sha-256

Затем перезапустите PostgreSQL и проверьте подключение с сервера Gitea.

Совет: ограничьте список IP, которым разрешён доступ, и используйте VPN/Private Network для доступа к БД в продакшене.

Шаг 3 — Установка и настройка Git

Установите git:

sudo apt install -y git

Проверьте версию:

git --version

Ожидаемый вывод (пример):

git version 2.30.2

Настройте глобальные имя и почту (они используются для коммитов, выполняемых на сервере):

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Проверить:

git config --list

Шаг 4 — Создание системного пользователя git

Gitea запускается под отдельным системным юзером. Создайте его:

sudo adduser \
  --system \
  --shell /bin/bash \
  --gecos 'Git Version Control' \
  --group \
  --disabled-password \
  --home /home/git \
  git

Права пользователя git ограничивают область доступа файлов Gitea.

Шаг 5 — Установка и базовая конфигурация Gitea

1. Скачайте бинарник Gitea. На момент написания примера версия — 1.15.7. Замените переменную VERSION на актуальную.

cd /tmp
GITEAVERSION=1.15.7
wget -O gitea https://dl.gitea.io/gitea/${GITEAVERSION}/gitea-${GITEAVERSION}-linux-amd64

2. Переместите бинарный файл и дайте права на исполнение:

sudo mv /tmp/gitea /usr/local/bin
sudo chmod +x /usr/local/bin/gitea

3. Создайте структуру директорий и назначьте права:

sudo mkdir -p /etc/gitea
sudo mkdir -p /var/lib/gitea/{custom,data,indexers,public,log}
sudo chown -R git:git /var/lib/gitea/
sudo chown root:git /etc/gitea
sudo chmod -R 750 /var/lib/gitea/
sudo chmod 770 /etc/gitea

4. Создайте systemd-сервис для управления:

sudo vim /etc/systemd/system/gitea.service

Вставьте:

[Unit]
Description=Gitea
After=syslog.target
After=network.target
After=postgresql.service

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web -c /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

Сохраните, затем примените и запустите сервис:

sudo systemctl daemon-reload
sudo systemctl start gitea
sudo systemctl enable gitea
sudo systemctl status gitea

По умолчанию Gitea слушает порт 3000. Проверить можно так:

netstat -tulpan | grep 3000

Ожидаемый вывод (пример):

tcp6       0      0 :::3000                 :::*                    LISTEN      43778/gitea

Если netstat отсутствует, установите paket: sudo apt install -y net-tools или используйте ss.

Шаг 6 — Доступ к веб-интерфейсу и первичная настройка

Откройте в браузере http://YOUR_IP_ADDRESS:3000 (или https, если вы настроите обратный прокси с TLS).

В формах установки укажите параметры базы и общие параметры сайта.

Database Settings:

• Database Type: PostgreSQL
• Host: 127.0.0.1:5432
• Username: gitea
• Password: пароль, который вы задали в PostgreSQL
• Database Name: giteadb
• SSL: Disable (или включите, если используете SSL)

General Settings:

• Site Title: любое имя
• Repository Root Path: /var/lib/gitea/data/repositories
• Git LFS Root Path: /var/lib/gitea/data/lfs
• Run As Username: git
• SSH Server Domain: your_domain_or_IP
• SSH Server Port: 22
• Gitea HTTP Listen Port: 3000
• Gitea Base URL: http://YOUR_IP_ADDRESS:3000
• Log Path: /var/lib/gitea/log

Создайте администратора в секции Administrator Account. Этот аккаунт сможет настраивать систему, подключать внешние сервисы и управлять пользователями.

После установки вы попадёте на панель управления Gitea.

Шаг 7 — Настройка почты для уведомлений

Gitea может отправлять уведомления через SMTP. Отредактируйте конфигурационный файл app.ini (обычно /etc/gitea/app.ini). Если файл ещё не создан, Gitea создаст его после первого запуска; можно редактировать копию в /etc/gitea/app.ini.

sudo vim /etc/gitea/app.ini

Пример блока [mailer]:

[mailer]
ENABLED = true
FROM = [email protected]
MAILER_TYPE = smtp
HOST = mail.example.com:587
IS_TLS_ENABLED = true
USER = [email protected]
PASSWD = password

Сохраните файл и перезапустите Gitea:

sudo systemctl restart gitea

Совет: используйте сервисные аккаунты и отдельные SMTP-пароли, применяйте шифрование.

Шаг 8 — Резервное копирование и миграция

Рекомендую регулярно бэкапить:

• Данные репозиториев: /var/lib/gitea/data/repositories
• Данные LFS: /var/lib/gitea/data/lfs
• Конфигурацию: /etc/gitea/app.ini
• Базу данных PostgreSQL: pg_dump

Пример бэкапа БД:

sudo -u postgres pg_dump giteadb > /var/backups/giteadb-$(date +%F).sql

Для восстановления репозиториев просто восстановите файлы и убедитесь, что права принадлежат git:git.

Шаг 9 — Обновление Gitea (быстро и без сложных миграций)

Чтобы обновить Gitea, достаточно заменить бинарник:

sudo systemctl stop gitea
cd /tmp
GITEAVERSION=1.15.8
wget -O gitea https://dl.gitea.io/gitea/${GITEAVERSION}/gitea-${GITEAVERSION}-linux-amd64
sudo mv gitea /usr/local/bin
sudo chmod +x /usr/local/bin/gitea
sudo systemctl start gitea

Порядок важен: остановите сервис, замените бинарник, запустите. Проверьте логи и работоспособность.

Рекомендуемые практики безопасности

• Запускайте Gitea за обратным прокси (nginx) с TLS (Let’s Encrypt).
• Не открывайте PostgreSQL в Интернет; используйте private network или туннель.
• Включите двухфакторную аутентификацию для администраторов.
• Ограничьте доступ SSH к серверу (Fail2ban, ключи, отключите парольную аутентификацию).
• Регулярно обновляйте Gitea и ОС.

Пример использования nginx как обратного прокси — краткая схема:

• nginx принимает HTTPS и проксирует запросы на http://127.0.0.1:3000
• nginx обслуживает статические файлы и перенаправляет /ssh/* на SSH-порт при необходимости

Примеры файла app.ini (минимум для запуска)

Ниже — сокращённый пример секции database и server для /etc/gitea/app.ini:

[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = giteadb
USER = gitea
SSL_MODE = disable
PASSWORD = secure@123

[server]
PROTOCOL = http
HTTP_ADDR = 0.0.0.0
HTTP_PORT = 3000
ROOT_URL = http://YOUR_IP_ADDRESS:3000/
DISABLE_SSH = false
SSH_PORT = 22
RUN_USER = git

Замените параметры на реальные значения.

Отладка и распространённые проблемы

• Gitea не стартует: проверьте systemd-журналы:

sudo journalctl -u gitea -b --no-pager

• Порт 3000 уже занят: проверьте ss -tulpen | grep 3000 и измените HTTP_PORT.
• Ошибка подключения к БД: проверьте user/password, host, pg_hba.conf и что PostgreSQL слушает нужный адрес.
• Права на файловую систему: убедитесь, что /var/lib/gitea принадлежит git:git и имеет правильные права.

Критерии приёмки

• Сервис systemd стартует без ошибок и возвращает active (running).
• Веб-интерфейс доступен по указанному адресу и порт 3000.
• Администратор может создать репозиторий и выполнить push/pull по HTTP и SSH.
• Уведомления по почте отправляются (если настроены).
• Резервная копия базы и репозиториев создаётся успешно.

Тесты и критерии проверки

1. Проверка веб-UI:

• Открыть http://YOUR_IP_ADDRESS:3000 — логин страница загружается.

2. Создание репозитория:

• Создать новый репозиторий через UI — проверить, что директория появилась в /var/lib/gitea/data/repositories.

3. Git push/pull по HTTP:

• Клонировать репозиторий и выполнить коммиты, пушим — проверяем лог.

4. SSH-клонирование:

• Добавить SSH-ключ в профиль, клонировать по ssh://git@YOUR_IP:22/ — проверить.

Роль‑базированные чек‑листы

Администратор:

• Убедиться в наличии TLS на фронтенде.
• Настроить интеграции (LDAP/LDAPs, OAuth) по необходимости.
• Создать политики прав доступа.

DevOps:

• Настроить мониторинг (процесс, порт, SLI зависимости).
• Настроить ротацию логов и бэкапы.
• Автоматизировать обновление бинарника через CI/CD.

Разработчик:

• Проверить набор git-hooks при клонировании.
• Использовать LFS для больших бинарных файлов.

Когда этот способ не подходит

• Нужна корпоративная поддержка и расширенные CI/CD-опции — рассмотрите GitLab или GitHub Enterprise.
• Если важна встроенная высокодоступная кластеризация БД без настройки — используйте управляемые сервисы БД.

Альтернативные подходы

• Установка из пакета (если доступен репозиторий) — удобнее для автоматической интеграции с системными обновлениями.
• Развёртывание в контейнере (Docker, Kubernetes) — предпочтительнее для платформ с контейнерной оркестрацией.
• Использование SQLite для очень маленьких инстансов (низкая нагрузка).

Модель зрелости развёртывания (high-level)

• Proof of Concept: один сервер, SQLite, локальные пользователи.
• Production начальный: PostgreSQL, бэкапы, TLS, один фронтенд.
• Production зрелый: мониторинг, резервирование БД, HA-прокси, регулярные оффсайт бэкапы.

План отката при неудачном обновлении

1. Остановить новый сервис: sudo systemctl stop gitea
2. Вернуть предыдущую версию бинарника из бэкапа (/usr/local/bin/gitea.old)
3. Запустить сервис: sudo systemctl start gitea
4. Проверить логи и функциональность, восстановить БД, если нужно.

Краткий чеклист миграции на новый сервер

• Экспортировать БД: pg_dump
• Копировать /var/lib/gitea и /etc/gitea
• Восстановить права: chown -R git:git
• Импортировать БД на новом сервере и проверить app.ini

Полезные команды и сниппеты (cheat sheet)

• Просмотр логов Gitea:

  sudo journalctl -u gitea -f

• Резервная копия БД:

  sudo -u postgres pg_dump giteadb > /var/backups/giteadb-$(date +%F).sql

• Проверка доступности порта:

  ss -tulpen | grep 3000

Заключение

Поздравляю — вы установили и настроили Gitea на Debian 11 с PostgreSQL. Теперь у вас лёгкий, управляемый Git-сервер, готовый для командной работы. Настройте TLS, автоматические бэкапы и мониторинг, чтобы держать систему надёжной.

Если возникнут вопросы по адаптации инструкции под вашу архитектуру (Docker, Kubernetes, NFS для репозиториев, интеграция LDAP), задайте конкретные параметры — помогу подобрать оптимальный вариант.

Краткие выводы

• Gitea — лёгкая и гибкая альтернатива крупным Git-серверам.
• Установка из бинарника проста: заменить исполняемый файл и перезапустить.
• PostgreSQL с SCRAM-SHA-256 обеспечивает защищённую аутентификацию.
• Обязательно автоматизируйте бэкапы и следите за обновлениями.