# 🗄️ Universal Docker Backup Service

![Build Status](https://github.com/USERNAME/docker-s3-backup/actions/workflows/docker-build.yml/badge.svg)

Универсальная система автоматического резервного копирования Docker-проектов с загрузкой в S3-совместимое хранилище.

## ✨ Возможности

- ✅ Автоматическое создание tar.gz архивов по расписанию (cron)
- ✅ Загрузка бэкапов в S3-совместимые хранилища (Yandex Cloud, AWS S3, MinIO, Timeweb и т.д.)
- ✅ Опциональная остановка сервисов перед бекапом для консистентности данных
- ✅ Автоматическое удаление старых бэкапов
- ✅ Подробное логирование всех операций
- ✅ Запуск в отдельном Docker-контейнере

## 🚀 Быстрый старт

### Вариант 1: Использование готового образа (рекомендуется)

Создайте `docker-compose.yaml` в директории вашего проекта:

```yaml
services:
  backup:
    image: ghcr.io/USERNAME/docker-s3-backup:latest
    container_name: project-backup
    restart: unless-stopped
    environment:
      # Ваши настройки (см. ниже)
    volumes:
      - .:/backup-source:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
```

### Вариант 2: Сборка из исходников

Скопируйте файлы в директорию вашего проекта, который нужно бекапить:

```bash
git clone <this-repo> backup-system
cd your-project
cp -r backup-system/* .
```

### Настройка

Отредактируйте `docker-compose.yaml` и укажите свои значения переменных окружения:

```yaml
environment:
  # Обязательные параметры
  - BACKUP_PROJECT_NAME=my-project
  - BACKUP_S3_BUCKET=my-backups
  - BACKUP_S3_ENDPOINT=s3.twcstorage.ru
  - BACKUP_S3_ACCESS_KEY=your_access_key
  - BACKUP_S3_SECRET_KEY=your_secret_key
  
  # Необязательные параметры
  - BACKUP_SCHEDULE=0 3 * * *  # Каждый день в 03:00
  - BACKUP_RETENTION_DAYS=30
```

### Запуск

```bash
docker compose up -d backup
```

Проверить логи:

```bash
docker compose logs -f backup
```

> **Примечание:** Замените `USERNAME` в URL образа на ваш GitHub username после публикации проекта.

## 📋 Переменные окружения

Все параметры подробно описаны в `docker-compose.yaml` с примерами использования.

### Обязательные параметры

| Параметр | Описание | Пример |
|----------|----------|--------|
| `BACKUP_S3_BUCKET` | Имя S3 бакета | `my-backups` |
| `BACKUP_S3_ENDPOINT` | Эндпоинт S3 сервиса | `s3.twcstorage.ru` |
| `BACKUP_S3_ACCESS_KEY` | Ключ доступа S3 | `your_key` |
| `BACKUP_S3_SECRET_KEY` | Секретный ключ S3 | `your_secret` |

### Необязательные параметры

| Параметр | Значение по умолчанию | Описание |
|----------|----------------------|----------|
| `BACKUP_PROJECT_NAME` | `project` | Имя проекта для архивов |
| `BACKUP_S3_FOLDER` | ` ` (корень) | Папка внутри бакета |
| `BACKUP_S3_REGION` | `ru-1` | Регион S3 |
| `BACKUP_RETENTION_DAYS` | `30` | Дни хранения бэкапов |
| `BACKUP_SCHEDULE` | `0 3 * * *` | Расписание cron |
| `BACKUP_ON_START` | `false` | Бекап при старте |
| `BACKUP_STOP_SERVICES` | ` ` | Сервисы для остановки |
| `BACKUP_COMPOSE_FILE` | ` ` | Путь к compose-файлу |

## 🛠️ Расширенные сценарии

### Остановка сервисов перед бекапом

Для консистентности данных можно останавливать сервисы перед созданием архива:

```yaml
environment:
  # ... другие параметры ...
  - BACKUP_STOP_SERVICES=gitea gitea-db
  - BACKUP_COMPOSE_FILE=/backup-source/docker-compose.yml
```

**Важно:**
- Сервисы будут остановлены через `docker compose down`
- После создания архива сервисы автоматически запустятся через `docker compose up -d`
- Если бекап упадет с ошибкой - сервисы все равно запустятся обратно

### Изменение директории для бекапа

По умолчанию бекапится текущая директория (`.`). Чтобы изменить:

```yaml
volumes:
  - /path/to/your/project:/backup-source:ro
  # ... остальные volumes ...
```

### Примеры расписаний (cron)

```yaml
# Каждый день в 03:00
- BACKUP_SCHEDULE=0 3 * * *

# Каждые 6 часов
- BACKUP_SCHEDULE=0 */6 * * *

# Каждое воскресенье в 02:00
- BACKUP_SCHEDULE=0 2 * * 0

# Каждые 30 минут
- BACKUP_SCHEDULE=*/30 * * * *

# Дважды в день: 03:00 и 15:00
- BACKUP_SCHEDULE=0 3,15 * * *
```

### Тестовый бекап

Для проверки настроек запустите бекап вручную:

```bash
docker compose exec backup /scripts/backup.sh
```

Или включите бекап при старте:

```yaml
- BACKUP_ON_START=true
```

## 📂 Формат архивов

Архивы создаются в формате:

```
{BACKUP_PROJECT_NAME}-backup-YYYY-MM-DD_HH-MM-SS.tar.gz
```

Пример: `my-project-backup-2025-10-22_03-00-00.tar.gz`

## 🔧 Структура проекта

```
.
├── backup.sh          # Основной скрипт бекапа
├── entrypoint.sh      # Точка входа контейнера
├── crontab            # Шаблон cron (генерируется автоматически)
├── Dockerfile         # Образ контейнера
├── docker-compose.yaml # Конфигурация сервиса
└── README.md          # Документация
```

## 🐛 Решение проблем

### Проверка логов

```bash
# Все логи
docker compose logs backup

# Логи в реальном времени
docker compose logs -f backup

# Внутренние логи бекапа
docker compose exec backup cat /var/log/backup.log
```

### Проверка доступа к S3

```bash
docker compose exec backup aws s3 ls s3://your-bucket --endpoint-url=https://your-endpoint
```

### Ручной запуск бекапа

```bash
docker compose exec backup /scripts/backup.sh
```

## 📊 S3-провайдеры

### Yandex Cloud Object Storage

```yaml
- BACKUP_S3_ENDPOINT=storage.yandexcloud.net
- BACKUP_S3_REGION=ru-central1
```

### Timeweb Cloud S3

```yaml
- BACKUP_S3_ENDPOINT=s3.twcstorage.ru
- BACKUP_S3_REGION=ru-1
```

### AWS S3

```yaml
- BACKUP_S3_ENDPOINT=s3.amazonaws.com
- BACKUP_S3_REGION=us-east-1
```

### MinIO (self-hosted)

```yaml
- BACKUP_S3_ENDPOINT=minio.your-domain.com
- BACKUP_S3_REGION=us-east-1
```

## 🔄 CI/CD

Проект использует GitHub Actions для автоматической сборки и публикации Docker-образов:

- **Сборка:** При каждом push в main/master
- **Публикация:** Автоматическая публикация в GitHub Container Registry (ghcr.io)
- **Платформы:** Поддержка amd64 и arm64 архитектур
- **Теги:** 
  - `latest` - последняя версия из main/master
  - `v1.0.0` - семантическое версионирование при создании тегов
  - `main-sha` - образы с хешем коммита

Готовые образы доступны по адресу: `ghcr.io/USERNAME/docker-s3-backup`

## 📝 Лицензия

MIT

## 🤝 Поддержка

При возникновении проблем создайте issue в репозитории.