Установка и настройка Gitea с Docker на Ubuntu 22.04

О чём статья

• Что такое Gitea и для каких задач подходит
• Установка Docker и запуск контейнеров под непривилегированным пользователем
• docker-compose для Gitea + PostgreSQL
• Nginx как обратный прокси с SSL
• Начальная настройка Gitea через веб-интерфейс
• Резервное копирование, тесты, отладка и меры безопасности

Кому полезно

• Системным администраторам и DevOps-инженерам, которые хотят быстрый и лёгкий self-hosted Git-сервер
• Командам с ограниченным бюджетом, предпочитающим лёгкие альтернативы GitLab или GitHub Enterprise

Краткое определение терминов

• Gitea — лёгкий open-source Git-сервис для самохостинга.
• Docker — платформа для запуска контейнеров приложений.
• Reverse proxy — обратный прокси, перенаправляющий HTTP/HTTPS-запросы на внутренние сервисы.

Введение

Gitea — бесплатный и открытый Git-сервис для самохостинга (альтернатива GitHub/GitLab/Bitbucket). Это форк проекта Gogs, написанный на Go и распространяемый по лицензии MIT. Gitea поддерживает отслеживание ошибок, вики, обзоры кода и интеграции через вебхуки. Приложение кроссплатформенное и может работать на Linux, macOS, Windows и ARM.

Цель инструкции — показать максимально простой и надёжный путь запуска Gitea в Docker на Ubuntu 22.04 с использованием Nginx в роли обратного прокси и LetsEncrypt для TLS.

Требования

• Сервер с Ubuntu 22.04
• Пользователь с правами sudo (или root)
• Доменное имя, указывающее на сервер (если планируется HTTPS)
• Открытые порты 80 и 443 для получения сертификатов Let’s Encrypt

Установка и настройка Docker

Перед установкой Docker установите зависимости:

sudo apt install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

Добавьте ключ GPG Docker и репозиторий. Ключ разместится в /etc/apt/keyrings:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Добавьте репозиторий Docker:

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

Обновите индексы пакетов и установите Docker Engine и плагин docker-compose:

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

Подтвердите установку и запустите тестовый контейнер:

sudo docker run hello-world

Если вы видите сообщение “Hello from Docker!”, установка завершена успешно.

Настройка пользователя для запуска контейнеров

Рекомендуется запускать сервисы под непривилегированным пользователем, добавленным в группу docker.

sudo useradd -m -s /bin/bash gitea
sudo usermod -aG docker gitea
su - gitea

Проверьте запуск контейнера без sudo (от имени gitea):

docker run hello-world

Если вывод успешен, можно выполнять дальнейшие шаги под пользователем gitea.

Создание проекта и docker-compose

Переключившись на пользователя gitea, создайте рабочую директорию и файл docker-compose.yml:

mkdir -p myapp; cd myapp/
nano docker-compose.yml

Вставьте следующий файл docker-compose (сохраните как docker-compose.yml):

version: "2"

volumes:
  gitea-data:
    driver: local
  gitea-config:
    driver: local

services:
  server:
    image: gitea/gitea:1.16.8-rootless
    environment:
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea
    restart: always
    volumes:
      - ./data:/var/lib/gitea
      - gitea-data:/var/lib/gitea
      - ./config:/etc/gitea
      - gitea-config:/etc/gitea
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:2222"
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data

Сохраните изменения и запустите стек:

docker compose up -d

Во время первого запуска Docker скачает образы Gitea и PostgreSQL. После завершения проверьте состояние контейнеров:

docker compose ps

Чтобы просмотреть логи для диагностики:

docker compose logs
# или отдельно
docker compose logs db
docker compose logs server

Ключевые моменты конфигурации в docker-compose.yml:

• Volumes gitea-data и gitea-config сохраняют данные и настройки контейнера
• Порты: 3000 (веб-интерфейс), 2222 (SSH для Git)
• База данных — PostgreSQL (контейнер db), с данными в ./postgres

Настройка Nginx как обратного прокси с SSL

Пример ниже показывает минимальную конфигурацию Nginx для проксирования HTTPS-запросов к Gitea, используя сертификаты Let’s Encrypt, размещённые в /etc/letsencrypt/live/<ваш-домен>.

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

