logboard/docs/configuration.md

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

**Автор:** Сергей Антропов  
**Сайт:** https://devops.org.ru

## Содержание

1. [Обзор конфигурации](#обзор-конфигурации)
2. [Переменные окружения](#переменные-окружения)
3. [Настройка Docker](#настройка-docker)
4. [Настройка безопасности](#настройка-безопасности)
5. [Настройка производительности](#настройка-производительности)
6. [Настройка логирования](#настройка-логирования)
7. [Примеры конфигураций](#примеры-конфигураций)

## Обзор конфигурации

LogBoard+ использует переменные окружения для настройки всех аспектов работы приложения. Конфигурация разделена на несколько категорий для удобства управления.

### Файлы конфигурации

- `.env` - Основной файл конфигурации (создается из `env.example`)
- `docker-compose.yml` - Конфигурация Docker Compose
- `app/excluded_containers.json` - Список исключенных контейнеров

### Приоритет настроек

1. Переменные окружения системы
2. Файл `.env`
3. Значения по умолчанию в коде

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

### Основные настройки приложения

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `LOGBOARD_PORT` | Порт веб-интерфейса | `9001` | Нет |
| `LOGBOARD_TAIL` | Количество строк логов по умолчанию | `500` | Нет |
| `LOGBOARD_USER` | Имя пользователя для входа | `admin` | Нет |
| `LOGBOARD_PASS` | Пароль пользователя | `admin` | Да |
| `LOGBOARD_SNAPSHOT_DIR` | Директория для снимков логов | `/app/snapshots` | Нет |
| `LOGBOARD_INDEX_HTML` | Путь к HTML шаблону | `./templates/index.html` | Нет |
| `TZ_TS` | Временная зона | `Europe/Moscow` | Нет |

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

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `COMPOSE_PROJECT_NAME` | Фильтр по проекту Docker Compose | - | Нет |
| `LOGBOARD_PROJECTS` | Множественные проекты (через запятую) | - | Нет |
| `DOCKER_HOST` | Путь к Docker socket | `unix:///var/run/docker.sock` | Нет |
| `DOCKER_TLS_VERIFY` | Проверка TLS для Docker | - | Нет |
| `DOCKER_CERT_PATH` | Путь к сертификатам Docker | - | Нет |
| `DOCKER_NETWORKS` | Внешние сети Docker | `iaas,infrastructure_iaas` | Нет |

### Настройки безопасности

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `SECRET_KEY` | Секретный ключ для JWT | `your-secret-key-here` | Да |
| `ENCRYPTION_KEY` | Ключ шифрования | `your-encryption-key-here` | Да |
| `AUTH_ENABLED` | Включить аутентификацию | `true` | Нет |
| `AUTH_METHOD` | Метод аутентификации | `jwt` | Нет |
| `SESSION_TIMEOUT` | Время жизни сессии (секунды) | `3600` | Нет |

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

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `MAX_CONNECTIONS` | Максимальное количество соединений | `100` | Нет |
| `CONNECTION_TIMEOUT` | Таймаут подключения (секунды) | `30` | Нет |
| `READ_TIMEOUT` | Таймаут чтения (секунды) | `60` | Нет |
| `LOGBOARD_AJAX_UPDATE_INTERVAL` | Интервал AJAX обновления (мс) | `2000` | Нет |

### Настройки фильтрации контейнеров

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `LOGBOARD_SKIP_UNHEALTHY` | Пропускать нездоровые контейнеры | `true` | Нет |
| `LOGBOARD_CONTAINER_LIST_TIMEOUT` | Таймаут получения списка контейнеров | `10` | Нет |
| `LOGBOARD_CONTAINER_INFO_TIMEOUT` | Таймаут получения информации о контейнере | `3` | Нет |
| `LOGBOARD_HEALTH_CHECK_TIMEOUT` | Таймаут health check | `2` | Нет |

### Настройки логирования

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `LOG_LEVEL` | Уровень логирования | `INFO` | Нет |
| `LOG_FORMAT` | Формат логов | `json` | Нет |

### Настройки веб-интерфейса

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `WEB_TITLE` | Заголовок веб-интерфейса | `LogBoard+` | Нет |
| `WEB_DESCRIPTION` | Описание веб-интерфейса | `Веб-панель для просмотра логов микросервисов` | Нет |
| `WEB_VERSION` | Версия веб-интерфейса | `1.0.0` | Нет |

### Настройки режима отладки

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `DEBUG_MODE` | Режим отладки | `false` | Нет |

**Режим отладки включает:**
- **Auto-reload** - автоматическая перезагрузка при изменении кода
- **Swagger UI** - документация API по адресу `/docs`
- **ReDoc** - альтернативная документация по адресу `/redoc`
- **Подробное логирование** - детальные логи для отладки

Важно: в продакшене обязательно установите `DEBUG_MODE=false`.

### Настройки уведомлений

| Переменная | Описание | По умолчанию | Обязательная |
|------------|----------|--------------|--------------|
| `NOTIFICATIONS_ENABLED` | Включить уведомления | `false` | Нет |
| `SMTP_HOST` | SMTP сервер | - | Нет |
| `SMTP_PORT` | Порт SMTP | `587` | Нет |
| `SMTP_USER` | Пользователь SMTP | - | Нет |
| `SMTP_PASS` | Пароль SMTP | - | Нет |
| `SMTP_FROM` | Email отправителя | - | Нет |

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

### Подключение к Docker daemon

#### Локальный Docker

```bash
# Стандартная конфигурация для локального Docker
DOCKER_HOST=unix:///var/run/docker.sock
```

#### Удаленный Docker

```bash
# Подключение к удаленному Docker daemon
DOCKER_HOST=tcp://192.168.1.100:2375

# С TLS сертификатами
DOCKER_HOST=tcp://192.168.1.100:2376
DOCKER_TLS_VERIFY=1
DOCKER_CERT_PATH=/path/to/certs
```

### Фильтрация проектов

#### Один проект

```bash
# Показать только контейнеры из одного проекта
COMPOSE_PROJECT_NAME=myproject
```

#### Несколько проектов

```bash
# Показать контейнеры из нескольких проектов
LOGBOARD_PROJECTS=project1,project2,project3
```

#### Все проекты

```bash
# Показать все контейнеры (по умолчанию)
# Оставьте переменные пустыми или не указывайте их
```

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

```bash
# Подключение к внешним Docker сетям
DOCKER_NETWORKS=iaas,infrastructure_iaas,frontend,backend
```

## Настройка безопасности

### Генерация секретных ключей

```bash
# Генерация секретного ключа для JWT
openssl rand -hex 32
# 8a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

# Генерация ключа шифрования
openssl rand -hex 32
# 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7
```

### Настройка аутентификации

```bash
# Включение аутентификации
AUTH_ENABLED=true
AUTH_METHOD=jwt

# Настройка времени жизни сессии (1 час)
SESSION_TIMEOUT=3600

# Настройка пользователей
LOGBOARD_USER=admin
LOGBOARD_PASS=your-secure-password
```

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

Для продакшена рекомендуется использовать HTTPS через reverse proxy:

```nginx
# Nginx конфигурация
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_pass http://localhost:9001;
        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;
        
        # WebSocket поддержка
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

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

### Ограничения соединений

```bash
# Максимальное количество одновременных подключений
MAX_CONNECTIONS=100

# Таймауты
CONNECTION_TIMEOUT=30
READ_TIMEOUT=60
```

### Настройка AJAX обновления

```bash
# Интервал обновления логов (в миллисекундах)
LOGBOARD_AJAX_UPDATE_INTERVAL=2000

# Количество строк логов по умолчанию
LOGBOARD_TAIL=500
```

### Оптимизация Docker

```bash
# Таймауты для операций с Docker
LOGBOARD_CONTAINER_LIST_TIMEOUT=10
LOGBOARD_CONTAINER_INFO_TIMEOUT=3
LOGBOARD_HEALTH_CHECK_TIMEOUT=2

# Пропуск нездоровых контейнеров
LOGBOARD_SKIP_UNHEALTHY=true
```

## Настройка логирования

### Уровни логирования

```bash
# Доступные уровни: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

# Форматы: json, text
LOG_FORMAT=json
```

### Настройка логов приложения

```bash
# Создание директории для логов
sudo mkdir -p /var/log/logboard
sudo chown $USER:$USER /var/log/logboard

# Обновление docker-compose.yml
volumes:
  - /var/log/logboard:/app/logs
```

## Исключение контейнеров

### Файл excluded_containers.json

```json
{
  "excluded_containers": [
    "noisy-container-1",
    "noisy-container-2",
    "debug-container",
    "test-container"
  ],
  "description": "Контейнеры с избыточным логированием, исключенные из отображения"
}
```

### Управление через API

```bash
# Получение списка исключенных контейнеров
curl -X GET "http://localhost:9001/api/containers/excluded" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Обновление списка
curl -X POST "http://localhost:9001/api/containers/excluded" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '["container1", "container2"]'
```

## Примеры конфигураций

### Разработка

```bash
# .env для разработки
LOGBOARD_PORT=9001
LOGBOARD_USER=admin
LOGBOARD_PASS=dev-password
SECRET_KEY=dev-secret-key-change-in-production
ENCRYPTION_KEY=dev-encryption-key-change-in-production

# Docker настройки
DOCKER_HOST=unix:///var/run/docker.sock
LOGBOARD_PROJECTS=dev-project

# Производительность
LOGBOARD_TAIL=100
LOGBOARD_AJAX_UPDATE_INTERVAL=1000
LOG_LEVEL=DEBUG

# Безопасность
AUTH_ENABLED=true
SESSION_TIMEOUT=7200

# Режим отладки
DEBUG_MODE=true
```

### Режим отладки

```bash
# .env для режима отладки
LOGBOARD_PORT=9001
LOGBOARD_USER=admin
LOGBOARD_PASS=dev-password
SECRET_KEY=dev-secret-key
ENCRYPTION_KEY=dev-encryption-key

# Docker настройки
DOCKER_HOST=unix:///var/run/docker.sock

# Производительность
LOGBOARD_TAIL=50
LOGBOARD_AJAX_UPDATE_INTERVAL=500
LOG_LEVEL=DEBUG

# Безопасность
AUTH_ENABLED=true
SESSION_TIMEOUT=7200

# Режим отладки (ВКЛЮЧЕН)
DEBUG_MODE=true

# Команды для управления режимом отладки:
# make debug-on    # Включить режим отладки
# make debug-off   # Выключить режим отладки
# make debug-status # Проверить статус
```

### Тестирование

```bash
# .env для тестирования
LOGBOARD_PORT=9002
LOGBOARD_USER=test
LOGBOARD_PASS=test-password
SECRET_KEY=test-secret-key
ENCRYPTION_KEY=test-encryption-key

# Docker настройки
DOCKER_HOST=unix:///var/run/docker.sock
LOGBOARD_PROJECTS=test-project

# Производительность
LOGBOARD_TAIL=50
LOGBOARD_AJAX_UPDATE_INTERVAL=500
LOG_LEVEL=INFO

# Безопасность
AUTH_ENABLED=true
SESSION_TIMEOUT=1800
```

### Продакшен

```bash
# .env для продакшена
LOGBOARD_PORT=9001
LOGBOARD_USER=admin
LOGBOARD_PASS=very-secure-password-here
SECRET_KEY=8a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
ENCRYPTION_KEY=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7

# Docker настройки
DOCKER_HOST=unix:///var/run/docker.sock
LOGBOARD_PROJECTS=prod-project,monitoring

# Производительность
LOGBOARD_TAIL=1000
LOGBOARD_AJAX_UPDATE_INTERVAL=5000
MAX_CONNECTIONS=200
CONNECTION_TIMEOUT=60
READ_TIMEOUT=120

# Безопасность
AUTH_ENABLED=true
SESSION_TIMEOUT=3600

# Логирование
LOG_LEVEL=WARNING
LOG_FORMAT=json

# Режим отладки (ОБЯЗАТЕЛЬНО ВЫКЛЮЧЕН в продакшене)
DEBUG_MODE=false

# Уведомления
NOTIFICATIONS_ENABLED=true
SMTP_HOST=smtp.company.com
SMTP_PORT=587
SMTP_USER=logboard@company.com
SMTP_PASS=email-password
SMTP_FROM=logboard@company.com
```

### Масштабированная установка

```bash
# .env для масштабированной установки
LOGBOARD_PORT=9001
LOGBOARD_USER=admin
LOGBOARD_PASS=very-secure-password
SECRET_KEY=8a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
ENCRYPTION_KEY=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7

# Docker настройки
DOCKER_HOST=tcp://docker-swarm-manager:2376
DOCKER_TLS_VERIFY=1
DOCKER_CERT_PATH=/etc/docker/certs
LOGBOARD_PROJECTS=app1,app2,app3,monitoring

# Производительность
LOGBOARD_TAIL=2000
LOGBOARD_AJAX_UPDATE_INTERVAL=3000
MAX_CONNECTIONS=500
CONNECTION_TIMEOUT=120
READ_TIMEOUT=300

# Безопасность
AUTH_ENABLED=true
SESSION_TIMEOUT=7200

# Логирование
LOG_LEVEL=INFO
LOG_FORMAT=json

# Уведомления
NOTIFICATIONS_ENABLED=true
SMTP_HOST=smtp.company.com
SMTP_PORT=587
SMTP_USER=logboard@company.com
SMTP_PASS=email-password
SMTP_FROM=logboard@company.com
```

## Проверка конфигурации

### Валидация переменных окружения

```bash
# Проверка конфигурации
make env-check

# Проверка Docker Compose
make validate
```

### Тестирование подключения

```bash
# Проверка подключения к Docker
docker ps

# Проверка доступности API
curl http://localhost:9001/healthz

# Проверка аутентификации
curl -X POST "http://localhost:9001/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'
```

### Мониторинг конфигурации

```bash
# Просмотр текущих настроек
curl -X GET "http://localhost:9001/api/settings" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Проверка списка контейнеров
curl -X GET "http://localhost:9001/api/services" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Рекомендации по безопасности

### Обязательные настройки для продакшена

1. **Измените пароли по умолчанию**
2. **Используйте сильные секретные ключи**
3. **Настройте HTTPS через reverse proxy**
4. **Ограничьте доступ к Docker socket**
5. **Настройте файрвол**
6. **Регулярно обновляйте зависимости**
7. **Мониторьте логи доступа**

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

```bash
# Проверка прав доступа к Docker socket
ls -la /var/run/docker.sock

# Проверка пользователей в группе docker
getent group docker

# Проверка открытых портов
netstat -tlnp | grep 9001

# Проверка логов аутентификации
grep "authentication" /var/log/logboard/app.log
```