Перейти к содержимому

Статья 128 из 141

Гайды

Gitea на VPS: свой Git-сервер в Docker с PostgreSQL, SSH и бэкапом

Gitea — лёгкий Git-сервер с веб-интерфейсом в духе GitHub: репозитории, задачи, запросы на слияние, вики, пакеты. Он подойдёт, если вы хотите держать код у себя: личные проекты, код команды, зеркала чужих репозиториев. Интерфейс переведён на русский.

У Gitea есть форк Forgejo. Его развивает некоммерческая организация Codeberg e.V., на нём работает сервис Codeberg. Установка Forgejo в Docker устроена похоже, но образ и документация у него свои.

Ресурс Минимум Комфортно
vCPU 1 2
RAM 1 ГБ 2 ГБ
Диск 10 ГБ по объёму репозиториев

Сразу после установки Gitea с PostgreSQL заняли около 160 МБ памяти. Ещё нужны:

  • поддомен, например git.example.com, с A-записью на IP сервера (DNS);
  • Docker и Docker Compose;
  • Nginx и certbot для HTTPS.

Файл ниже основан на примере из официальной документации Gitea. Веб-интерфейс слушает только 127.0.0.1:3000, наружу он выйдет через Nginx. Порт 2222 открыт для git по SSH.

Окно терминала
mkdir -p /opt/gitea && cd /opt/gitea
nano docker-compose.yml
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:latest
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
- GITEA__database__DB_TYPE=postgres
- GITEA__database__HOST=db:5432
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=ДЛИННЫЙ_ПАРОЛЬ_БД
- GITEA__server__SSH_DOMAIN=git.example.com
- GITEA__server__SSH_PORT=2222
- GITEA__service__DISABLE_REGISTRATION=true
restart: always
networks:
- gitea
volumes:
- ./gitea:/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: docker.io/library/postgres:18
restart: always
environment:
- POSTGRES_USER=gitea
- POSTGRES_PASSWORD=ДЛИННЫЙ_ПАРОЛЬ_БД
- POSTGRES_DB=gitea
networks:
- gitea
volumes:
- ./postgres:/var/lib/postgresql

Пароль базы задайте одинаковым в двух местах. Сгенерировать его можно командой openssl rand -hex 16.

Любой параметр из app.ini задаётся переменной вида GITEA__секция__КЛЮЧ. Значения применяются при каждом старте контейнера:

Переменная Что делает
GITEA__server__SSH_DOMAIN домен в SSH-ссылках для клонирования
GITEA__server__SSH_PORT порт в SSH-ссылках, совпадает с левой частью 2222:22
GITEA__service__DISABLE_REGISTRATION true закрывает самостоятельную регистрацию

Без SSH_DOMAIN в ссылках для клонирования будет localhost. Без DISABLE_REGISTRATION зарегистрироваться сможет любой посетитель: в мастере установки этот флажок по умолчанию снят.

Запуск:

Окно терминала
docker compose up -d
docker compose logs -f server

В логе должна появиться строка Prepare to run install page. Выйти из лога: Ctrl+C.

Для одного пользователя хватит SQLite. Уберите сервис db, блок depends_on и все переменные GITEA__database__*. В мастере установки выберите тип базы SQLite3, файл будет лежать в /data/gitea/gitea.db. Для команды с CI и десятками репозиториев лучше PostgreSQL.

Конфиг /etc/nginx/sites-available/gitea:

server {
listen 80;
server_name git.example.com;
client_max_body_size 512M;
location / {
proxy_pass http://127.0.0.1:3000;
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;
}
}
Окно терминала
ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d git.example.com

client_max_body_size нужен для git push по HTTPS и загрузки больших файлов. Подробнее: Nginx, Let’s Encrypt.

Откройте порт для git по SSH в файрволе:

Окно терминала
ufw allow 2222/tcp

Откройте https://git.example.com. Gitea покажет страницу «Начальная конфигурация». Язык переключается внизу страницы, русский есть.