sudo apt install nginx

Добавьте SSL-snippet:

sudo nano /etc/nginx/snippets/ssl.conf

Вставьте конфигурацию SSL (замените пути к сертификатам на свои):

ssl_certificate /etc/letsencrypt/live/git.howtoforge.local/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/git.howtoforge.local/privkey.pem;

# from https://cipherli.st/
# and https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_ecdh_curve secp384r1;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
add_header Strict-Transport-Security "max-age=63072000; includeSubdomains";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;

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

sudo nano /etc/nginx/sites-available/gitea.conf

Вставьте серверный блок (измените server_name на ваш домен):

server {
    server_name git.howtoforge.local;
    listen 443 ssl http2;
    include snippets/ssl.conf;

    access_log /var/log/nginx/gitea.access.log;
    error_log /var/log/nginx/gitea.error.log;

    location / {
        proxy_pass http://localhost: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;
    }
}

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

sudo ln -s /etc/nginx/sites-available/gitea.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

При корректной настройке Nginx сайт будет доступен по https://git.howtoforge.local.

Важно: если используете Docker на одной машине, proxy_pass к localhost будет работать, поскольку Nginx запущен вне контейнера. Если nginx в контейнере — используйте адрес контейнера server (docker network).

Начальная настройка Gitea через веб-интерфейс

