mybeacon-backend/STARTUP.md

MyBeacon - Quick Start Guide

🚀 Запуск всего проекта

Самый простой способ (оба сервиса сразу)

# Development режим (frontend интерактивный)
./start-all.sh dev

# Background режим (всё в фоне)
./start-all.sh background

# Посмотреть логи
./start-all.sh logs

# Остановить всё
./start-all.sh stop

# Статус
./start-all.sh status

---

🔧 Запуск по отдельности

Backend

cd backend

# Development с auto-reload
./start.sh dev

# Production (4 воркера)
./start.sh prod

# В фоне
./start.sh background

# Остановить
./start.sh stop

# Статус
./start.sh status

Кастомизация:

# Другой порт
PORT=8001 ./start.sh dev

# Другой хост
HOST=127.0.0.1 PORT=9000 ./start.sh background

# Debug логи
LOG_LEVEL=debug ./start.sh dev

Логи:

• Dev: /tmp/backend_dev.log
• Background: /tmp/backend_live.log
• Production: /var/log/mybeacon/backend.log

---

Frontend

cd frontend

# Development server
./start.sh dev

# В фоне
./start.sh background

# Build production
./start.sh build

# Preview production build
./start.sh preview

# Остановить
./start.sh stop

# Очистить кеш
./start.sh clean

# Установить/обновить зависимости
./start.sh install

Кастомизация:

# Другой порт
PORT=3000 ./start.sh dev

# Другой хост
HOST=192.168.5.4 PORT=5173 ./start.sh dev

Логи:

• Background: /tmp/frontend_dev.log

---

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

1. Установка зависимостей

Backend:

cd backend
poetry install

Frontend:

cd frontend
npm install

2. Настройка окружения

Создай .env файл в backend/:

cd backend
cp .env.example .env
# Отредактируй .env если нужно

3. Запуск баз данных

PostgreSQL:

sudo systemctl start postgresql
sudo systemctl enable postgresql

# Создать БД
sudo -u postgres psql
CREATE USER mybeacon WITH PASSWORD 'mybeacon';
CREATE DATABASE mybeacon OWNER mybeacon;
\q

ClickHouse:

sudo systemctl start clickhouse-server
sudo systemctl enable clickhouse-server

# Создать БД
clickhouse-client -q "CREATE DATABASE IF NOT EXISTS mybeacon"

Redis:

sudo systemctl start redis
sudo systemctl enable redis

4. Миграции

cd backend
poetry run alembic upgrade head

5. Создать superadmin

cd backend
poetry run python3 -c "
from app.core.database import async_session_maker
from app.models.user import User
from app.core.security import get_password_hash
from datetime import datetime, timezone
import asyncio

async def create_superadmin():
    async with async_session_maker() as db:
        admin = User(
            email='superadmin@mybeacon.com',
            hashed_password=get_password_hash('superadmin123'),
            full_name='Super Admin',
            role='superadmin',
            status='active',
            email_verified=True,
            created_at=datetime.now(timezone.utc)
        )
        db.add(admin)
        await db.commit()
        print('✅ Superadmin created: superadmin@mybeacon.com / superadmin123')

asyncio.run(create_superadmin())
"

6. Запуск!

# Из корня проекта
./start-all.sh dev

---

🌐 URL-адреса

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

📊 Мониторинг

Проверка статуса

# Все сервисы
./start-all.sh status

# Backend отдельно
cd backend && ./start.sh status

# Frontend отдельно
cd frontend && ./start.sh status

Логи

# Все логи сразу
./start-all.sh logs

# Backend
tail -f /tmp/backend_live.log

# Frontend
tail -f /tmp/frontend_dev.log

Процессы

# Backend
ps aux | grep uvicorn

# Frontend
ps aux | grep vite

---

🛠️ Команды разработчика

Backend

cd backend

# Форматирование кода
poetry run black app/

# Проверка кода
poetry run ruff app/

# Тесты
poetry run pytest

# Новая миграция
poetry run alembic revision --autogenerate -m "description"

# Применить миграции
poetry run alembic upgrade head

# Откатить миграцию
poetry run alembic downgrade -1

Frontend

cd frontend

# Линтинг
npm run lint

# Форматирование
npm run format

# Проверка типов
npm run type-check

# Build
npm run build

# Preview build
npm run preview

---

🐛 Troubleshooting

Backend не стартует

# Проверь .env
cat backend/.env

# Проверь БД подключение
cd backend
poetry run python3 -c "from app.core.database import engine; print('OK')"

# Проверь порт 8000
sudo netstat -tlnp | grep 8000

# Убей старые процессы
pkill -f uvicorn

Frontend не стартует

# Проверь node_modules
cd frontend
ls node_modules/ | wc -l  # Должно быть > 0

# Переустанови
rm -rf node_modules package-lock.json
npm install

# Проверь порт 5173
sudo netstat -tlnp | grep 5173

# Убей старые процессы
pkill -f vite

Очистка всего

# Останови всё
./start-all.sh stop

# Очисти кеши
cd backend
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null
find . -type f -name "*.pyc" -delete 2>/dev/null

cd ../frontend
rm -rf node_modules/.vite dist

---

📝 Полезные алиасы

Добавь в ~/.bashrc или ~/.zshrc:

# MyBeacon
alias mb-start='cd ~/work/luckfox/alpine/mybeacon-backend && ./start-all.sh background'
alias mb-stop='cd ~/work/luckfox/alpine/mybeacon-backend && ./start-all.sh stop'
alias mb-logs='cd ~/work/luckfox/alpine/mybeacon-backend && ./start-all.sh logs'
alias mb-status='cd ~/work/luckfox/alpine/mybeacon-backend && ./start-all.sh status'

# Backend
alias mb-be='cd ~/work/luckfox/alpine/mybeacon-backend/backend'
alias mb-be-logs='tail -f /tmp/backend_live.log'

# Frontend
alias mb-fe='cd ~/work/luckfox/alpine/mybeacon-backend/frontend'
alias mb-fe-logs='tail -f /tmp/frontend_dev.log'

Потом: source ~/.bashrc

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

mb-start     # Запустить всё
mb-status    # Статус
mb-logs      # Логи
mb-stop      # Остановить

---

🎯 Production Deployment

systemd service для Backend

sudo cp backend/systemd/mybeacon-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mybeacon-api
sudo systemctl start mybeacon-api

Nginx для Frontend

# Build frontend
cd frontend
npm run build

# Copy to nginx
sudo cp -r dist /var/www/mybeacon-frontend

# Setup nginx
sudo cp nginx/mybeacon.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/mybeacon.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

---

Готово! 🎉