Aknaproff/DOCKER_GUIDE.md

🐳 Docker Guide - AKNAPROFF Tootmine

📋 Оглавление

1. Быстрый старт
2. Структура файлов
3. Development режим
4. Production режим
5. База данных
6. Команды Docker
7. Troubleshooting

---

🚀 Быстрый старт

Prerequisite

Установите Docker и Docker Compose:

• Docker: https://docs.docker.com/get-docker/
• Docker Compose: обычно идёт в комплекте с Docker Desktop

Development режим (с локальной БД)

# 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 режим

Запуск

# Запустить в 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:

volumes:
  # Весь проект монтируется
  - ./:/app
  # node_modules остаются в контейнере
  - /app/node_modules

Почему это работает:

• ✅ Весь проект доступен в контейнере
• ✅ .wrangler/ создаётся внутри проекта
• ✅ БД физически на вашем диске в проекте
• ✅ Можно бэкапить вместе с проектом

Остановка

# Остановить контейнеры
docker-compose down

# Остановить и удалить volumes (НЕ УДАЛЯЕТ ЛОКАЛЬНЫЕ ФАЙЛЫ)
docker-compose down -v

---

🚀 Production режим

Build и запуск

# 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:

volumes:
  # Только БД монтируется локально
  - ./data/db:/app/.wrangler/state/v3/d1
  - ./data/logs:/app/logs

Почему отдельная папка data/:

• ✅ Чистое разделение данных и кода
• ✅ Легко бэкапить: tar -czf backup.tar.gz data/
• ✅ Можно смонтировать на отдельный диск
• ✅ Безопасность: права доступа только к data/

---

🗄️ База данных

Где находится БД

Development:

# Путь к БД
./webapp/.wrangler/state/v3/d1/webapp-production.sqlite

# Посмотреть БД
sqlite3 .wrangler/state/v3/d1/webapp-production.sqlite

Production:

# Путь к БД
./webapp/data/db/webapp-production.sqlite

# Посмотреть БД
sqlite3 data/db/webapp-production.sqlite

Бэкап БД

Автоматический бэкап (рекомендуется):

# Создать скрипт 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

Ручной бэкап:

# 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

Восстановление БД

# 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

Сброс БД

# Зайти в контейнер
docker-compose exec webapp sh

# Внутри контейнера
npm run db:reset

# Или снаружи
docker-compose exec webapp npm run db:reset

Миграции

# Применить миграции
docker-compose exec webapp npm run db:migrate:local

# Залить seed данные
docker-compose exec webapp npm run db:seed

---

📦 Команды Docker

Базовые команды

# Запустить
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

Управление контейнерами

# Список контейнеров
docker-compose ps

# Зайти в контейнер
docker-compose exec webapp sh

# Выполнить команду в контейнере
docker-compose exec webapp npm run build

# Посмотреть использование ресурсов
docker stats aknaproff-webapp

Build и образы

# Build заново
docker-compose build

# Build без кэша
docker-compose build --no-cache

# Посмотреть образы
docker images | grep webapp

# Удалить неиспользуемые образы
docker image prune -a

Logs и debugging

# Все логи
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'

Решение:

# Удалить node_modules и пересобрать
docker-compose down -v
docker-compose build --no-cache
docker-compose up

---

Проблема: Порт 3000 занят

Симптомы:

Error: bind: address already in use

Решение 1: Убить процесс на порту 3000

# Linux/Mac
lsof -ti:3000 | xargs kill -9

# Или
fuser -k 3000/tcp

Решение 2: Изменить порт в docker-compose.yml

ports:
  - "3001:3000"  # Host:Container

---

Проблема: БД не создаётся

Симптомы:

Error: no such table: users

Решение:

# Зайти в контейнер
docker-compose exec webapp sh

# Сбросить БД
npm run db:reset

# Выйти
exit

---

Проблема: БД пропала после перезапуска

Причина: Использовали docker-compose down -v (удаляет volumes)

Решение:

# НЕ используйте -v если нужно сохранить данные
docker-compose down  # ✅ Правильно

# Используйте -v только для полной очистки
docker-compose down -v  # ❌ Удалит volumes

Но в нашем случае:

• ✅ БД хранится в ./ или ./data/ (bind mount)
• ✅ docker-compose down -v НЕ удалит файлы на хосте
• ✅ Безопасно использовать -v

---

Проблема: Изменения в коде не видны

Development режим:

# Проверить bind mount
docker-compose exec webapp ls -la /app

# Если bind mount не работает, перезапустить
docker-compose down
docker-compose up

Production режим:

# 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

# docker-compose.prod.yml
deploy:
  resources:
    limits:
      memory: 1G  # Было 512M

---

📊 Мониторинг

Использование ресурсов

# Real-time статистика
docker stats aknaproff-webapp

# Вывод:
# CONTAINER      CPU %   MEM USAGE / LIMIT   MEM %
# aknaproff...   0.5%    120MB / 512MB       23%

Health checks

# Проверить health status
docker-compose ps

# Вывод:
# NAME              STATUS
# aknaproff-webapp  Up (healthy)

Логи приложения

# Live логи
docker-compose logs -f webapp

# Ошибки
docker-compose logs webapp | grep ERROR

# Экспорт в файл
docker-compose logs webapp > logs.txt

---

🎯 Best Practices

1. Регулярные бэкапы

# Добавить в cron (каждый день в 3:00)
0 3 * * * cd /path/to/webapp && ./backup.sh

2. Мониторинг дискового пространства

# Проверить размер БД
du -sh .wrangler/state/v3/d1/
du -sh data/db/

# Проверить свободное место
df -h

3. Обновление образов

# Обновить base образы
docker-compose pull

# Rebuild с новыми образами
docker-compose build --no-cache
docker-compose up -d

4. Безопасность

# Использовать .env для секретов
echo "CLOUDFLARE_API_TOKEN=your_token" > .env

# Добавить в .gitignore
echo ".env" >> .gitignore

# В docker-compose.yml
env_file:
  - .env

5. Логирование

# Ротация логов (добавить в 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

Бэкап:

./backup.sh

---

Создано: 28.11.2025
Версия проекта: v4.0.13