64403d6fd6
- Реструктуризация: src/ разбит на middleware/, utils/, repositories/ (удалены), routes/ (удалены) - Добавлен src/original-html.ts — полный HTML с reportModal - Добавлен src/index.tsx.backup — React-компонент с reportModal - Миграции переименованы (0001_initial_schema.sql) - Добавлена миграция 0018 (удалена позже) - Docker: multi-stage build, wrangler.toml - Frontend: public/static/app.js + style.css - seed.sql добавлен - Документация: CHANGELOG, CHANGES_v4.1.0-4.1.9, PROJECT_STRUCTURE
630 lines
14 KiB
Markdown
630 lines
14 KiB
Markdown
# 🐳 Docker Guide - AKNAPROFF Tootmine
|
||
|
||
## 📋 Оглавление
|
||
1. [Быстрый старт](#быстрый-старт)
|
||
2. [Структура файлов](#структура-файлов)
|
||
3. [Development режим](#development-режим)
|
||
4. [Production режим](#production-режим)
|
||
5. [База данных](#база-данных)
|
||
6. [Команды Docker](#команды-docker)
|
||
7. [Troubleshooting](#troubleshooting)
|
||
|
||
---
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### Prerequisite
|
||
Установите Docker и Docker Compose:
|
||
- **Docker**: https://docs.docker.com/get-docker/
|
||
- **Docker Compose**: обычно идёт в комплекте с Docker Desktop
|
||
|
||
### Development режим (с локальной БД)
|
||
|
||
```bash
|
||
# 1. Клонировать проект (или быть в папке проекта)
|
||
cd /path/to/webapp
|
||
|
||
# 2. Запустить Docker Compose
|
||
docker-compose up
|
||
|
||
# 3. Открыть браузер
|
||
http://localhost:3000
|
||
```
|
||
|
||
**✅ БД будет храниться в `.wrangler/state/v3/d1/` внутри проекта!**
|
||
|
||
---
|
||
|
||
## 📁 Структура файлов
|
||
|
||
### Созданные Docker файлы:
|
||
|
||
```
|
||
webapp/
|
||
├── docker-compose.yml # Development конфигурация
|
||
├── docker-compose.prod.yml # Production конфигурация
|
||
├── Dockerfile # Production образ
|
||
├── .dockerignore # Исключения для Docker build
|
||
└── DOCKER_GUIDE.md # Эта инструкция
|
||
```
|
||
|
||
### Где хранится БД:
|
||
|
||
#### Development режим (docker-compose.yml):
|
||
```
|
||
./ # Корень проекта
|
||
└── .wrangler/
|
||
└── state/
|
||
└── v3/
|
||
└── d1/
|
||
└── webapp-production.sqlite # ✅ БД здесь!
|
||
```
|
||
|
||
#### Production режим (docker-compose.prod.yml):
|
||
```
|
||
./ # Корень проекта
|
||
└── data/
|
||
└── db/
|
||
└── webapp-production.sqlite # ✅ БД здесь!
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Development режим
|
||
|
||
### Запуск
|
||
|
||
```bash
|
||
# Запустить в foreground (видеть логи)
|
||
docker-compose up
|
||
|
||
# Запустить в background (daemon)
|
||
docker-compose up -d
|
||
|
||
# Посмотреть логи
|
||
docker-compose logs -f
|
||
```
|
||
|
||
### Особенности Development режима:
|
||
|
||
1. **Hot reload**: Изменения в коде сразу видны (bind mount)
|
||
2. **Локальная БД**: Хранится в `.wrangler/state/v3/d1/`
|
||
3. **Автоматический rebuild**: При изменении `package.json`
|
||
4. **Debug режим**: Все логи в консоль
|
||
|
||
### Структура docker-compose.yml:
|
||
|
||
```yaml
|
||
volumes:
|
||
# Весь проект монтируется
|
||
- ./:/app
|
||
# node_modules остаются в контейнере
|
||
- /app/node_modules
|
||
```
|
||
|
||
**Почему это работает:**
|
||
- ✅ Весь проект доступен в контейнере
|
||
- ✅ `.wrangler/` создаётся внутри проекта
|
||
- ✅ БД физически на вашем диске в проекте
|
||
- ✅ Можно бэкапить вместе с проектом
|
||
|
||
### Остановка
|
||
|
||
```bash
|
||
# Остановить контейнеры
|
||
docker-compose down
|
||
|
||
# Остановить и удалить volumes (НЕ УДАЛЯЕТ ЛОКАЛЬНЫЕ ФАЙЛЫ)
|
||
docker-compose down -v
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Production режим
|
||
|
||
### Build и запуск
|
||
|
||
```bash
|
||
# 1. Создать директорию для БД
|
||
mkdir -p data/db data/logs
|
||
|
||
# 2. Build образа
|
||
docker-compose -f docker-compose.prod.yml build
|
||
|
||
# 3. Запуск
|
||
docker-compose -f docker-compose.prod.yml up -d
|
||
|
||
# 4. Проверить логи
|
||
docker-compose -f docker-compose.prod.yml logs -f
|
||
```
|
||
|
||
### Особенности Production режима:
|
||
|
||
1. **Multi-stage build**: Оптимизированный образ
|
||
2. **Non-root user**: Безопасность
|
||
3. **Health checks**: Автоматическая проверка
|
||
4. **Resource limits**: CPU и Memory limits
|
||
5. **Локальная БД**: Хранится в `./data/db/`
|
||
|
||
### Структура docker-compose.prod.yml:
|
||
|
||
```yaml
|
||
volumes:
|
||
# Только БД монтируется локально
|
||
- ./data/db:/app/.wrangler/state/v3/d1
|
||
- ./data/logs:/app/logs
|
||
```
|
||
|
||
**Почему отдельная папка `data/`:**
|
||
- ✅ Чистое разделение данных и кода
|
||
- ✅ Легко бэкапить: `tar -czf backup.tar.gz data/`
|
||
- ✅ Можно смонтировать на отдельный диск
|
||
- ✅ Безопасность: права доступа только к `data/`
|
||
|
||
---
|
||
|
||
## 🗄️ База данных
|
||
|
||
### Где находится БД
|
||
|
||
#### Development:
|
||
```bash
|
||
# Путь к БД
|
||
./webapp/.wrangler/state/v3/d1/webapp-production.sqlite
|
||
|
||
# Посмотреть БД
|
||
sqlite3 .wrangler/state/v3/d1/webapp-production.sqlite
|
||
```
|
||
|
||
#### Production:
|
||
```bash
|
||
# Путь к БД
|
||
./webapp/data/db/webapp-production.sqlite
|
||
|
||
# Посмотреть БД
|
||
sqlite3 data/db/webapp-production.sqlite
|
||
```
|
||
|
||
### Бэкап БД
|
||
|
||
#### Автоматический бэкап (рекомендуется):
|
||
|
||
```bash
|
||
# Создать скрипт backup.sh
|
||
cat > backup.sh << 'EOF'
|
||
#!/bin/bash
|
||
DATE=$(date +%Y%m%d_%H%M%S)
|
||
BACKUP_DIR="./backups"
|
||
mkdir -p $BACKUP_DIR
|
||
|
||
# Development БД
|
||
if [ -f ".wrangler/state/v3/d1/webapp-production.sqlite" ]; then
|
||
cp .wrangler/state/v3/d1/webapp-production.sqlite \
|
||
$BACKUP_DIR/webapp-dev-$DATE.sqlite
|
||
echo "✅ Dev DB backed up: $BACKUP_DIR/webapp-dev-$DATE.sqlite"
|
||
fi
|
||
|
||
# Production БД
|
||
if [ -f "data/db/webapp-production.sqlite" ]; then
|
||
cp data/db/webapp-production.sqlite \
|
||
$BACKUP_DIR/webapp-prod-$DATE.sqlite
|
||
echo "✅ Prod DB backed up: $BACKUP_DIR/webapp-prod-$DATE.sqlite"
|
||
fi
|
||
EOF
|
||
|
||
chmod +x backup.sh
|
||
|
||
# Запустить бэкап
|
||
./backup.sh
|
||
```
|
||
|
||
#### Ручной бэкап:
|
||
|
||
```bash
|
||
# Development
|
||
cp .wrangler/state/v3/d1/webapp-production.sqlite \
|
||
webapp-backup-$(date +%Y%m%d).sqlite
|
||
|
||
# Production
|
||
cp data/db/webapp-production.sqlite \
|
||
webapp-backup-$(date +%Y%m%d).sqlite
|
||
```
|
||
|
||
### Восстановление БД
|
||
|
||
```bash
|
||
# Development
|
||
cp webapp-backup-20251128.sqlite \
|
||
.wrangler/state/v3/d1/webapp-production.sqlite
|
||
|
||
# Production
|
||
cp webapp-backup-20251128.sqlite \
|
||
data/db/webapp-production.sqlite
|
||
|
||
# Перезапустить контейнер
|
||
docker-compose restart # Development
|
||
docker-compose -f docker-compose.prod.yml restart # Production
|
||
```
|
||
|
||
### Сброс БД
|
||
|
||
```bash
|
||
# Зайти в контейнер
|
||
docker-compose exec webapp sh
|
||
|
||
# Внутри контейнера
|
||
npm run db:reset
|
||
|
||
# Или снаружи
|
||
docker-compose exec webapp npm run db:reset
|
||
```
|
||
|
||
### Миграции
|
||
|
||
```bash
|
||
# Применить миграции
|
||
docker-compose exec webapp npm run db:migrate:local
|
||
|
||
# Залить seed данные
|
||
docker-compose exec webapp npm run db:seed
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Команды Docker
|
||
|
||
### Базовые команды
|
||
|
||
```bash
|
||
# Запустить
|
||
docker-compose up
|
||
|
||
# Запустить в background
|
||
docker-compose up -d
|
||
|
||
# Остановить
|
||
docker-compose down
|
||
|
||
# Остановить и удалить volumes
|
||
docker-compose down -v
|
||
|
||
# Перезапустить
|
||
docker-compose restart
|
||
|
||
# Посмотреть логи
|
||
docker-compose logs -f
|
||
|
||
# Посмотреть логи конкретного сервиса
|
||
docker-compose logs -f webapp
|
||
```
|
||
|
||
### Управление контейнерами
|
||
|
||
```bash
|
||
# Список контейнеров
|
||
docker-compose ps
|
||
|
||
# Зайти в контейнер
|
||
docker-compose exec webapp sh
|
||
|
||
# Выполнить команду в контейнере
|
||
docker-compose exec webapp npm run build
|
||
|
||
# Посмотреть использование ресурсов
|
||
docker stats aknaproff-webapp
|
||
```
|
||
|
||
### Build и образы
|
||
|
||
```bash
|
||
# Build заново
|
||
docker-compose build
|
||
|
||
# Build без кэша
|
||
docker-compose build --no-cache
|
||
|
||
# Посмотреть образы
|
||
docker images | grep webapp
|
||
|
||
# Удалить неиспользуемые образы
|
||
docker image prune -a
|
||
```
|
||
|
||
### Logs и debugging
|
||
|
||
```bash
|
||
# Все логи
|
||
docker-compose logs
|
||
|
||
# Последние 100 строк
|
||
docker-compose logs --tail=100
|
||
|
||
# Follow (live)
|
||
docker-compose logs -f
|
||
|
||
# Только ошибки
|
||
docker-compose logs | grep ERROR
|
||
|
||
# Экспорт логов в файл
|
||
docker-compose logs > webapp-logs.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 Troubleshooting
|
||
|
||
### Проблема: Контейнер не запускается
|
||
|
||
**Симптомы:**
|
||
```
|
||
Error: Cannot find module 'hono'
|
||
```
|
||
|
||
**Решение:**
|
||
```bash
|
||
# Удалить node_modules и пересобрать
|
||
docker-compose down -v
|
||
docker-compose build --no-cache
|
||
docker-compose up
|
||
```
|
||
|
||
---
|
||
|
||
### Проблема: Порт 3000 занят
|
||
|
||
**Симптомы:**
|
||
```
|
||
Error: bind: address already in use
|
||
```
|
||
|
||
**Решение 1: Убить процесс на порту 3000**
|
||
```bash
|
||
# Linux/Mac
|
||
lsof -ti:3000 | xargs kill -9
|
||
|
||
# Или
|
||
fuser -k 3000/tcp
|
||
```
|
||
|
||
**Решение 2: Изменить порт в docker-compose.yml**
|
||
```yaml
|
||
ports:
|
||
- "3001:3000" # Host:Container
|
||
```
|
||
|
||
---
|
||
|
||
### Проблема: БД не создаётся
|
||
|
||
**Симптомы:**
|
||
```
|
||
Error: no such table: users
|
||
```
|
||
|
||
**Решение:**
|
||
```bash
|
||
# Зайти в контейнер
|
||
docker-compose exec webapp sh
|
||
|
||
# Сбросить БД
|
||
npm run db:reset
|
||
|
||
# Выйти
|
||
exit
|
||
```
|
||
|
||
---
|
||
|
||
### Проблема: БД пропала после перезапуска
|
||
|
||
**Причина:** Использовали `docker-compose down -v` (удаляет volumes)
|
||
|
||
**Решение:**
|
||
```bash
|
||
# НЕ используйте -v если нужно сохранить данные
|
||
docker-compose down # ✅ Правильно
|
||
|
||
# Используйте -v только для полной очистки
|
||
docker-compose down -v # ❌ Удалит volumes
|
||
```
|
||
|
||
**Но в нашем случае:**
|
||
- ✅ БД хранится в `./` или `./data/` (bind mount)
|
||
- ✅ `docker-compose down -v` НЕ удалит файлы на хосте
|
||
- ✅ Безопасно использовать `-v`
|
||
|
||
---
|
||
|
||
### Проблема: Изменения в коде не видны
|
||
|
||
**Development режим:**
|
||
```bash
|
||
# Проверить bind mount
|
||
docker-compose exec webapp ls -la /app
|
||
|
||
# Если bind mount не работает, перезапустить
|
||
docker-compose down
|
||
docker-compose up
|
||
```
|
||
|
||
**Production режим:**
|
||
```bash
|
||
# Production требует rebuild
|
||
docker-compose -f docker-compose.prod.yml build
|
||
docker-compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
---
|
||
|
||
### Проблема: Недостаточно памяти
|
||
|
||
**Симптомы:**
|
||
```
|
||
JavaScript heap out of memory
|
||
```
|
||
|
||
**Решение: Увеличить memory limit**
|
||
```yaml
|
||
# docker-compose.prod.yml
|
||
deploy:
|
||
resources:
|
||
limits:
|
||
memory: 1G # Было 512M
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Мониторинг
|
||
|
||
### Использование ресурсов
|
||
|
||
```bash
|
||
# Real-time статистика
|
||
docker stats aknaproff-webapp
|
||
|
||
# Вывод:
|
||
# CONTAINER CPU % MEM USAGE / LIMIT MEM %
|
||
# aknaproff... 0.5% 120MB / 512MB 23%
|
||
```
|
||
|
||
### Health checks
|
||
|
||
```bash
|
||
# Проверить health status
|
||
docker-compose ps
|
||
|
||
# Вывод:
|
||
# NAME STATUS
|
||
# aknaproff-webapp Up (healthy)
|
||
```
|
||
|
||
### Логи приложения
|
||
|
||
```bash
|
||
# Live логи
|
||
docker-compose logs -f webapp
|
||
|
||
# Ошибки
|
||
docker-compose logs webapp | grep ERROR
|
||
|
||
# Экспорт в файл
|
||
docker-compose logs webapp > logs.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 Best Practices
|
||
|
||
### 1. Регулярные бэкапы
|
||
|
||
```bash
|
||
# Добавить в cron (каждый день в 3:00)
|
||
0 3 * * * cd /path/to/webapp && ./backup.sh
|
||
```
|
||
|
||
### 2. Мониторинг дискового пространства
|
||
|
||
```bash
|
||
# Проверить размер БД
|
||
du -sh .wrangler/state/v3/d1/
|
||
du -sh data/db/
|
||
|
||
# Проверить свободное место
|
||
df -h
|
||
```
|
||
|
||
### 3. Обновление образов
|
||
|
||
```bash
|
||
# Обновить base образы
|
||
docker-compose pull
|
||
|
||
# Rebuild с новыми образами
|
||
docker-compose build --no-cache
|
||
docker-compose up -d
|
||
```
|
||
|
||
### 4. Безопасность
|
||
|
||
```bash
|
||
# Использовать .env для секретов
|
||
echo "CLOUDFLARE_API_TOKEN=your_token" > .env
|
||
|
||
# Добавить в .gitignore
|
||
echo ".env" >> .gitignore
|
||
|
||
# В docker-compose.yml
|
||
env_file:
|
||
- .env
|
||
```
|
||
|
||
### 5. Логирование
|
||
|
||
```bash
|
||
# Ротация логов (добавить в docker-compose.yml)
|
||
logging:
|
||
driver: "json-file"
|
||
options:
|
||
max-size: "10m"
|
||
max-file: "3"
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 Полезные ссылки
|
||
|
||
- **Docker Docs**: https://docs.docker.com/
|
||
- **Docker Compose**: https://docs.docker.com/compose/
|
||
- **Cloudflare Workers**: https://developers.cloudflare.com/workers/
|
||
- **Wrangler CLI**: https://developers.cloudflare.com/workers/wrangler/
|
||
- **Hono Framework**: https://hono.dev/
|
||
|
||
---
|
||
|
||
## ✅ Проверочный чек-лист
|
||
|
||
### Development:
|
||
- [ ] `docker-compose up` запускается без ошибок
|
||
- [ ] Приложение доступно на http://localhost:3000
|
||
- [ ] БД создалась в `.wrangler/state/v3/d1/`
|
||
- [ ] Демо-данные загрузились (5 записей за январь 2025)
|
||
- [ ] Hot reload работает (изменения видны)
|
||
- [ ] Health check: `docker-compose ps` → `(healthy)`
|
||
|
||
### Production:
|
||
- [ ] `docker-compose -f docker-compose.prod.yml build` успешно
|
||
- [ ] `docker-compose -f docker-compose.prod.yml up -d` запустился
|
||
- [ ] Приложение доступно на http://localhost:3000
|
||
- [ ] БД создалась в `./data/db/`
|
||
- [ ] Демо-данные загрузились
|
||
- [ ] Health check: `(healthy)`
|
||
- [ ] Бэкап работает: `./backup.sh`
|
||
|
||
---
|
||
|
||
## 🎉 Готово!
|
||
|
||
**AKNAPROFF Tootmine теперь работает в Docker с локальной БД!**
|
||
|
||
**Production URL (Docker):**
|
||
http://localhost:3000
|
||
|
||
**Demo Accounts:**
|
||
- `admin` / `demo123`
|
||
- `aknaproff` / `demo123`
|
||
- **Public User** (без логина)
|
||
|
||
**База данных:**
|
||
- **Development**: `.wrangler/state/v3/d1/webapp-production.sqlite`
|
||
- **Production**: `./data/db/webapp-production.sqlite`
|
||
|
||
**Бэкап:**
|
||
```bash
|
||
./backup.sh
|
||
```
|
||
|
||
---
|
||
|
||
*Создано: 28.11.2025*
|
||
*Версия проекта: v4.0.13*
|