Установка Gitea на Debian 10 за Nginx с HTTPS

Gitea — это веб-приложение для хостинга исходного кода, написанное на Go и форкнутое от Gogs. Оно предназначено для работы с Git и по функционалу сходно с GitLab и GitHub. В этом руководстве показано, как установить Gitea на Debian 10 и разместить его за HTTPS‑реверс‑прокси Nginx.

Краткие требования

• Сервер с Debian 10 и root‑правами.
• Зарегистрированный домен, указывающий на ваш сервер (A/AAAA записи).
• Установленная переменная окружения $EDITOR.
• Доступ к SMTP‑серверу для уведомлений по e‑mail (опционально).

Важно: убедитесь, что A‑запись указывает на IPv4 сервера. При наличии IPv6 добавьте AAAA‑запись.

Шаг 1: Подготовка системы

Обновите индекс пакетов и установите обновления:

apt update
apt upgrade -y
reboot

Установите необходимые компоненты: Git, PostgreSQL, Nginx, Certbot и sudo:

apt install -y git nginx certbot postgresql sudo

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

adduser --system --disabled-password --group --shell /bin/bash --home /home/gitea gitea

Создайте структуру каталогов:

mkdir -p /var/lib/gitea/{data,log} /etc/gitea /run/gitea

Установите владельцев и права:

chown -R gitea:gitea /var/lib/gitea
chown -R gitea:gitea /run/gitea
chown -R root:gitea /etc/gitea
chmod -R 750 /var/lib/gitea
chmod 770 /etc/gitea

Примечание: права на /etc/gitea временно ослаблены — мы их ужесточим после веб‑инсталляции.

Шаг 2: Настройка базы данных

Включите и запустите PostgreSQL:

systemctl enable --now [email protected]

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

sudo -u postgres psql
postgres=# CREATE ROLE gitea LOGIN ENCRYPTED PASSWORD 'your_password';
postgres=# CREATE DATABASE gitea;
postgres=# GRANT ALL PRIVILEGES ON DATABASE gitea TO gitea;
postgres=# exit;

Совет: используйте менеджер секретов для хранения паролей (Vault, pass, gpg‑encrypted file).

Шаг 3: Установка Gitea

Скачайте бинарник linux‑amd64 и поместите его в /usr/local/bin:

wget https://dl.gitea.io/gitea/master/gitea-master-linux-amd64 -O /usr/local/bin/gitea
chmod 755 /usr/local/bin/gitea

Создайте systemd‑юнит для Gitea:

$EDITOR /etc/systemd/system/gitea.service

Вставьте содержимое юнита:

[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
Requires=postgresql.service
[Service]
Type=simple
User=gitea
Group=gitea
WorkingDirectory=/var/lib/gitea/
RuntimeDirectory=gitea
ExecStart=/usr/local/bin/gitea web -c /etc/gitea/app.ini
Restart=always
Environment=USER=gitea HOME=/home/gitea GITEA_WORK_DIR=/var/lib/gitea
[Install]
WantedBy=multi-user.target

Перезагрузите конфигурацию systemd и включите автозапуск:

systemctl daemon-reload
systemctl enable gitea.service

Шаг 4: Первичная конфигурация Gitea через веб‑установщик

Запустите службу Gitea и откройте веб‑инсталлятор:

systemctl start gitea.service

Перейдите в браузере по адресу http://your_domain:3000/install и заполните поля:

• Database Type: PostgreSQL
• Host: 127.0.0.1:5432
• Username: gitea
• Password: пароль, созданный ранее
• Database Name: gitea
• SSL: Disable
• Site Title: по вашему выбору
• Repository Root Path: /var/lib/gitea/data/repositories
• Git LFS Root Path: /var/lib/gitea/data/lfs
• Run As Username: gitea
• SSH Server Domain: your_domain
• SSH Server Port: 22
• Gitea HTTP Listen Port: 3000
• Gitea Base URL: https://your_domain/
• Log Path: /var/lib/gitea/log

Заполните настройки почты и остальные параметры по необходимости. Нажмите «Install Gitea». После установки вас может перенаправить на некорректный URL — это нормально до настройки Nginx и HTTPS.

Для повышения производительности и безопасности переключим Gitea на unix‑сокет. Остановите службу:

systemctl stop gitea.service

Ужесточьте права на /etc/gitea и файл app.ini:

chmod 750 /etc/gitea
chown root:gitea /etc/gitea/app.ini
chmod 640 /etc/gitea/app.ini

Откройте конфиг для редактирования:

$EDITOR /etc/gitea/app.ini

В секции [server] удалите строку:

HTTP_PORT = 3000

И добавьте следующие строки:

HTTP_ADDR        = /run/gitea/gitea.sock
PROTOCOL         = unix
UNIX_SOCKET_PERMISSION = 666

Примечание: /run и /var/run обычно ссылаются друг на друга; проверьте путь сокета, если Nginx не находит файл.

Шаг 5: Настройка обратного прокси Nginx и сертификата

Остановите Nginx, чтобы certbot мог прослушивать порт 80:

systemctl stop nginx.service

Получите сертификат Let’s Encrypt в режиме standalone (подставьте e‑mail и домен):

certbot certonly --standalone --agree-tos -m [email protected] -d your_domain

Сертификаты будут в /etc/letsencrypt/live/your_domain/.

Создайте конфигурацию для Nginx:

$EDITOR /etc/nginx/sites-available/gitea

Вставьте:

server {
        listen 80;
        listen [::]:80;
        server_name your_domain;
        return 301 https://$server_name$request_uri;
    access_log /var/log/nginx/gitea-proxy_access.log;
    error_log /var/log/nginx/gitea-proxy_error.log;
}
server {
        listen 443 ssl;
        listen [::]:443 ssl;
        server_name your_domain;
        ssl on;
        ssl_certificate /etc/letsencrypt/live/your_domain/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/your_domain/privkey.pem;
        location / {
                proxy_pass http://unix:/var/run/gitea/gitea.sock;
    }
    access_log /var/log/nginx/gitea-proxy_access.log;
    error_log /var/log/nginx/gitea-proxy_error.log;
}

Включите сайт и проверьте конфигурацию:

ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled
nginx -t

Запустите Nginx и Gitea:

systemctl start nginx.service gitea.service

Если вы не создали администратора в веб‑инсталляторе, первым зарегистрировавшимся пользователем станет администратор.

Дополнительно: настройка логирования

По умолчанию Gitea логирует с уровнем info и выше. Чтобы изменить уровень, откройте /etc/gitea/app.ini и отредактируйте секцию [log]:

[log]
MODE = file
LEVEL = warn
ROOT_PATH = /var/lib/gitea/log

Перезапустите службу:

systemctl restart gitea.service

Дополнительно: встроенный SSH‑сервер Gitea

Чтобы Gitea использовала собственный SSH‑сервер, добавьте в секцию [server]:

START_SSH_SERVER = true
SSH_PORT = 2222

Перезапустите Gitea.

Блок фактов (ключевые значения и пути)

• Порт по умолчанию для HTTP‑инсталлятора: 3000
• Путь репозиториев: /var/lib/gitea/data/repositories
• Путь логов: /var/lib/gitea/log
• Пользователь службы: gitea
• Socket (пример): /run/gitea/gitea.sock (или /var/run/gitea/gitea.sock)
• Сервис systemd: gitea.service

Рекомендации по безопасности

• Перемещайте чувствительные файлы в каталог с правами, ограниченными для группы gitea и root.
• Не храните пароли в открытом виде в скриптах. Используйте менеджеры секретов.
• Ограничьте доступ к административной панели по IP, если у вас закрытая сеть.
• Включите автопроверку обновлений Gitea и тестируйте обновления в staging перед продом.
• Резервируйте /var/lib/gitea/data и конфиг /etc/gitea/app.ini регулярно.
• Настройте Fail2Ban или другой механизм блокировки брутфорса для SSH и веб‑форм.

Playbook: бэкап и восстановление (микро‑SOP)

1. Остановите сервисы: systemctl stop gitea.service
2. Бэкап базы данных:

sudo -u postgres pg_dump -Fc gitea > /root/gitea-db-$(date +%F).dump

3. Бэкап файлов:

tar czf /root/gitea-files-$(date +%F).tgz /var/lib/gitea /etc/gitea

4. Проверьте целостность бэкапов и перенесите их на удалённое хранилище.
5. Для восстановления: распакуйте архивы, восстановите дамп psql и проверьте права владельцев.

Критерии приёмки: после восстановления веб‑интерфейс доступен, репозитории видны, вход в систему работает.

Резервные сценарии и альтернативы

• Docker / docker‑compose: если вы предпочитаете контейнеризацию, используйте официальный образ gitea/gitea и отдельный образ для Postgres. Это облегчает обновления и изоляцию.
• Пакеты дистрибутива: некоторые дистрибутивы предлагают пакет gitea, но он может отставать от upstream по версии.
• Облачные решения: если не хотите управлять инфрастуктурой, рассмотрите SaaS‑хостинг репозиториев.

Когда этот метод не подходит:

• На ограниченных хостингах без возможности получать реальный IP/нет доступа к портам 80/443.
• Если требуется кластеризация Gitea: нужен другой подход и внешнее хранилище для репозиториев.

План обновления (микро‑методология)

1. Протестируйте новую версию на staging‑инстансе с теми же конфигами и данными (или с копией).
2. Сделайте бэкап базы и файлов.
3. Отключите доступ к продакшену (maintenance mode) или используйте read‑only окна.
4. Обновите бинарник: скачайте новую версию и замените /usr/local/bin/gitea.
5. Перезапустите сервис и проверьте логи.
6. Если проблемы — откат по бэкапу.

Чеклист ролей (кто за что отвечает)

• Администратор:
  • Обновления Gitea и ОС
  • Управление сертификатами
  • Резервное копирование
• Девопс / Оператор:
  • Настройка Nginx, systemd и мониторинга
  • Восстановление после сбоев
• Разработчик / пользователь:
  • Управление репозиториями и ключами SSH
  • Создание тикетов и настройка webhook’ов

Тесты и критерии приёмки

• Доступность: https://your_domain/ открывается корректно.
• SSH: git clone ssh://your_domain/yourrepo.git работает.
• HTTP‑операции: создание/клон/пуш через HTTPS проходят.
• Логи: уровень логирования соответствует настройке и не переполняет диск.

Частые проблемы и способы решения

• Проблема: certbot не может получить порт 80.

  • Решение: остановите все сервисы, слушающие 80 (systemctl stop nginx), запустите certbot, затем перезапустите Nginx.

• Проблема: Nginx возвращает 502 Bad Gateway.

  • Проверьте, что сокет существует: ls -l /run/gitea/gitea.sock или /var/run/gitea/gitea.sock.
  • Проверьте права на сокет. systemd RuntimeDirectory создает каталог с uid/gid gitea.
  • Убедитесь, что Gitea запущена и слушает unix‑сокет.

• Проблема: веб‑инсталлятор редиректит на ошибочный URL.

  • Это ожидаемо до настройки Nginx/HTTPS. Проверьте параметр Gitea Base URL в /etc/gitea/app.ini.

Советы по совместимости и миграции с Gogs

• Gitea совместим с репозиториями Gogs, но перед миграцией протестируйте перенос пользователей и вебхуков.
• Снимите бэкап Gogs и восстановите в тестовом окружении Gitea. Проверьте метаданные репозиториев.

Краткое резюме

• Установите зависимости, создайте пользователя и каталоги.
• Настройте PostgreSQL и создайте базу/роль.
• Скачайте бинарник Gitea, создайте systemd‑юнит и запустите сервис.
• Используйте веб‑инсталлятор, затем переключитесь на unix‑сокет.
• Получите SSL через certbot и настройте Nginx как обратный прокси.
• Настройте безопасность, бэкапы и процедуру обновлений.

Важно: проверяйте логи (/var/log/nginx/, /var/lib/gitea/log) при возникновении ошибок.

Короткая памятка: регулярно бэкапьте базу и репозитории, обновляйте Gitea сначала в тестовой среде, и используйте HTTPS и ограниченные права доступа для конфигурационных файлов.