dbstorage/DOCKER_SETUP.md

# Docker Setup - Полное руководство

## 📋 Обзор

Этот проект использует Docker для развертывания Django приложения с PostGIS и TileServer GL.

**Основные компоненты:**
- Django 5.2 с PostGIS
- PostgreSQL 17 с расширением PostGIS 3.4
- TileServer GL для работы с картографическими тайлами
- Nginx (только для production)
- Gunicorn WSGI сервер (production)

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

### Development
```bash
cp .env.dev .env
make dev-up
make createsuperuser
```
Откройте http://localhost:8000

### Production
```bash
cp .env.prod .env
# Отредактируйте .env (SECRET_KEY, пароли, домены)
make prod-up
make prod-createsuperuser
```
Откройте http://yourdomain.com

## 📁 Структура файлов

```
.
├── dbapp/                          # Django приложение
│   ├── Dockerfile                 # Универсальный Dockerfile
│   ├── entrypoint.sh              # Скрипт инициализации
│   ├── .dockerignore              # Исключения для Docker
│   └── ...
│
├── nginx/                          # Nginx конфигурация (prod)
│   ├── conf.d/
│   │   ├── default.conf          # HTTP конфигурация
│   │   └── ssl.conf.example      # HTTPS конфигурация (пример)
│   └── ssl/                       # SSL сертификаты
│
├── tiles/                          # Тайлы для TileServer GL
│   ├── README.md                  # Инструкция по настройке
│   ├── config.json.example        # Пример конфигурации
│   └── .gitignore
│
├── docker-compose.yaml             # Development окружение
├── docker-compose.prod.yaml        # Production окружение
│
├── .env.dev                        # Переменные для dev
├── .env.prod                       # Переменные для prod (шаблон)
│
├── Makefile                        # Удобные команды
├── generate_secret_key.py          # Генератор SECRET_KEY
│
└── Документация:
    ├── QUICKSTART.md              # Быстрый старт
    ├── DOCKER_README.md           # Подробная документация
    ├── DEPLOYMENT_CHECKLIST.md    # Чеклист для деплоя
    └── DOCKER_SETUP.md            # Этот файл
```

## 🔧 Конфигурация

### Dockerfile

**Один универсальный Dockerfile** для dev и prod:
- Multi-stage build для оптимизации размера
- Установка GDAL, PostGIS зависимостей
- Использование uv для управления зависимостями
- Non-root пользователь для безопасности
- Healthcheck для мониторинга

### entrypoint.sh

Скрипт автоматически:
- Ждет готовности PostgreSQL
- Выполняет миграции
- Собирает статику (только prod)
- Запускает runserver (dev) или Gunicorn (prod)

Поведение определяется переменной `ENVIRONMENT`:
- `development` → Django development server
- `production` → Gunicorn WSGI server

### docker-compose.yaml (Development)

**Сервисы:**
- `db` - PostgreSQL с PostGIS
- `web` - Django приложение
- `tileserver` - TileServer GL

**Особенности:**
- Код монтируется как volume (live reload)
- DEBUG=True
- Django development server
- Простые пароли для локальной разработки

### docker-compose.prod.yaml (Production)

**Сервисы:**
- `db` - PostgreSQL с PostGIS
- `web` - Django с Gunicorn
- `tileserver` - TileServer GL
- `nginx` - Reverse proxy

**Особенности:**
- Код копируется в образ (не монтируется)
- DEBUG=False
- Gunicorn WSGI server
- Nginx для статики и проксирования
- Сильные пароли из .env
- Сбор статики (collectstatic)

## 🔐 Безопасность

### Для Production обязательно:

1. **Сгенерируйте SECRET_KEY:**
   ```bash
   python generate_secret_key.py
   ```

2. **Измените пароли БД** в `.env`

3. **Настройте ALLOWED_HOSTS:**
   ```
   ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
   ```

4. **Настройте SSL/HTTPS** (рекомендуется):
   - Получите сертификаты (Let's Encrypt)
   - Поместите в `nginx/ssl/`
   - Используйте `nginx/conf.d/ssl.conf.example`

5. **Ограничьте доступ к портам:**
   - Открыть: 80, 443
   - Закрыть: 5432, 8000

## 📊 Мониторинг

### Логи
```bash
# Development
make dev-logs

# Production
make prod-logs

# Конкретный сервис
docker-compose logs -f web
docker-compose logs -f db
```

### Статус
```bash
make status              # Development
make prod-status         # Production
docker stats             # Использование ресурсов
```

### Healthcheck
```bash
curl http://localhost:8000/admin/
```

## 💾 Backup и восстановление

### Backup
```bash
make backup
# или
docker-compose exec db pg_dump -U geralt geodb > backup_$(date +%Y%m%d).sql
```

### Восстановление
```bash
docker-compose exec -T db psql -U geralt geodb < backup.sql
```

### Автоматический backup (cron)
```bash
# Добавьте в crontab
0 2 * * * cd /path/to/project && make backup
```

## 🔄 Обновление

### Development
```bash
git pull
make dev-build
```

### Production
```bash
git pull
make prod-build
make prod-migrate
```

## 🗺️ TileServer GL

Поместите `.mbtiles` файлы в директорию `tiles/`:

```bash
tiles/
├── world.mbtiles
└── satellite.mbtiles
```

Доступ: http://localhost:8080

Подробнее: [tiles/README.md](tiles/README.md)

## 🛠️ Makefile команды

### Development
```bash
make dev-up              # Запустить
make dev-down            # Остановить
make dev-build           # Пересобрать
make dev-logs            # Логи
make dev-restart         # Перезапустить web
```

### Production
```bash
make prod-up             # Запустить
make prod-down           # Остановить
make prod-build          # Пересобрать
make prod-logs           # Логи
make prod-restart        # Перезапустить web
```

### Django
```bash
make shell               # Django shell
make migrate             # Миграции
make makemigrations      # Создать миграции
make createsuperuser     # Создать суперпользователя
make collectstatic       # Собрать статику
```

### Утилиты
```bash
make backup              # Backup БД
make status              # Статус контейнеров
make clean               # Очистка (с volumes)
make clean-all           # Полная очистка
```

## 📚 Дополнительная документация

- **[QUICKSTART.md](QUICKSTART.md)** - Быстрый старт для нетерпеливых
- **[DOCKER_README.md](DOCKER_README.md)** - Подробная документация по Docker
- **[DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md)** - Чеклист для деплоя
- **[tiles/README.md](tiles/README.md)** - Настройка TileServer GL

## ❓ Troubleshooting

### Контейнеры не запускаются
```bash
docker-compose logs
docker-compose config
```

### База данных недоступна
```bash
docker-compose exec db pg_isready -U geralt
docker-compose logs db
```

### Статические файлы не загружаются
```bash
docker-compose exec web python manage.py collectstatic --noinput
docker-compose exec web ls -la /app/staticfiles
```

### 502 Bad Gateway
```bash
docker-compose ps web
docker-compose logs web
docker-compose exec nginx nginx -t
```

## 🎯 Следующие шаги

1. ✅ Прочитайте [QUICKSTART.md](QUICKSTART.md)
2. ✅ Запустите development окружение
3. ✅ Изучите [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) перед деплоем
4. ✅ Настройте TileServer GL ([tiles/README.md](tiles/README.md))
5. ✅ Настройте SSL для production

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

При возникновении проблем:
1. Проверьте логи: `make dev-logs` или `make prod-logs`
2. Изучите документацию в этой директории
3. Проверьте [DOCKER_README.md](DOCKER_README.md) для подробностей