# 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)
./start.sh dev

# Build and deploy to nginx (RECOMMENDED)
./start.sh deploy

# Build only (without deploy)
./start.sh build
```

**IMPORTANT:** Frontend is served by nginx from `/var/www/mybeacon/frontend`.
After building, you MUST deploy to nginx:
```bash
./start.sh deploy   # Build + copy to nginx
```

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