alexei.dolgolyov
e2e1107df7
Some checks failed
Lint & Test / test (push) Has been cancelled
- Replace URL-based image_source/url fields with image_asset_id/video_asset_id on StaticImagePictureSource and VideoCaptureSource (clean break, no migration) - Resolve asset IDs to file paths at runtime via AssetStore.get_file_path() - Add EntitySelect asset pickers for image/video in stream editor modal - Add notification sound configuration (global sound + per-app overrides) - Unify per-app color and sound overrides into single "Per-App Overrides" section - Persist notification history between server restarts - Add asset management system (upload, edit, delete, soft-delete) - Replace emoji buttons with SVG icons throughout UI - Various backend improvements: SQLite stores, auth, backup, MQTT, webhooks
81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# Server Operations
|
|
|
|
**Read this file when restarting, starting, or managing the server process.**
|
|
|
|
## Server Modes
|
|
|
|
Two independent server modes with separate configs, ports, and data directories:
|
|
|
|
| Mode | Command | Config | Port | API Key | Data |
|
|
| ---- | ------- | ------ | ---- | ------- | ---- |
|
|
| **Real** | `python -m wled_controller` | `config/default_config.yaml` | 8080 | `development-key-change-in-production` | `data/` |
|
|
| **Demo** | `python -m wled_controller.demo` | `config/demo_config.yaml` | 8081 | `demo` | `data/demo/` |
|
|
|
|
Demo mode can also be triggered via the `WLED_DEMO` environment variable (`true`, `1`, or `yes`). This works with any launch method — Python, Docker (`-e WLED_DEMO=true`), or the installed app (`set WLED_DEMO=true` before `LedGrab.bat`).
|
|
|
|
Both modes can run simultaneously on different ports.
|
|
|
|
## Restart Procedure
|
|
|
|
### Real server
|
|
|
|
Use the PowerShell restart script — it reliably stops only the server process and starts a new detached instance:
|
|
|
|
```bash
|
|
powershell -ExecutionPolicy Bypass -File "c:\Users\Alexei\Documents\wled-screen-controller\server\restart.ps1"
|
|
```
|
|
|
|
### Demo server
|
|
|
|
Find and kill the process on port 8081, then restart:
|
|
|
|
```bash
|
|
# Find PID
|
|
powershell -Command "netstat -ano | Select-String ':8081.*LISTEN'"
|
|
# Kill it
|
|
powershell -Command "Stop-Process -Id <PID> -Force"
|
|
# Restart
|
|
cd server && python -m wled_controller.demo
|
|
```
|
|
|
|
**Do NOT use** `Stop-Process -Name python` — it kills unrelated Python processes (VS Code extensions, etc.).
|
|
|
|
**Do NOT use** bash background `&` jobs — they get killed when the shell session ends.
|
|
|
|
## When to Restart
|
|
|
|
**Restart required** for changes to:
|
|
- API routes (`api/routes/`, `api/schemas/`)
|
|
- Core logic (`core/*.py`)
|
|
- Configuration (`config.py`)
|
|
- Utilities (`utils/*.py`)
|
|
- Data models (`storage/`)
|
|
|
|
**No restart needed** for:
|
|
- Static files (`static/js/`, `static/css/`) — but **must rebuild bundle**: `cd server && npm run build`
|
|
- Locale files (`static/locales/*.json`) — loaded by frontend
|
|
- Documentation files (`*.md`)
|
|
|
|
## Auto-Reload Note
|
|
|
|
Auto-reload is disabled (`reload=False` in `main.py`) due to watchfiles causing an infinite reload loop. Manual restart is required after server code changes.
|
|
|
|
## Demo Mode Awareness
|
|
|
|
**When adding new entity types, engines, device providers, or stores — keep demo mode in sync:**
|
|
|
|
1. **New entity stores**: Add the store's file path to `StorageConfig` in `config.py` — `model_post_init()` auto-rewrites `data/` to `data/demo/` paths when demo is active.
|
|
2. **New capture engines**: Verify demo mode filtering works — demo engines use `is_demo_mode()` gate in `is_available()`.
|
|
3. **New audio engines**: Same as capture engines — `is_available()` must respect `is_demo_mode()`.
|
|
4. **New device providers**: Gate discovery with `is_demo_mode()` like `DemoDeviceProvider.discover()`.
|
|
5. **New seed data**: Update `server/src/wled_controller/core/demo_seed.py` to include sample entities.
|
|
6. **Frontend indicators**: Demo state exposed via `GET /api/v1/version` -> `demo_mode: bool`. Frontend stores it as `demoMode` in app state and sets `document.body.dataset.demo = 'true'`.
|
|
7. **Backup/Restore**: New stores added to `STORE_MAP` in `system.py` automatically work in demo mode since the data directory is already isolated.
|
|
|
|
### Key files
|
|
|
|
- Config flag: `server/src/wled_controller/config.py` -> `Config.demo`, `is_demo_mode()`
|
|
- Demo engines: `core/capture_engines/demo_engine.py`, `core/audio/demo_engine.py`
|
|
- Demo devices: `core/devices/demo_provider.py`
|
|
- Seed data: `core/demo_seed.py`
|