Встановлення Gitea на VPS

# Оновлення списку пакетів та їх оновлення до останніх версій
sudo apt update && sudo apt upgrade -y

# Створення нового користувача (замініть 'ваш_пользователь' на бажане ім'я)
sudo adduser ваш_пользователь

# Додавання користувача до групи sudo для отримання адміністративних прав
sudo usermod -aG sudo ваш_пользователь

exit
# Потім увійдіть знову з вашим_пользователем
ssh ваш_пользователь@ваш_ip_сервера

# На вашій локальній машині
ssh-keygen -t ed25519 -C "ваш[email protected]"

# На вашій локальній машині
ssh-copy-id ваш_пользователь@ваш_ip_сервера

# На сервері
sudo nano /etc/ssh/sshd_config

# /etc/ssh/sshd_config
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no
PermitRootLogin no

sudo systemctl restart sshd

# Встановлення Fail2Ban
sudo apt install fail2ban -y

# Копіювання стандартного конфігу для його налаштування
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

# Відкриття файлу для редагування (опціонально, для більш тонкого налаштування)
sudo nano /etc/fail2ban/jail.local

# Приклад вмісту jail.local (переконайтеся, що enabled = true)
[DEFAULT]
bantime  = 1d
findtime = 10m
maxretry = 5

[sshd]
enabled = true
mode   = aggressive
port    = ssh
logpath = %(sshd_log)s
backend = %(sshd_backend)s

# Перезапуск Fail2Ban для застосування змін
sudo systemctl restart fail2ban
sudo systemctl enable fail2ban

# Встановлення UFW
sudo apt install ufw -y

# Дозволити SSH (за замовчуванням порт 22)
sudo ufw allow ssh

# Дозволити HTTP (порт 80) та HTTPS (порт 443) для веб-сервера (Caddy)
sudo ufw allow http
sudo ufw allow https

# Увімкнути UFW
sudo ufw enable

# Удаление старых версий Docker, если они есть
for pkg in docker.io docker-doc docker-compose docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin; do sudo apt remove $pkg; done

# Обновление списка пакетов
sudo apt update

# Установка необходимых пакетов для работы с репозиториями
sudo apt install ca-certificates curl gnupg -y

# Добавление официального GPG-ключа Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Добавление репозитория Docker в APT-источники
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Обновление списка пакетов после добавления репозитория Docker
sudo apt update

# Установка Docker Engine, Docker CLI, containerd и Docker Compose плагина
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Проверка версии Docker
docker --version

# Проверка статуса Docker-сервиса
sudo systemctl status docker

# Запуск тестового контейнера 'hello-world'
sudo docker run hello-world

# Добавление пользователя в группу docker
sudo usermod -aG docker ваш_пользователь

# Примените изменения группы (выйдите и войдите заново или перезагрузите систему)
newgrp docker

# Создание корневой директории для проекта Gitea
mkdir -p ~/gitea

# Переход в созданную директорию
cd ~/gitea

# Создание директории для хранения постоянных данных Gitea
mkdir -p ./data

# Создание файла docker-compose.yml
nano docker-compose.yml

# docker-compose.yml
version: "3.8"