Страница начальной конфигурации Gitea: настройки базы данных PostgreSQL

  1. Раздел «Настройки базы данных» уже заполнен из переменных окружения. Ничего не меняйте.
  2. В «Основных настройках» проверьте «Gitea Website URL». Там должно быть https://git.example.com/. Gitea берёт адрес из запроса, поэтому сначала настройте HTTPS, а потом открывайте мастер.
  3. «Порт SSH сервера» оставьте как есть или укажите 2222: переменная SSH_PORT всё равно перезапишет значение при старте.
  4. Раскройте «Настройки учётной записи администратора» и создайте администратора: логин, email, пароль. Регистрация закрыта, поэтому без этого шага войти будет некем.
  5. Нажмите «Установить Gitea». Через несколько секунд откроется главная страница под вашим аккаунтом.

Настройки почты можно заполнить позже. Без SMTP Gitea работает, но не отправит письма для сброса пароля и уведомления.

  1. Добавьте свой публичный ключ: аватар справа вверху → «Настройки» → «SSH / GPG ключи» → «Добавить ключ». Как создать ключ: SSH-ключи.
  2. Нажмите «+» → «Новый репозиторий». Укажите название, при желании отметьте «Сделать репозиторий приватным».

Форма создания нового репозитория в Gitea

  1. После «Создать репозиторий» Gitea покажет команды для первого git push. Отправьте код с компьютера:
Окно терминала
git remote add origin ssh://git@git.example.com:2222/имя/my-project.git
git push -u origin main

Проверить ключ без репозитория:

Окно терминала
ssh -T -p 2222 git@git.example.com

Ответ при успехе:

Hi there, имя! You've successfully authenticated with the SSH key named ...
Gitea does not provide shell access.

Ссылка для клонирования есть на странице репозитория, кнопка «Код» → вкладка SSH.

Репозиторий в Gitea с SSH-ссылкой для клонирования на порту 2222

В репозитории есть вкладка «Действия». Это Gitea Actions, CI в формате GitHub Actions. Чтобы задачи запускались, нужен отдельный раннер act_runner, его настройка выходит за рамки статьи.

gitea dump собирает в один zip репозитории, дамп базы, app.ini и данные. Запускайте от пользователя git:

Окно терминала
docker exec -u git -w /tmp gitea bash -c '/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini'

В конце лога будет путь к архиву:

Finish dumping in file /tmp/gitea-dump-1795014544.zip

Скопируйте архив из контейнера и удалите его внутри:

Окно терминала
docker cp gitea:/tmp/gitea-dump-1795014544.zip /root/
docker exec gitea rm /tmp/gitea-dump-1795014544.zip

Восстановление описано в официальной документации (раздел Backup and Restore): архив распаковывают в контейнере, раскладывают data и repos по местам и выполняют gitea admin regenerate hooks. Храните копии вне сервера: бэкапы.

Окно терминала
cd /opt/gitea
docker exec -u git -w /tmp gitea bash -c '/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini'
docker compose pull
docker compose up -d

Перед обновлением сделайте dump. Миграции базы Gitea выполняет сама при старте. На ноябрь 2026 актуальна версия 28.4. Если хотите обновляться осознанно, укажите в image конкретную версию, например docker.gitea.com/gitea:28.4.0, и меняйте её вручную.

Образ PostgreSQL обновляйте только в пределах мажорной версии. Переход с 18 на 19 требует pg_upgrade или дампа и восстановления: PostgreSQL.

Симптом Причина и решение
В ссылках клонирования localhost или порт 22 Не заданы GITEA__server__SSH_DOMAIN и GITEA__server__SSH_PORT. Добавьте их и выполните docker compose up -d
Connection refused при git push по SSH Порт 2222 закрыт в файрволе или в ports указан 127.0.0.1:2222:22. Проверьте: проверка портов
Permission denied (publickey) Ключ не добавлен в профиль Gitea или клиент берёт другой ключ. Проверьте ssh -T -p 2222 git@git.example.com
413 Request Entity Too Large при push по HTTPS Увеличьте client_max_body_size в Nginx
Ссылки ведут на http:// Мастер открывали до настройки HTTPS. Исправьте ROOT_URL в /opt/gitea/gitea/gitea/conf/app.ini или задайте GITEA__server__ROOT_URL
Регистрация открыта для всех Задайте GITEA__service__DISABLE_REGISTRATION=true и перезапустите контейнер