logboard/docs/installation.md

# Установка и настройка LogBoard+

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

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

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

## Обзор и применение

### 🎯 **Идеально для локальной разработки**

LogBoard+ создан специально для разработчиков, работающих с микросервисной архитектурой. Если вы используете Docker и Docker Compose для локальной разработки, этот инструмент станет незаменимым помощником:

- **Второй монитор** - Держите логи всех микросервисов постоянно видимыми
- **Быстрая отладка** - Мгновенный доступ к логам без переключения между терминалами
- **Мониторинг в реальном времени** - Видите проблемы сразу, как они возникают
- **Централизованный просмотр** - Все логи в одном месте, а не в десятках терминалов

### 🐳 **Оптимизирован для Docker и Docker Compose**

Если ваша инфраструктура основана на Docker и Docker Compose, LogBoard+ предоставляет:

- **Автоматическое обнаружение** всех проектов Docker Compose
- **Быстрый просмотр логов** всех контейнеров в проекте
- **Фильтрация по проектам** - легко переключаться между разными проектами
- **Multi-view режим** - одновременный просмотр логов нескольких контейнеров
- **Интеграция с Docker API** - прямая работа с контейнерами

### 💡 **Сценарии использования**

- **Локальная разработка** - мониторинг логов микросервисов на втором мониторе
- **Отладка проблем** - быстрый поиск ошибок в логах
- **Тестирование** - наблюдение за поведением системы в реальном времени
- **Демонстрации** - показ работы системы клиентам или команде

## Предварительные требования

### Системные требования

- **Операционная система:** Linux (Ubuntu 20.04+, CentOS 8+, RHEL 8+)
- **Docker Engine:** 20.10.0 или выше
- **Docker Compose:** 2.0.0 или выше
- **RAM:** Минимум 1 GB, рекомендуется 2 GB
- **CPU:** Минимум 1 ядро, рекомендуется 2 ядра
- **Дисковое пространство:** Минимум 2 GB свободного места

### Проверка системы

```bash
# Проверка версии Docker
docker --version
# Docker version 20.10.21, build baeda1f

# Проверка версии Docker Compose
docker compose version
# Docker Compose version v2.12.2

# Проверка доступной памяти
free -h
#               total        used        free      shared  buff/cache   available
# Mem:           7.7Gi       2.1Gi       4.2Gi       0.0Ki       1.4Gi       5.3Gi

# Проверка свободного места
df -h /
# Filesystem      Size  Used Avail Use% Mounted on
# /dev/sda1       100G   20G   80G  20% /
```

## Установка

### Метод 1: Клонирование из Git

```bash
# Клонирование репозитория
git clone https://github.com/your-username/logboard.git
cd logboard

# Проверка структуры проекта
ls -la
```

### Метод 2: Скачивание архива

```bash
# Скачивание и распаковка
wget https://github.com/your-username/logboard/archive/refs/tags/v1.0.0.tar.gz
tar -xzf v1.0.0.tar.gz
cd logboard-1.0.0
```

## Настройка

### 1. Создание файла переменных окружения

```bash
# Копирование примера конфигурации
make setup

# Или вручную
cp env.example .env
```

### 2. Редактирование конфигурации

Откройте файл `.env` и настройте основные параметры:

```bash
# Основные настройки
LOGBOARD_PORT=9001
LOGBOARD_USER=admin
LOGBOARD_PASS=your-secure-password

# Безопасность (обязательно измените!)
SECRET_KEY=your-very-secure-secret-key-here
ENCRYPTION_KEY=your-encryption-key-here

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

### 3. Настройка прав доступа к Docker

```bash
# Создание группы docker (если не существует)
sudo groupadd docker

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

# Проверка прав доступа
ls -la /var/run/docker.sock
# srw-rw-rw- 1 root docker 0 Jan 15 10:00 /var/run/docker.sock

# Перезагрузка группы (или перелогин)
newgrp docker
```

### 4. Создание директорий

```bash
# Создание директории для снимков логов
mkdir -p snapshots

# Установка прав доступа
chmod 755 snapshots
```

## Первый запуск

### 1. Сборка Docker образа

```bash
# Сборка образа
make build