services:
  gitea:
    image: gitea/gitea:1.22.0 # Актуальна версія на 2026 рік, перевірте https://dl.gitea.io/gitea/
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__DATABASE__DB_TYPE=sqlite3 # Використовуємо SQLite для простоти
      - GITEA__DATABASE__PATH=/data/gitea.db # Шлях до файлу бази даних SQLite
      - GITEA__SERVER__DOMAIN=your.domain.com # Ваш домен
      - GITEA__SERVER__SSH_DOMAIN=your.domain.com # Домен для SSH-доступу
      - GITEA__SERVER__HTTP_PORT=3000 # Внутрішній порт Gitea
      - GITEA__SERVER__APP_DATA_PATH=/data # Шлях для даних Gitea всередині контейнера
      - GITEA__SERVER__ROOT_URL=https://your.domain.com/ # Базовий URL для Gitea
      - GITEA__SECURITY__INSTALL_LOCK=true # Блокування сторінки встановлення після першого налаштування
      - GITEA__SERVICE__DISABLE_REGISTRATION=false # Дозволити реєстрацію нових користувачів (true для приватного сервера)
      - GITEA__SERVICE__REQUIRE_SIGNIN_VIEW=false # Вимагати вхід для перегляду репозиторіїв (true для приватного сервера)
      - GITEA__SESSION__PROVIDER=db # Використовуємо базу даних для сесій
      - GITEA__CACHE__ADAPTER=redis # Рекомендується для продуктивності
      - GITEA__CACHE__HOST=redis:6379 # Хост Redis
      - GITEA__QUEUE__TYPE=redis # Черга завдань через Redis
      - GITEA__QUEUE__CONN_STR=redis://redis:6379/0 # Рядок підключення до Redis
    restart: always
    volumes:
      - ./data:/data # Мапінг локальної директорії даних до контейнера
      - /etc/timezone:/etc/timezone:ro # Синхронізація часового поясу
      - /etc/localtime:/etc/localtime:ro # Синхронізація локального часу
    ports:
      - "3000:3000" # Внутрішній HTTP-порт Gitea (для Caddy)
      - "2222:22" # SSH-порт Gitea (мапімо на 2222, щоб не конфліктувати з хостом)
    networks:
      - gitea-network

  caddy:
    image: caddy:2.7.5 # Актуальна версія Caddy на 2026 рік
    container_name: caddy
    restart: always
    ports:
      - "80:80" # HTTP для Let's Encrypt challenge та перенаправлення
      - "443:443" # HTTPS
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile # Файл конфігурації Caddy
      - ./caddy_data:/data # Сховище Caddy для сертифікатів та стану
    environment:
      - GITEA_DOMAIN=your.domain.com # Передача домену в Caddyfile через змінну
    networks:
      - gitea-network
    depends_on:
      - gitea # Caddy залежить від Gitea

  redis:
    image: redis:7.2-alpine # Легковажна версія Redis
    container_name: redis
    restart: always
    volumes:
      - ./redis_data:/data # Сховище даних Redis
    networks:
      - gitea-network
    command: redis-server --appendonly yes # Увімкнення персистентності даних

networks:
  gitea-network:
    driver: bridge

# Создание файла Caddyfile
nano Caddyfile

# Caddyfile
{env.GITEA_DOMAIN} {
    # Автоматичний HTTPS
    tls {
        # Використовуємо Let's Encrypt
        acme_challenge http
    }

    # Зворотний проксі для Gitea
    reverse_proxy gitea:3000 {
        # Проксіюємо заголовки, необхідні Gitea
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-For {remote_ip}
    }

    # Налаштування для великих файлів (Git LFS)
    # Gitea сам обробляє LFS, але Caddy повинен пропускати великі запити
    # Якщо у вас будуть дуже великі LFS файли, може знадобитися збільшення body_size
    # (за замовчуванням Caddy обробляє до 10MB)
    # Для Gitea це зазвичай не потрібно, оскільки він сам приймає дані
}

# Переход в директорию с файлами
cd ~/gitea

# Запуск всех сервисов в фоновом режиме
docker compose up -d

# Проверка статуса контейнеров
docker compose ps

Конфігурація

Після успішного запуску контейнерів Gitea та Caddy, вам потрібно виконати початкове налаштування Gitea через веб-інтерфейс, а також переконатися, що всі параметри відповідають вашим вимогам.

1. Початкове налаштування Gitea через веб-інтерфейс