Откройте браузер и перейдите по адресу вашего домена (например https://git.howtoforge.local). На странице первоначальной настройки проверьте параметры базы данных — они должны совпадать с docker-compose.yml.

В разделе Server Domain и Gitea Base URL укажите ваш домен (например https://git.howtoforge.local). Раскройте блок Administrator Account Settings и создайте административного пользователя.

После завершения установки вы попадёте на дашборд Gitea, войдя под созданным админом.

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

• Веб-интерфейс Gitea доступен по HTTPS и возвращает код 200
• Вход под созданным администратором возможен
• SSH-доступ к Gitea через порт 2222 (при необходимости) устанавливается через git clone по SSH
• Контейнеры server и db находятся в состоянии Up

Резервное копирование и восстановление

Резервные копии — критичны для самохостинга. Подходы:

• Файловая копия томов Docker (gitea-data/gitea-config/postgres)
• Экспорт SQL-дампа PostgreSQL (pg_dump)

Пример резервного копирования PostgreSQL:

# внутри контейнера db или с хоста, если psql доступен
docker exec -t  pg_dump -U gitea gitea > gitea_backup_$(date +%F).sql

Резервное копирование томов Gitea (простой способ):

# остановите стек для консистентной копии
docker compose down
# архивируем каталоги данных
tar czf gitea_data_$(date +%F).tar.gz ./data ./postgres ./config

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

• Распакуйте архив в рабочую директорию
• Запустите docker compose up -d
• При необходимости выполните импорт SQL: psql -U gitea -d gitea < gitea_backup.sql

Тесты и приёмочные проверки

• Проверить, что http(s) GET / возвращает 200 и заголовок Server: Gitea
• Создать репозиторий через веб-интерфейс, сделать push/pull из локального git
• Проверить SSH-доступ: git clone ssh://git@yourhost:2222//.git
• Проверить автообновление страниц wiki и issue

Отладка типичных ошибок

• Если контейнер db не запускается — проверьте права директории ./postgres и логи: docker compose logs db
• Ошибка подключения к БД в Gitea — проверьте правильность GITEAdatabaseHOST и учетных данных
• Проблемы с HTTPS — проверьте наличие сертификатов в /etc/letsencrypt/live и права доступа

Меры безопасности

• Запускайте Gitea под непривилегированным пользователем и используйте rootless-образ
• Обновляйте образы Docker и патчи безопасности регулярно
• Ограничьте доступ к административной панели через firewall/ACL
• Настройте бэкапы и проверяйте восстановление
• Используйте SSH-ключи и отключите установку паролей для git-пушей, если возможно
• Включите 2FA для админов и чувствительных аккаунтов

Рекомендации по firewall (ufw):

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

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

• Использовать MySQL вместо PostgreSQL — потребуется изменить настройки в docker-compose и конфигурации Gitea
• Разворачивать Gitea без Docker, через системный пакет или бинарник — полезно при ограничениях по Docker
• Использовать Traefik вместо Nginx для автоматического получения сертификатов и динамической маршрутизации

Модель принятия решения при выборе архитектуры

• Малые команды и простые проекты: Gitea + Docker на одном хосте + PostgreSQL в контейнере
• Корпоративные сценарии: Gitea в Kubernetes с внешним хранилищем и управляемой базой данных

flowchart TD
  A[Нужен self-hosted Git?] --> B{Да}
  B --> C{Требуется много функций CI/CD?}
  C -->|Да| D[Рассмотрите GitLab или Gitea + внешние CI]
  C -->|Нет| E[Используйте Gitea в Docker]
  B -->|Нет| F[Оставаться на GitHub/GitLab SaaS]

Чек-листы по ролям

Admin:

• Настроить домен и получить TLS
• Создать администратора Gitea
• Настроить бэкапы и тест восстановления
• Настроить журналирование и ротацию логов

DevOps:

• Развернуть Docker и docker-compose
• Настроить Nginx/Traefik
• Настроить мониторинг и алерты
• Обновление образов и план патчей

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

• Создать SSH-ключ и добавить в профиль
• Клонировать репозиторий и выполнить push
• Проверить CI / webhooks

SOP для обновления Gitea

1. Оповестить команду и поставить окно обслуживания
2. Снять бэкап БД и каталогов Gitea
3. docker compose pull
4. docker compose up -d
5. Проверить работоспособность сервисов и выполнить smoke-тесты
6. Откат при проблемах согласно процедуре восстановления

Примеры команд для регулярного обслуживания

• Просмотр логов сервисов:

docker compose logs -f server

• Обновление образов и перезапуск:

docker compose pull
docker compose up -d

Совместимость и миграции

• Версии образов Gitea: проверяйте совместимость данных перед обновлением мажорных версий
• При миграции с другой платформы (GitLab/GitHub) используйте экспорт/импорт через стандартные инструменты и миграционные скрипты

Часто встречающие вопросы

Q: Можно ли использовать SQLite для Gitea? A: Да, для небольших тестовых инсталляций допустимо, но для продакшна рекомендуется PostgreSQL или MySQL.

Q: Что делать, если порт 3000 занят? A: Измените перенаправление портов в docker-compose или настройте proxy_pass к другому адресу.

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

• Gitea — лёгкий и быстрый вариант для самохостинга Git
• Docker + docker-compose упрощают развёртывание и обновление
• Nginx с SSL обеспечивает безопасный доступ по HTTPS
• Резервное копирование и регулярное обслуживание — обязательны

Полезные команды кратко

• docker compose up -d — поднять стек
• docker compose ps — проверить состояние
• docker compose logs -f server — смотреть логи Gitea
• sudo nginx -t — проверить конфигурацию Nginx

Контрольный список перед сдачей в продуктив

• TLS активно и валиден
• Бэкапы настроены и проверены
• Мониторинг и логирование работают
• Доступ пользователей протестирован

Факто-бокс

• Платформа: Ubuntu 22.04
• Контейнеризация: Docker + docker-compose
• СУБД: PostgreSQL (в примере postgres:14)
• Порты: 3000 (HTTP), 2222 (SSH)

Короткое объявление для команды (100–200 слов)

Gitea готов к использованию: мы развернули самохостинг Git-сервера на Ubuntu 22.04 с использованием Docker и PostgreSQL. Доступен веб-интерфейс по HTTPS и SSH-доступ для git. Администратор создан, бэкапы настроены. Пожалуйста, проверьте свои SSH-ключи и выполните первый пуш в тестовый репозиторий. Обновления и обслуживание будут выполняться по заранее согласованному графику.

1-строчный глоссарий

• Gitea — лёгкий self-hosted Git-сервис; Docker — технология контейнеризации; Reverse proxy — сервер, перенаправляющий внешние запросы на внутренние сервисы.

Если нужна помощь с конкретной проблемой (логи контейнеров, ошибки при миграции, настройке HTTPS или бэкапе) — пришлите вывод docker compose ps и соответствующие логи, и я помогу диагностировать.