# Или вручную
docker compose build --no-cache
```

### 2. Запуск приложения

```bash
# Запуск в фоновом режиме
make up

# Или вручную
docker compose up -d
```

### 3. Проверка статуса

```bash
# Проверка статуса контейнеров
make status

# Просмотр логов
make logs
```

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

### 1. Проверка доступности веб-интерфейса

```bash
# Проверка HTTP ответа
curl -I http://localhost:9001
# HTTP/1.1 200 OK
# Content-Type: text/html; charset=utf-8

# Проверка health check
curl http://localhost:9001/healthz
# ok
```

### 2. Проверка API

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

# Ответ должен содержать access_token
```

### 3. Проверка Docker интеграции

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

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

### 4. Проверка WebSocket соединений

```bash
# Тестирование WebSocket (требует специального клиента)
# Используйте браузер или wscat для тестирования
```

## Настройка для продакшена

### 1. Безопасность

#### Изменение паролей и ключей

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

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

# Обновление .env файла
LOGBOARD_PASS=your-very-secure-password
SECRET_KEY=8a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
ENCRYPTION_KEY=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7
```

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

Создайте файл `nginx.conf`:

```nginx
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/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";
    }
}
```

### 2. Мониторинг

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

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

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

#### Настройка systemd сервиса

Создайте файл `/etc/systemd/system/logboard.service`:

```ini
[Unit]
Description=LogBoard+ Docker Compose
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/path/to/logboard
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target
```

```bash
# Включение автозапуска
sudo systemctl enable logboard.service
sudo systemctl start logboard.service
```

### 3. Резервное копирование

#### Скрипт резервного копирования

Создайте файл `backup.sh`:

```bash
#!/bin/bash
# Скрипт резервного копирования LogBoard+

BACKUP_DIR="/backup/logboard"
DATE=$(date +%Y%m%d_%H%M%S)

# Создание директории для резервных копий
mkdir -p $BACKUP_DIR

# Резервное копирование конфигурации
tar -czf $BACKUP_DIR/logboard_config_$DATE.tar.gz \
  .env \
  excluded_containers.json \
  docker-compose.yml

# Резервное копирование снимков логов
tar -czf $BACKUP_DIR/logboard_snapshots_$DATE.tar.gz \
  snapshots/

# Удаление старых резервных копий (старше 30 дней)
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete

echo "Резервное копирование завершено: $DATE"
```

```bash
# Установка прав на выполнение
chmod +x backup.sh

# Добавление в cron (ежедневно в 2:00)
crontab -e
# 0 2 * * * /path/to/logboard/backup.sh
```

### 4. Обновление

#### Скрипт обновления

Создайте файл `update.sh`:

```bash
#!/bin/bash
# Скрипт обновления LogBoard+

echo "Начинаем обновление LogBoard+..."

# Остановка сервисов
make down

# Получение обновлений
git pull origin main

# Пересборка образов
make build

# Запуск сервисов
make up

# Проверка статуса
make status

echo "Обновление завершено!"
```

```bash
# Установка прав на выполнение
chmod +x update.sh
```

## Устранение проблем установки

### Частые ошибки

1. **Ошибка доступа к Docker socket**
   ```bash
   # Решение: добавление пользователя в группу docker
   sudo usermod -aG docker $USER
   newgrp docker
   ```

2. **Ошибка порта уже используется**
   ```bash
   # Решение: изменение порта в .env
   LOGBOARD_PORT=9002
   ```

3. **Ошибка недостаточно памяти**
   ```bash
   # Решение: увеличение лимитов Docker
   sudo systemctl edit docker
   # Добавьте:
   # [Service]
   # MemoryLimit=2G
   ```

4. **Ошибка SSL сертификатов**
   ```bash
   # Решение: использование самоподписанных сертификатов для тестирования
   openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
     -keyout private.key -out certificate.crt
   ```

### Логи для диагностики

```bash
# Просмотр логов приложения
make logs

# Просмотр логов Docker
docker logs logboard

# Проверка статуса контейнера
docker inspect logboard
```

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

После успешной установки:

1. [Настройте безопасность](./security.md)
2. [Изучите API документацию](./api.md)
3. [Настройте конфигурацию](./configuration.md)
4. [Изучите WebSocket API](./websocket.md)