Відкрийте ваш домен (наприклад, https://your.domain.com) у веб-браузері. Ви повинні побачити сторінку початкового налаштування Gitea.

На цій сторінці перевірте та за необхідності змініть наступні параметри:

• Налаштування бази даних:
  • Тип бази даних: SQLite3 (має бути вибрано за замовчуванням).
  • Шлях до файлу бази даних: /data/gitea.db (має бути встановлено зі змінних оточення).
• Налаштування загальних параметрів застосунку:
  • Домен: your.domain.com (встановлено зі змінних оточення).
  • Базовий URL: https://your.domain.com/ (встановлено зі змінних оточення).
  • Шлях до кореневого каталогу Gitea: /data (встановлено зі змінних оточення).
  • Порт для SSH-сервера: 2222 (встановлено зі змінних оточення).
  • Шлях до логів Gitea: /data/log.
• Налаштування адміністратора:

  Створіть першого адміністративного користувача. Введіть ім'я користувача, пароль та адресу електронної пошти. Це буде основний обліковий запис для керування Gitea.

• Налаштування поштового сервера (SMTP): Якщо ви хочете, щоб Gitea надсилав сповіщення (наприклад, про реєстрацію, скидання пароля, згадки), налаштуйте SMTP-сервер.

  
  # Пример настроек SMTP для Gitea (в веб-интерфейсе)
  [mailer]
  ENABLED = true
  HOST = smtp.yourprovider.com:587
  FROM = [email protected]
  USER = [email protected]
  PASSWD = ваш_пароль_smtp
  PROTOCOL = smtps # или smtp+tls
  

Після перевірки всіх параметрів натисніть кнопку "Встановити Gitea". Якщо все пройшло успішно, ви будете перенаправлені на сторінку входу.

2. Конфігураційний файл app.ini

Більшість налаштувань Gitea можна змінити через веб-інтерфейс адміністратора, але деякі параметри зберігаються у файлі app.ini всередині контейнера. Цей файл знаходиться за шляхом /data/gitea/conf/app.ini. Оскільки ми змонтували ./data в /data, ви можете отримати до нього доступ на хості:

# Доступ к app.ini на хосте
nano ~/gitea/data/gitea/conf/app.ini

Після початкової установки Gitea автоматично заповнить цей файл. Ось деякі важливі секції, які ви можете захотіти перевірити або змінити:

# app.ini (пример важных секций)
[server]
DOMAIN = your.domain.com
SSH_DOMAIN = your.domain.com
HTTP_PORT = 3000
ROOT_URL = https://your.domain.com/
DISABLE_SSH = false
SSH_PORT = 2222 # Внутренний порт Gitea для SSH
LFS_START_SERVER = true
LFS_HTTP_HOST = https://your.domain.com/ # URL для Git LFS

[database]
DB_TYPE = sqlite3
PATH = /data/gitea.db

[repository]
ROOT = /data/git/repositories # Путь для хранения репозиториев
DEFAULT_BRANCH = main # Ветка по умолчанию для новых репозиториев

[service]
REGISTER_EMAIL_ACTIVE = false # Требуется ли активация по email при регистрации
DISABLE_REGISTRATION = false # Разрешить ли регистрацию (true для приватного сервера)
REQUIRE_SIGNIN_VIEW = false # Требовать вход для просмотра репозиториев (true для приватного сервера)
NO_REPLY_ADDRESS = [email protected] # Адрес для "no-reply" коммитов

[session]
PROVIDER = db

[cache]
ADAPTER = redis
HOST = redis:6379

[queue]
TYPE = redis
CONN_STR = redis://redis:6379/0

[security]
INSTALL_LOCK = true # Важно: после установки должен быть true
SECRET_KEY = ваш_сгенерированный_ключ # Генерируется автоматически

Якщо ви внесете зміни до app.ini вручну, не забудьте перезапустити контейнер Gitea:

# Перезапуск контейнера Gitea
docker compose restart gitea

3. TLS/HTTPS через Caddy

Caddy автоматично отримав і налаштував SSL-сертифікати для вашого домену. Це підтверджується тим, що ви змогли отримати доступ до Gitea по HTTPS. Caddy автоматично оновлюватиме сертифікати до закінчення терміну їх дії.

Ви можете перевірити статус сертифікатів Caddy:

# Просмотр логов Caddy для проверки статуса сертификатов
docker compose logs caddy | grep -i "certificate"

Ви повинні побачити записи про отримання та/або оновлення сертифікатів Let's Encrypt.

4. Перевірка працездатності

Переконайтеся, що Gitea повністю функціональний:

• Доступ по HTTPS: Відкрийте https://your.domain.com у браузері. Переконайтеся, що з'єднання захищено (зелений замочок).
• Вхід та створення репозиторію: Увійдіть під створеним адміністратором, створіть новий репозиторій.
• Клонування по HTTPS: Спробуйте клонувати репозиторій через HTTPS з вашої локальної машини:

  
  git clone https://your.domain.com/ваш_пользователь/ваш_репозиторий.git
  

  Вам буде запропоновано ввести ім'я користувача та пароль Gitea.

• SSH-доступ: Gitea використовує порт 2222 для SSH. Щоб налаштувати SSH-доступ, вам потрібно додати публічний SSH-ключ вашого користувача Gitea через веб-інтерфейс (Налаштування профілю -> SSH/GPG ключі). Потім ви можете клонувати репозиторій по SSH:

  
  git clone ssh://[email protected]:2222/ваш_пользователь/ваш_репозиторий.git
  

  Важливо: Переконайтеся, що порт 2222 відкрито у вашому фаєрволі на VPS. Якщо ви використовуєте UFW:

  
  sudo ufw allow 2222/tcp
  sudo ufw reload
  

• Healthcheck: Перевірте статус контейнерів:

  
  docker compose ps
  

  Все має бути running та healthy.

Вітаємо! Ваш Gitea-сервер повністю налаштований і готовий до роботи.

# Создание скрипта бэкапа
nano ~/backup_gitea.sh

#!/bin/bash

# Налаштування
BACKUP_DIR="/var/backups/gitea"
GITEA_DIR="/home/ваш_пользователь/gitea" # Путь к директории с docker-compose.yml
DATE=$(date +%Y%m%d%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/gitea_backup_${DATE}.zip"

# Створення директорії для резервних копій, якщо її немає
mkdir -p ${BACKUP_DIR}

echo "--- Починаємо резервне копіювання Gitea (${DATE}) ---"

# 1. Дамп Gitea за допомогою вбудованої утиліти (всередині контейнера)
# Це створить zip-архів у /tmp всередині контейнера Gitea
echo "Створення дампу Gitea..."
docker exec gitea gitea dump -c /data/gitea/conf/app.ini

# 2. Копіювання створеного дампу з контейнера на хост
echo "Копіювання дампу на хост..."
DUMP_CONTAINER_PATH=$(docker exec gitea find /tmp -name "gitea-dump-.zip" -print -quit)
if [ -z "$DUMP_CONTAINER_PATH" ]; then
    echo "Помилка: Дамп Gitea не знайдено в контейнері."
    exit 1
fi
docker cp gitea:${DUMP_CONTAINER_PATH} ${BACKUP_FILE}

# 3. Видалення дампу з контейнера
echo "Видалення тимчасового дампу з контейнера..."
docker exec gitea rm ${DUMP_CONTAINER_PATH}

# 4. Копіювання даних Caddy (сертифікати)
echo "Копіювання даних Caddy..."
tar -czf ${BACKUP_DIR}/caddy_data_backup_${DATE}.tar.gz -C ${GITEA_DIR}/caddy_data .

echo "Резервне копіювання завершено: ${BACKUP_FILE} та ${BACKUP_DIR}/caddy_data_backup_${DATE}.tar.gz"

# Очищення старих резервних копій (наприклад, зберігати останні 7 днів)
echo "Очищення старих резервних копій..."
find ${BACKUP_DIR} -type f -name "gitea_backup_.zip" -mtime +7 -delete
find ${BACKUP_DIR} -type f -name "caddy_data_backup_.tar.gz" -mtime +7 -delete

echo "--- Резервне копіювання Gitea завершено ---"

chmod +x ~/backup_gitea.sh

# Открытие crontab для редактирования
crontab -e

# Ежедневный бэкап Gitea в 03:00
0 3    /home/ваш_пользователь/backup_gitea.sh >> /var/log/gitea_backup.log 2>&1

# Приклад додавання rclone до скрипту backup_gitea.sh
# ... (після створення резервної копії)
echo "Надсилання резервної копії на S3..."
/usr/bin/rclone copy ${BACKUP_FILE} my-s3-remote:gitea-backups/
/usr/bin/rclone copy ${BACKUP_DIR}/caddy_data_backup_${DATE}.tar.gz my-s3-remote:gitea-backups/caddy-data/

# ... (очищення старих резервних копій на S3, якщо налаштовано в rclone або через політики S3)

Вирішення проблем + FAQ

Навіть при найретельнішому налаштуванні можуть виникнути проблеми. Ось список типових питань та проблем, з якими можна зіткнутися при розгортанні Gitea з Docker та Caddy.

Який VPS-конфіг мінімально підійде?

Для базової установки Gitea (без Docker) на невелику кількість користувачів (1-5) можна обійтися 1 vCore CPU, 1 ГБ RAM та 20-30 ГБ SSD. Однак, якщо ви використовуєте Docker та Caddy, а також плануєте до 10-15 користувачів, мінімально рекомендується 2 vCore CPU, 2 ГБ RAM та 40 ГБ SSD. Це забезпечить стабільну роботу та достатній запас ресурсів для операційної системи, Docker-демона та всіх контейнерів.

Що вибрати — VPS чи dedicated для цього завдання?

Для більшості сценаріїв використання Gitea (особисті проєкти, команди до 50 осіб, помірна кількість репозиторіїв) VPS є оптимальним вибором. Він пропонує достатню продуктивність, гнучкість і значно нижчий за вартістю, ніж dedicated-сервер. Dedicated-сервер слід розглядати лише у випадках дуже високого навантаження (сотні користувачів, тисячі репозиторіїв), суворих вимог до ізоляції або за необхідності запуску безлічі інших ресурсомістких сервісів на тій самій машині.

Gitea не запускається або контейнер постійно перезапускається. Що робити?

Насамперед перевірте логи контейнера Gitea: docker compose logs gitea. Часті причини:

• Конфлікт портів: Переконайтеся, що порт 3000 (внутрішній порт Gitea) не зайнятий іншим процесом всередині контейнера або на хості (хоча в нашій конфігурації він не відкритий безпосередньо назовні).
• Проблеми з базою даних: Якщо Gitea не може підключитися до Redis або SQLite-файл пошкоджений. Перевірте логи Gitea на помилки, пов'язані з database або cache.
• Невірні дозволи на файли: Переконайтеся, що користувач Docker всередині контейнера (UID/GID 1000) має права на запис у директорію ./data. Ви можете перевірити права на хості: ls -la ~/gitea/data.
• Неправильний app.ini: Синтаксичні помилки або невірні значення у конфігураційному файлі Gitea.

Caddy не отримує SSL-сертифікат або не перенаправляє трафік.

Перевірте логи Caddy: docker compose logs caddy. Можливі причини:

• Проблеми з DNS: Переконайтеся, що A-запис вашого домену (наприклад, your.domain.com) коректно вказує на IP-адресу вашого VPS. Це можна перевірити за допомогою dig your.domain.com.
• Фаєрвол блокує порти 80/443: Переконайтеся, що UFW (або інший фаєрвол) дозволяє вхідні з'єднання на портах 80 та 443. Перевірте sudo ufw status.
• Інший процес займає порти 80/443 на хості: Переконайтеся, що немає іншого веб-сервера (Apache, Nginx) або іншого Caddy, запущеного на хості та використовуючого ці порти.
• Неправильний Caddyfile: Синтаксичні помилки або невірні налаштування проксі.
• Ліміти Let's Encrypt: Якщо ви багаторазово намагалися отримати сертифікат з одного домену за короткий час, ви могли потрапити під ліміт Let's Encrypt. Зачекайте кілька годин.

Не працює SSH-доступ до репозиторіїв Gitea.

Перевірте наступне:

• Порт 2222 відкритий у фаєрволі: sudo ufw status має показувати дозвіл для порту 2222.
• SSH-ключ додано до Gitea: Переконайтеся, що ваш публічний SSH-ключ додано до налаштувань вашого профілю Gitea через веб-інтерфейс.
• Правильна команда клонування: Використовуйте git clone ssh://[email protected]:2222/ваш_пользователь/ваш_репозиторий.git. Зверніть увагу на git@ та порт :2222.
• Gitea SSH-сервер запущений: Перевірте логи Gitea на предмет помилок, пов'язаних з SSH.

Після оновлення Docker-образів Gitea не запускається.

Це може бути пов'язано зі змінами в новій версії Gitea або Docker. Завжди перевіряйте офіційні changelogs. Якщо Gitea вимагає міграції бази даних, вона зазвичай виконується автоматично при першому запуску. Якщо ні, перевірте логи. Можливо, знадобиться відкотитися до попередньої версії образу (наприклад, gitea/gitea:1.21.10 замість gitea/gitea:1.22.0) та вивчити інструкції з міграції.

Як оновити Gitea?

Для оновлення Gitea (та інших контейнерів) виконайте наступні кроки в директорії ~/gitea:

# 1. Зробіть бекап! Це критично важливо.
# 2. Зупинка поточних контейнерів
docker compose down
# 3. Оновлення Docker-образів до останніх версій, зазначених у docker-compose.yml
#    Якщо ви хочете оновити до новішої версії, змініть тег образу в docker-compose.yml
docker compose pull
# 4. Запуск оновлених контейнерів
docker compose up -d

Після запуску перевірте логи та веб-інтерфейс.

Як змінити налаштування Gitea після початкової установки?

Більшість налаштувань можна змінити через веб-інтерфейс, увійшовши як адміністратор: "Панель адміністратора" -> "Конфігурація сайту". Деякі специфічні налаштування можуть вимагати ручного редагування файлу ~/gitea/data/gitea/conf/app.ini з подальшим перезапуском контейнера Gitea (docker compose restart gitea).