Add Docker deployment setup and comprehensive local development envir…

.env.example

@@ -0,0 +1,45 @@
+# Пример файла переменных окружения для Bulker
+# Скопируйте в .env и измените значения по необходимости
+
+# === Основные настройки ===
+BULKER_HTTP_PORT=3042
+BULKER_INSTANCE_ID=local-instance
+BULKER_LOG_LEVEL=INFO
+BULKER_LOG_FORMAT=json
+
+# === Kafka настройки ===
+BULKER_KAFKA_BOOTSTRAP_SERVERS=kafka:9092
+BULKER_KAFKA_CONSUMER_GROUP_ID=bulker-local
+BULKER_KAFKA_TOPIC_PREFIX=bulker_local_
+
+# === PostgreSQL настройки ===
+BULKER_DESTINATION_POSTGRES_HOST=postgres
+BULKER_DESTINATION_POSTGRES_PORT=5432
+BULKER_DESTINATION_POSTGRES_DB=bulker
+BULKER_DESTINATION_POSTGRES_USER=bulker
+BULKER_DESTINATION_POSTGRES_PASSWORD=bulker_password
+BULKER_DESTINATION_POSTGRES_SSL_MODE=disable
+
+# === Redis настройки ===
+BULKER_REDIS_URL=redis://redis:6379
+
+# === Авторизация ===
+BULKER_RAW_AUTH_TOKENS=local-token-123,admin-token-456,test-token-789
+
+# === Метрики ===
+BULKER_METRICS_ENABLED=true
+BULKER_METRICS_PORT=9090
+
+# === Производительность ===
+BULKER_BATCH_SIZE=1000
+BULKER_BATCH_TIMEOUT=5s
+BULKER_MAX_CONNECTIONS=10
+
+# === PostgreSQL (для docker-compose) ===
+POSTGRES_DB=bulker
+POSTGRES_USER=bulker
+POSTGRES_PASSWORD=bulker_password
+
+# === Mock Server настройки ===
+MOCK_PORT=3042
+MOCK_TOKENS=local-token-123,admin-token-456,test-token-789

DEPLOYMENT.md

