Добавлена полная документация проекта LogBoard+

- Создан основной README.md с описанием проекта - Добавлена подробная документация в папке docs/ - Создан файл LICENSE (MIT) - Обновлен .gitignore - Добавлена документация по безопасности с генерацией ключей - Включены примеры конфигураций и устранение неполадок Автор: Сергей Антропов Сайт: https://devops.org.ru
2025-08-19 01:06:23 +03:00
parent 86a2c44333
commit 5c8efe2644
11 changed files with 4932 additions and 90 deletions
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -0,0 +1,430 @@
+# Установка и настройка LogBoard+
+
+**Автор:** Сергей Антропов  
+**Сайт:** https://devops.org.ru
+
+## Содержание
+
+1. [Предварительные требования](#предварительные-требования)
+2. [Установка](#установка)
+3. [Настройка](#настройка)
+4. [Первый запуск](#первый-запуск)
+5. [Проверка установки](#проверка-установки)
+6. [Настройка для продакшена](#настройка-для-продакшена)
+
+## Предварительные требования
+
+### Системные требования
+
+- **Операционная система:** 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)
+