Initial commit
This commit is contained in:
poignatov
297
ENV_SETUP.md
Normal file
297
ENV_SETUP.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# Настройка единого .env файла
|
||||
|
||||
Все приложения проекта используют единый файл `.env` в корне проекта.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
1. Скопируйте файл `.env.example` в `.env`:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. Отредактируйте `.env` и укажите свои значения:
|
||||
```bash
|
||||
nano .env
|
||||
# или
|
||||
vim .env
|
||||
```
|
||||
|
||||
3. **ВАЖНО**: Файл `.env` уже добавлен в `.gitignore` и не будет попадать в git.
|
||||
|
||||
## Структура переменных окружения
|
||||
|
||||
### Database Configuration
|
||||
- `DB_HOST` - хост базы данных (по умолчанию: localhost)
|
||||
- `DB_PORT` - порт базы данных (по умолчанию: 5432)
|
||||
- `DB_USER` - пользователь БД (по умолчанию: playeng)
|
||||
- `DB_PASSWORD` - пароль БД (по умолчанию: playeng)
|
||||
- `DB_NAME` - имя БД (по умолчанию: playeng)
|
||||
|
||||
### Backend Server Configuration
|
||||
- `PORT` - порт бэкенд сервера (по умолчанию: 8080)
|
||||
- В production всегда используется порт 8080 внутри контейнера
|
||||
- Nginx автоматически проксирует запросы к `http://backend:8080`
|
||||
|
||||
### Frontend Configuration (play-life-web)
|
||||
- `VITE_PORT` - порт для dev-сервера Vite (по умолчанию: 3000)
|
||||
- `WEB_PORT` - порт для production контейнера (по умолчанию: 3001)
|
||||
|
||||
**Примечание:** API запросы автоматически проксируются к бэкенду. В development режиме Vite проксирует запросы к `http://localhost:8080`. В production nginx проксирует запросы к бэкенд контейнеру. Не требуется настройка `VITE_API_BASE_URL`.
|
||||
|
||||
### Telegram Bot Configuration (опционально)
|
||||
- `TELEGRAM_BOT_TOKEN` - токен бота от @BotFather
|
||||
- `TELEGRAM_CHAT_ID` - ID чата для отправки сообщений
|
||||
- `TELEGRAM_WEBHOOK_BASE_URL` - базовый URL для автоматической настройки webhook. Webhook будет настроен автоматически при старте сервера на `<TELEGRAM_WEBHOOK_BASE_URL>/webhook/telegram`. Если не указан, webhook нужно настраивать вручную.
|
||||
|
||||
**Примеры значений:**
|
||||
- Production с HTTPS: `https://your-domain.com` (порт не нужен для стандартных 80/443)
|
||||
- Локальная разработка с ngrok: `https://abc123.ngrok.io` (порт не нужен)
|
||||
- Прямой доступ на нестандартном порту: `http://your-server:8080` (порт обязателен)
|
||||
|
||||
### Todoist Webhook Configuration (опционально)
|
||||
- `TODOIST_WEBHOOK_SECRET` - секрет для проверки подлинности webhook от Todoist (если задан, все запросы должны содержать заголовок `X-Todoist-Webhook-Secret` с этим значением)
|
||||
|
||||
## Настройка интеграции с Todoist
|
||||
|
||||
Интеграция с Todoist позволяет автоматически обрабатывать закрытые задачи и добавлять их в базу данных play-life.
|
||||
|
||||
### Как это работает
|
||||
|
||||
1. При закрытии задачи в Todoist отправляется webhook на ваш сервер
|
||||
2. Сервер извлекает `title` (content) и `description` из закрытой задачи
|
||||
3. Склеивает их в один текст: `title + "\n" + description`
|
||||
4. Обрабатывает текст через существующую логику `processMessage`, которая:
|
||||
- Парсит ноды в формате `**[Project][+/-][Score]**`
|
||||
- Сохраняет данные в базу данных
|
||||
- Отправляет уведомление в Telegram (если настроено)
|
||||
|
||||
### Настройка webhook в Todoist
|
||||
|
||||
1. Откройте настройки Todoist: https://todoist.com/app/settings/integrations
|
||||
2. Перейдите в раздел "Webhooks" или "Integrations"
|
||||
3. Создайте новый webhook:
|
||||
- **URL**: `http://your-server:8080/webhook/todoist`
|
||||
- Для локальной разработки: `http://localhost:8080/webhook/todoist`
|
||||
- Для production: укажите публичный URL вашего сервера
|
||||
- **Event**: выберите `item:completed` (закрытие задачи)
|
||||
4. Сохраните webhook
|
||||
|
||||
### Безопасность (опционально)
|
||||
|
||||
Для защиты webhook от несанкционированного доступа:
|
||||
|
||||
1. Установите секрет в `.env`:
|
||||
```bash
|
||||
TODOIST_WEBHOOK_SECRET=your_secret_key_here
|
||||
```
|
||||
|
||||
2. Настройте Todoist для отправки секрета в заголовке:
|
||||
- В настройках webhook добавьте заголовок: `X-Todoist-Webhook-Secret: your_secret_key_here`
|
||||
- Или используйте встроенные механизмы безопасности Todoist, если они доступны
|
||||
|
||||
**Примечание**: Если `TODOIST_WEBHOOK_SECRET` не задан, проверка секрета не выполняется.
|
||||
|
||||
### Формат задач в Todoist
|
||||
|
||||
Для корректной обработки задачи должны содержать ноды в формате:
|
||||
```
|
||||
**[ProjectName][+/-][Score]**
|
||||
```
|
||||
|
||||
Примеры:
|
||||
- `**[Work]+5.5**` - добавить 5.5 баллов к проекту "Work"
|
||||
- `**[Health]-2.0**` - вычесть 2.0 баллов из проекта "Health"
|
||||
|
||||
Ноды можно размещать как в `title` (content), так и в `description` задачи. Они будут обработаны при закрытии задачи.
|
||||
|
||||
### Тестирование
|
||||
|
||||
Для тестирования интеграции:
|
||||
|
||||
1. Создайте задачу в Todoist с нодами, например:
|
||||
- Title: `Test task`
|
||||
- Description: `**[TestProject]+10.0**`
|
||||
|
||||
2. Закройте задачу в Todoist
|
||||
|
||||
3. Проверьте логи сервера - должно появиться сообщение:
|
||||
```
|
||||
Processing Todoist task: title='Test task', description='**[TestProject]+10.0**'
|
||||
Successfully processed Todoist task, found 1 nodes
|
||||
```
|
||||
|
||||
4. Проверьте базу данных или веб-интерфейс - данные должны быть добавлены
|
||||
|
||||
|
||||
## Использование
|
||||
|
||||
### Локальная разработка
|
||||
|
||||
Все приложения автоматически читают переменные из корневого `.env` файла:
|
||||
|
||||
- **play-life-backend**: читает из `../.env` и `.env` (локальный имеет приоритет)
|
||||
- **play-life-web**: читает из `../.env` и `.env` (локальный имеет приоритет)
|
||||
|
||||
### Docker Compose
|
||||
|
||||
Для запуска всех приложений в одном образе используйте корневой `docker-compose.yml`:
|
||||
|
||||
```bash
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
Все сервисы автоматически загружают переменные из корневого `.env` файла.
|
||||
|
||||
### Отдельные приложения
|
||||
|
||||
Если нужно запустить отдельные приложения, они также будут использовать корневой `.env`:
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd play-life-backend
|
||||
docker-compose up
|
||||
|
||||
# Frontend
|
||||
cd play-life-web
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
## Приоритет переменных окружения
|
||||
|
||||
1. Переменные окружения системы (высший приоритет)
|
||||
2. Локальный `.env` в директории приложения
|
||||
3. Корневой `.env` файл
|
||||
4. Значения по умолчанию в коде
|
||||
|
||||
## Примеры использования
|
||||
|
||||
### Изменение порта базы данных
|
||||
|
||||
```bash
|
||||
# В .env
|
||||
DB_PORT=5433
|
||||
```
|
||||
|
||||
### Изменение порта бэкенда
|
||||
|
||||
```bash
|
||||
# В .env
|
||||
PORT=9090
|
||||
```
|
||||
|
||||
### Изменение порта фронтенда
|
||||
|
||||
```bash
|
||||
# В .env
|
||||
VITE_PORT=4000 # для development
|
||||
WEB_PORT=4001 # для production Docker контейнера
|
||||
```
|
||||
|
||||
После изменения `.env` файла перезапустите соответствующие сервисы.
|
||||
|
||||
## Настройка интеграции с Telegram (webhook для сообщений пользователя)
|
||||
|
||||
Интеграция с Telegram позволяет автоматически обрабатывать сообщения, отправленные пользователем в чат бота, и добавлять их в базу данных play-life.
|
||||
|
||||
### Как это работает
|
||||
|
||||
1. Пользователь отправляет сообщение в чат с ботом в Telegram
|
||||
2. Telegram отправляет webhook на ваш сервер с информацией о сообщении и entities (форматирование)
|
||||
3. Сервер извлекает жирный текст из entities (type === 'bold')
|
||||
4. Парсит жирный текст по формату `project+/-score` (без `**`)
|
||||
5. Обрабатывает текст и сохраняет данные в базу данных
|
||||
6. **НЕ отправляет сообщение обратно в Telegram** (в отличие от других интеграций)
|
||||
|
||||
### Отличия от других интеграций
|
||||
|
||||
- **Формат нод**: `project+/-score` (без `**`), например: `Work+5.5` или `Health-2.0`
|
||||
- **Определение жирного текста**: через entities от Telegram, а не через markdown `**`
|
||||
- **Без обратной отправки**: сообщение не отправляется обратно в Telegram
|
||||
|
||||
### Настройка webhook в Telegram
|
||||
|
||||
#### Автоматическая настройка (рекомендуется)
|
||||
|
||||
1. Создайте бота через [@BotFather](https://t.me/botfather) в Telegram
|
||||
2. Получите токен бота и добавьте его в `.env`:
|
||||
```bash
|
||||
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
||||
TELEGRAM_CHAT_ID=123456789
|
||||
TELEGRAM_WEBHOOK_BASE_URL=https://your-domain.com
|
||||
```
|
||||
|
||||
**Важно о портах:**
|
||||
- Если сервер доступен на стандартных портах (HTTP 80 или HTTPS 443), порт можно не указывать
|
||||
- Если сервер работает на нестандартном порту и доступен напрямую, укажите порт: `http://your-server:8080`
|
||||
- Если используется reverse proxy (nginx, etc.), указывайте внешний URL без порта: `https://your-domain.com`
|
||||
|
||||
3. Запустите сервер - webhook будет настроен автоматически при старте!
|
||||
|
||||
Для локальной разработки можно использовать ngrok или аналогичный сервис:
|
||||
```bash
|
||||
# Установите ngrok: https://ngrok.com/
|
||||
ngrok http 8080
|
||||
# Используйте полученный URL в TELEGRAM_WEBHOOK_BASE_URL (без порта)
|
||||
# Например: TELEGRAM_WEBHOOK_BASE_URL=https://abc123.ngrok.io
|
||||
```
|
||||
|
||||
4. Проверьте логи сервера - должно появиться сообщение:
|
||||
```
|
||||
Telegram webhook configured successfully: https://abc123.ngrok.io/webhook/telegram
|
||||
```
|
||||
|
||||
#### Ручная настройка (если не указан TELEGRAM_WEBHOOK_BASE_URL)
|
||||
|
||||
Если вы не указали `TELEGRAM_WEBHOOK_BASE_URL`, webhook нужно настроить вручную:
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"url": "http://your-server:8080/webhook/telegram"
|
||||
}'
|
||||
```
|
||||
|
||||
Проверьте, что webhook установлен:
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"
|
||||
```
|
||||
|
||||
### Формат сообщений в Telegram
|
||||
|
||||
Для корректной обработки сообщения должны содержать жирный текст в формате:
|
||||
```
|
||||
project+/-score
|
||||
```
|
||||
|
||||
Примеры:
|
||||
- `Work+5.5` (жирным) - добавить 5.5 баллов к проекту "Work"
|
||||
- `Health-2.0` (жирным) - вычесть 2.0 баллов из проекта "Health"
|
||||
|
||||
**Важно**: Текст должен быть выделен жирным шрифтом в Telegram (через форматирование сообщения, не через `**`).
|
||||
|
||||
### Тестирование
|
||||
|
||||
Для тестирования интеграции:
|
||||
|
||||
1. Откройте чат с вашим ботом в Telegram
|
||||
2. Отправьте сообщение с жирным текстом в формате `project+/-score`, например:
|
||||
- Напишите: `Test message`
|
||||
- Выделите `Work+10.0` жирным шрифтом (через форматирование)
|
||||
- Отправьте сообщение
|
||||
|
||||
3. Проверьте логи сервера - должно появиться сообщение:
|
||||
```
|
||||
Processing Telegram message: text='Test message', entities count=1
|
||||
Successfully processed Telegram message, found 1 nodes
|
||||
```
|
||||
|
||||
4. Проверьте базу данных или веб-интерфейс - данные должны быть добавлены
|
||||
|
||||
### Примечания
|
||||
|
||||
- Webhook должен быть доступен из интернета (для production используйте публичный URL)
|
||||
- Для локальной разработки используйте ngrok или аналогичный сервис для туннелирования
|
||||
- Сообщения обрабатываются только если содержат жирный текст в правильном формате
|
||||
- Сообщения **не отправляются обратно** в Telegram (в отличие от других интеграций)
|
||||
|
||||
Reference in New Issue
Block a user