@@ -0,0 +1,255 @@
+# 🚚 Развертывание Bulker в тестовой среде
+
+Этот документ описывает, как развернуть Bulker в тестовой среде с использованием Docker Compose.
+
+## Предварительные требования
+
+- Docker 20.10+
+- Docker Compose 2.0+
+- curl (для тестирования API)
+
+## Быстрый старт
+
+### 1. Сборка и запуск всех сервисов
+
+```bash
+# Сборка и запуск в фоновом режиме
+docker compose -f docker-compose.test.yml up -d --build
+
+# Просмотр логов
+docker compose -f docker-compose.test.yml logs -f
+```
+
+### 2. Проверка статуса сервисов
+
+```bash
+# Проверка статуса всех сервисов
+docker compose -f docker-compose.test.yml ps
+
+# Проверка здоровья сервисов
+docker compose -f docker-compose.test.yml ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"
+```
+
+### 3. Тестирование API
+
+```bash
+# Запуск автоматических тестов
+./test-api.sh
+
+# Или ручная проверка готовности
+curl http://localhost:12000/ready
+```
+
+## Архитектура развертывания
+
+Тестовая среда включает следующие компоненты:
+
+### Инфраструктурные сервисы
+- **Zookeeper** (порт 2181) - координация для Kafka
+- **Kafka** (порты 9092, 9093) - очередь сообщений
+- **PostgreSQL** (порт 5432) - тестовая база данных
+- **Redis** (порт 6379) - кеширование конфигурации
+
+### Приложения Bulker
+- **Bulker App** (порт 12000) - основное HTTP API
+- **Ingest Service** (порт 12001) - сервис приема данных
+
+## Конфигурация
+
+### Переменные окружения
+
+Основные настройки задаются через переменные окружения в `docker-compose.test.yml`:
+
+```yaml
+# Аутентификация
+BULKER_RAW_AUTH_TOKENS=test-token-123,admin-token-456
+
+# Kafka
+BULKER_KAFKA_BOOTSTRAP_SERVERS=kafka:9092
+
+# Destination для PostgreSQL
+BULKER_DESTINATION_POSTGRES_TEST={"type":"postgres",...}
+```
+
+### Destinations
+
+В тестовой среде настроен один destination:
+- **ID**: `postgres_test`
+- **Тип**: PostgreSQL
+- **Режим**: batch (пакетный)
+- **Размер пакета**: 100 записей
+
+## API Endpoints
+
+### Основные endpoints
+
+- `GET /ready` - проверка готовности сервиса
+- `POST /post/:destinationId?tableName=:table` - отправка события
+- `GET /metrics` - метрики Prometheus
+
+### Примеры использования
+
+#### Отправка простого события
+
+```bash
+curl -X POST "http://localhost:12000/post/postgres_test?tableName=user_events" \
+  -H "Authorization: Bearer test-token-123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "event_type": "page_view",
+    "timestamp": "2025-12-13T12:00:00Z"
+  }'
+```
+
+#### Отправка события с типизацией
+
+```bash
+curl -X POST "http://localhost:12000/post/postgres_test?tableName=purchases" \
+  -H "Authorization: Bearer test-token-123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": 12345,
+    "amount": "99.99",
+    "__sql_type_amount": "decimal(10,2)",
+    "currency": "USD"
+  }'
+```
+
+## Мониторинг и отладка
+
+### Просмотр логов
+
+```bash
+# Логи всех сервисов
+docker compose -f docker-compose.test.yml logs
+
+# Логи конкретного сервиса
+docker compose -f docker-compose.test.yml logs bulker
+docker compose -f docker-compose.test.yml logs kafka
+docker compose -f docker-compose.test.yml logs postgres
+```
+
+### Подключение к базе данных
+
+```bash
+# Подключение к PostgreSQL
+docker exec -it bulker-postgres psql -U bulker -d bulker_test
+
+# Просмотр созданных таблиц
+\dt
+
+# Просмотр данных в таблице
+SELECT * FROM user_events LIMIT 10;
+```
+
+### Проверка Kafka
+
+```bash
+# Список топиков
+docker exec -it bulker-kafka kafka-topics.sh --bootstrap-server localhost:9092 --list
+
+# Просмотр сообщений в топике
+docker exec -it bulker-kafka kafka-console-consumer.sh \
+  --bootstrap-server localhost:9092 \
+  --topic bulker-events \
+  --from-beginning
+```
+
+## Остановка и очистка
+
+### Остановка сервисов
+
+```bash
+# Остановка всех сервисов
+docker compose -f docker-compose.test.yml down
+
+# Остановка с удалением volumes (полная очистка)
+docker compose -f docker-compose.test.yml down -v
+```
+
+### Очистка Docker
+
+```bash
+# Удаление неиспользуемых образов
+docker image prune -f
+
+# Полная очистка Docker
+docker system prune -a -f
+```
+
+## Устранение неполадок
+
+### Проблемы с запуском
+
+1. **Порты заняты**: Убедитесь, что порты 12000, 12001, 5432, 9092, 6379 свободны
+2. **Недостаток памяти**: Kafka требует минимум 2GB RAM
+3. **Проблемы с сетью**: Проверьте, что Docker может создавать сети
+
+### Проблемы с подключением
+
+1. **Kafka недоступен**: Дождитесь полной инициализации (может занять 1-2 минуты)
+2. **PostgreSQL недоступен**: Проверьте логи postgres сервиса
+3. **Bulker не отвечает**: Проверьте health check статус
+
+### Полезные команды для диагностики
+
+```bash
+# Проверка сетевого подключения
+docker exec -it bulker-app ping kafka
+docker exec -it bulker-app ping postgres
+
+# Проверка портов
+docker exec -it bulker-app netstat -tlnp
+
+# Проверка переменных окружения
+docker exec -it bulker-app env | grep BULKER
+```
+
+## Производительность
+
+### Рекомендуемые ресурсы
+
+- **CPU**: 2+ ядра
+- **RAM**: 4GB+ (2GB для Kafka, 1GB для PostgreSQL, 1GB для Bulker)
+- **Диск**: 10GB+ свободного места
+
+### Настройка для нагрузочного тестирования
+
+Для тестирования высоких нагрузок измените в `docker-compose.test.yml`:
+
+```yaml
+# Увеличьте размер пакета
+BULKER_DESTINATION_POSTGRES_TEST: '{"options":{"batchSize":1000},...}'
+
+# Добавьте больше партиций Kafka
+KAFKA_CFG_NUM_PARTITIONS: 10
+```
+
+## Интеграция с внешними системами
+
+### Подключение к внешней базе данных
+
+Замените PostgreSQL сервис на подключение к внешней БД:
+
+```yaml
+environment:
+  - BULKER_DESTINATION_EXTERNAL_DB={"type":"postgres","credentials":{"host":"external-db.example.com",...}}
+```
+
+### Использование внешнего Kafka
+
+```yaml
+environment:
+  - BULKER_KAFKA_BOOTSTRAP_SERVERS=external-kafka.example.com:9092
+```
+
+## Безопасность
+
+⚠️ **Внимание**: Эта конфигурация предназначена только для тестирования!
+
+Для production использования:
+- Используйте сложные пароли
+- Настройте SSL/TLS
+- Ограничьте сетевой доступ
+- Используйте хешированные токены аутентификации