|
@@ -0,0 +1,229 @@
|
|
|
|
|
+# MyBeacon Development Container
|
|
|
|
|
+
|
|
|
|
|
+## LXC Container (Debian 13)
|
|
|
|
|
+
|
|
|
|
|
+**Access:**
|
|
|
|
|
+- SSH: `ssh -p 2223 user@ms.e-bash.ru`
|
|
|
|
|
+- Frontend: http://ms.e-bash.ru:2280
|
|
|
|
|
+- Backend API: http://ms.e-bash.ru:2280/api/v1/
|
|
|
|
|
+- API Docs: http://ms.e-bash.ru:2280/docs
|
|
|
|
|
+
|
|
|
|
|
+## Stack
|
|
|
|
|
+
|
|
|
|
|
+- **Backend**: Python 3.13, FastAPI, Poetry
|
|
|
|
|
+- **Frontend**: Vue 3, Vite
|
|
|
|
|
+- **Databases**: PostgreSQL 17, ClickHouse, Redis
|
|
|
|
|
+- **Web**: Nginx (reverse proxy)
|
|
|
|
|
+
|
|
|
|
|
+## Quick Start
|
|
|
|
|
+
|
|
|
|
|
+### Start/Stop Services
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+# Backend control
|
|
|
|
|
+./backend.sh start # Start
|
|
|
|
|
+./backend.sh stop # Stop
|
|
|
|
|
+./backend.sh restart # Restart
|
|
|
|
|
+./backend.sh logs # View logs
|
|
|
|
|
+./backend.sh status # Check status
|
|
|
|
|
+
|
|
|
|
|
+# Frontend is served as static files via Nginx
|
|
|
|
|
+# To rebuild: cd frontend && npm run build
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### Check Services Status
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+sudo systemctl status postgresql
|
|
|
|
|
+sudo systemctl status clickhouse-server
|
|
|
|
|
+sudo systemctl status redis
|
|
|
|
|
+sudo systemctl status nginx
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## Credentials
|
|
|
|
|
+
|
|
|
|
|
+### Superadmin
|
|
|
|
|
+- Email: `superadmin@mybeacon.com`
|
|
|
|
|
+- Password: `superadmin123`
|
|
|
|
|
+
|
|
|
|
|
+### Databases
|
|
|
|
|
+
|
|
|
|
|
+**PostgreSQL:**
|
|
|
|
|
+```bash
|
|
|
|
|
+sudo -u postgres psql -d mybeacon
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**ClickHouse:**
|
|
|
|
|
+```bash
|
|
|
|
|
+clickhouse-client --database mybeacon
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**Redis:**
|
|
|
|
|
+```bash
|
|
|
|
|
+redis-cli
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## Project Structure
|
|
|
|
|
+
|
|
|
|
|
+```
|
|
|
|
|
+~/mybeacon-backend/
|
|
|
|
|
+├── backend/ # Python FastAPI backend
|
|
|
|
|
+│ ├── app/ # Source code
|
|
|
|
|
+│ │ ├── api/ # API endpoints
|
|
|
|
|
+│ │ ├── models/ # SQLAlchemy models
|
|
|
|
|
+│ │ ├── core/ # Core settings, security, database
|
|
|
|
|
+│ │ └── main.py # App entry point
|
|
|
|
|
+│ ├── alembic/ # Database migrations
|
|
|
|
|
+│ ├── pyproject.toml # Python dependencies
|
|
|
|
|
+│ └── .env # Config (SECRET_KEY, DATABASE_URL)
|
|
|
|
|
+├── frontend/ # Vue 3 frontend
|
|
|
|
|
+│ ├── src/ # Source code
|
|
|
|
|
+│ │ ├── api/ # API clients
|
|
|
|
|
+│ │ ├── views/ # Page components
|
|
|
|
|
+│ │ ├── router/ # Vue Router
|
|
|
|
|
+│ │ └── i18n/ # Translations (RU/EN)
|
|
|
|
|
+│ ├── dist/ # Production build (served by nginx)
|
|
|
|
|
+│ └── package.json # Node dependencies
|
|
|
|
|
+├── backend.sh # Backend control script
|
|
|
|
|
+└── scripts/ # Deployment scripts
|
|
|
|
|
+ └── deploy.sh # Deploy from local machine
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## Development Workflow
|
|
|
|
|
+
|
|
|
|
|
+### Local Development
|
|
|
|
|
+
|
|
|
|
|
+1. **Clone the repo:**
|
|
|
|
|
+ ```bash
|
|
|
|
|
+ git clone https://h2.e-bash.ru/root/mybeacon-backend.git
|
|
|
|
|
+ cd mybeacon-backend
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+2. **Work on your changes locally**
|
|
|
|
|
+
|
|
|
|
|
+3. **Deploy to dev container:**
|
|
|
|
|
+ ```bash
|
|
|
|
|
+ ./scripts/deploy.sh
|
|
|
|
|
+ # or
|
|
|
|
|
+ ./scripts/deploy.sh --backend-only # Only restart backend
|
|
|
|
|
+ ./scripts/deploy.sh --skip-build # Skip frontend build
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+### Backend Development
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+cd backend
|
|
|
|
|
+
|
|
|
|
|
+# Install dependencies
|
|
|
|
|
+poetry install
|
|
|
|
|
+
|
|
|
|
|
+# Run migrations
|
|
|
|
|
+poetry run alembic upgrade head
|
|
|
|
|
+poetry run alembic revision --autogenerate -m "description"
|
|
|
|
|
+
|
|
|
|
|
+# Run dev server (with auto-reload)
|
|
|
|
|
+poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
|
|
|
|
+
|
|
|
|
|
+# Format code
|
|
|
|
|
+poetry run black app/
|
|
|
|
|
+poetry run ruff app/
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### Frontend Development
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+cd frontend
|
|
|
|
|
+
|
|
|
|
|
+# Install dependencies
|
|
|
|
|
+npm install
|
|
|
|
|
+
|
|
|
|
|
+# Run dev server (with HMR)
|
|
|
|
|
+npm run dev -- --host 0.0.0.0
|
|
|
|
|
+
|
|
|
|
|
+# Build for production
|
|
|
|
|
+npm run build
|
|
|
|
|
+
|
|
|
|
|
+# Preview production build
|
|
|
|
|
+npm run preview
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## API Endpoints
|
|
|
|
|
+
|
|
|
|
|
+### Authentication
|
|
|
|
|
+- `POST /api/v1/auth/login` - Login (get JWT tokens)
|
|
|
|
|
+- `POST /api/v1/auth/refresh` - Refresh access token
|
|
|
|
|
+- `GET /api/v1/auth/me` - Current user info
|
|
|
|
|
+
|
|
|
|
|
+### Superadmin
|
|
|
|
|
+- `GET/POST /api/v1/superadmin/devices` - Manage all devices
|
|
|
|
|
+- `GET/POST /api/v1/superadmin/organizations` - Manage organizations
|
|
|
|
|
+- `GET/POST /api/v1/superadmin/users` - Manage users
|
|
|
|
|
+- `GET/POST /api/v1/superadmin/settings/auto-registration` - Toggle device registration
|
|
|
|
|
+
|
|
|
|
|
+### Device API (for hardware)
|
|
|
|
|
+- `POST /api/v1/registration` - Register new device
|
|
|
|
|
+- `GET /api/v1/config?device_id=MAC` - Get device config
|
|
|
|
|
+- `POST /api/v1/ble` - Upload BLE events
|
|
|
|
|
+- `POST /api/v1/wifi` - Upload WiFi events
|
|
|
|
|
+
|
|
|
|
|
+## Troubleshooting
|
|
|
|
|
+
|
|
|
|
|
+### Backend won't start
|
|
|
|
|
+```bash
|
|
|
|
|
+./backend.sh logs # Check logs
|
|
|
|
|
+sudo -u postgres psql -d mybeacon # Check DB connection
|
|
|
|
|
+pkill -f uvicorn # Kill zombie processes
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### Frontend changes not visible
|
|
|
|
|
+```bash
|
|
|
|
|
+cd frontend
|
|
|
|
|
+npm run build # Rebuild frontend
|
|
|
|
|
+# Nginx serves static files from dist/
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### Check ports
|
|
|
|
|
+```bash
|
|
|
|
|
+sudo netstat -tlnp | grep -E '8000|5432|8123|6379|80'
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+### View logs
|
|
|
|
|
+```bash
|
|
|
|
|
+./backend.sh logs # Backend logs
|
|
|
|
|
+sudo tail -f /var/log/nginx/error.log # Nginx logs
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## Nginx Configuration
|
|
|
|
|
+
|
|
|
|
|
+Nginx is configured as reverse proxy:
|
|
|
|
|
+- `/` → Frontend static files from `frontend/dist/`
|
|
|
|
|
+- `/api/` → Backend at `localhost:8000`
|
|
|
|
|
+- `/docs` → Swagger UI
|
|
|
|
|
+- `/redoc` → ReDoc
|
|
|
|
|
+
|
|
|
|
|
+Config: `/etc/nginx/sites-enabled/mybeacon`
|
|
|
|
|
+
|
|
|
|
|
+## Git Workflow
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+# On local machine
|
|
|
|
|
+git add .
|
|
|
|
|
+git commit -m "Your message"
|
|
|
|
|
+git push origin master
|
|
|
|
|
+
|
|
|
|
|
+# Deploy
|
|
|
|
|
+./scripts/deploy.sh
|
|
|
|
|
+
|
|
|
|
|
+# Or manually on server
|
|
|
|
|
+ssh -p 2223 user@ms.e-bash.ru
|
|
|
|
|
+cd ~/mybeacon-backend
|
|
|
|
|
+git pull
|
|
|
|
|
+./backend.sh restart
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+## TODO
|
|
|
|
|
+
|
|
|
|
|
+- [ ] Add HTTPS (certbot)
|
|
|
|
|
+- [ ] Configure systemd for auto-start
|
|
|
|
|
+- [ ] Add logrotate for logs
|
|
|
|
|
+- [ ] ClickHouse integration for events
|