McSchneidarandFlorian Ostertag
336d08040e
* Replace the WCF webserver with an ASP.NET Core webserver (VocaluxeWeb) - New project VocaluxeWeb: ASP.NET Core 2.3 (Kestrel) on .NET Framework 4.8.1, HTTP or HTTPS with a self-signed certificate, REST API (/api/v1) with Swagger, live events (Server-Sent Events) - Access to the game only through IVocaluxeRemote; requests run on the main thread once per frame - Sessions with roles (guest, player, admin) and configurable permissions, PINs hashed with PBKDF2 - Queue as a playlist with requesters and singers, fair order (one song per person and round) - Admin: settings, server status, logged-in devices, activate/deactivate and delete profiles - Profile pictures: own photo or one of the Vocaluxe avatars - Game: WebApp queue screen (song options, playlist group) to start the next song with the chosen singers, return to it after singing, warning when the webserver is off, remote keyboard - Old WCF server, WebserverInitalConfig and URL reservations removed; libraries moved to libs/managed - Unit tests for PIN hashing, settings and permissions, queue order and device names - AppVeyor: Visual Studio 2022 image and Node.js 24 (the build compiles the WebApp) - Documentation in VocaluxeWeb/README.md * New WebApp (Vue 3, TypeScript, Vite) replacing the old jQuery Mobile website - Login with profile and PIN, create profiles - Songs with search, filters, sorting and 30 second previews - Queue: add songs with game mode, audio and singers, edit, reorder, start in the game - Playlists: create, edit, add to the queue - Now playing with live updates, remote control and keyboard - Players: own profile with picture (photo or Vocaluxe avatar), roles for admins - Admin settings: permissions, server status, devices, profiles - Help page, responsive layout for phones, tablets and desktops, light and dark mode - Texts in WebApp/src/locales/en.json, translated with Transifex - Old website and PhoneGap config removed --------- Co-authored-by: Florian Ostertag <flokuep@users.noreply.github.com>
98 lines
5.5 KiB
Markdown
98 lines
5.5 KiB
Markdown
# Vocaluxe WebApp and webserver
|
|
|
|
Vocaluxe has a built-in webserver. Guests open the WebApp on their phones (scan the QR code shown under
|
|
`Options → Server`), add songs to the queue, manage playlists and profiles and use the phone as a remote.
|
|
|
|
| Folder | What it is |
|
|
|---------------------|------------------------------------------------------------------------------------------------|
|
|
| `VocaluxeWeb` | The webserver: ASP.NET Core 2.3 (Kestrel) on .NET Framework 4.8.1, REST API, live events |
|
|
| `WebApp` | The WebApp: Vue 3, TypeScript and Vite |
|
|
| `Vocaluxe/Base/Web` | The game side: starts the server (`CWebServer`) and implements `IVocaluxeRemote` (`CVocaluxeRemote`) |
|
|
|
|
## Architecture
|
|
|
|
* `VocaluxeWeb` does not reference the game. Everything it needs from Vocaluxe goes through the interface
|
|
`IVocaluxeRemote`, which `CVocaluxeRemote` implements in the game.
|
|
* Requests run on Kestrel threads, but the game is not thread-safe. Calls into the game are queued with
|
|
`CMainThreadDispatcher` and executed once per frame on the main thread (`CWebHost.Tick`, called from
|
|
`CWebServer.ProcessTasks`). A call that is not executed within 5 seconds fails with `503`.
|
|
* The queue is a normal playlist in the game (default name `WebApp Queue`). `CQueueService` keeps who requested
|
|
a song and who sings it. Songs are inserted fairly: the n-th song of a person goes behind everybody's n-th song.
|
|
The queue can also be opened and started in the game (song menu → options → playlist group → WebApp queue).
|
|
* Live updates (queue, game state, notifications) are sent with Server-Sent Events (`GET /api/v1/events`).
|
|
* Logins are kept in memory (HttpOnly cookie `vlx_session`, logged out after 12 hours without use).
|
|
Profiles without PIN log in again automatically after a restart of Vocaluxe.
|
|
|
|
### Roles and permissions
|
|
|
|
Every profile has a role: `Guest`, `Player` or `Admin`. Admins may do everything; what guests and players may do is set
|
|
in the WebApp under `More → Settings` (stored in `WebServer.json`). Admins can also
|
|
|
|
* see and log out logged-in devices,
|
|
* deactivate and delete profiles,
|
|
* see the address, port and HTTPS state of the server (the port is set in `config.xml` under `Server/ServerPort`, default 3000;
|
|
HTTPS is switched in the game under `Options → Server`).
|
|
|
|
### Profile pictures
|
|
|
|
A profile picture is either an own photo (uploaded from the phone, saved as `WebApp_*.jpg` in the profile folder) or one of
|
|
the avatars that come with Vocaluxe or were put into the profile folder (`GET /api/v1/avatars`). Uploaded photos of other
|
|
people are not offered for selection.
|
|
|
|
### Files
|
|
|
|
Stored in the Vocaluxe data folder:
|
|
|
|
| File | Content |
|
|
|--------------------|---------------------------------------------------------------|
|
|
| `WebServer.json` | WebApp settings: permissions, queue playlist name |
|
|
| `WebServer.pfx` | Self-signed certificate for HTTPS (created on first use) |
|
|
| `WebCache` | Resized covers and avatars |
|
|
|
|
The built WebApp is copied to the `Website` folder next to `Vocaluxe.exe`.
|
|
|
|
## Building
|
|
|
|
[Node.js](https://nodejs.org) (LTS, 22.12 or newer) is required. Building the project `VocaluxeWeb` (or the
|
|
whole solution) runs `npm ci` (only when `package.json` or `package-lock.json` changed) and `npm run build` in `WebApp`.
|
|
If Node.js is missing, the build stops with a hint. Restart Visual Studio after installing Node.js.
|
|
|
|
## Developing the WebApp
|
|
|
|
Start Vocaluxe with the webserver switched on, then:
|
|
|
|
```
|
|
cd WebApp
|
|
npm run dev
|
|
```
|
|
|
|
Vite serves the WebApp with hot reload and forwards `/api` and `/swagger` to Vocaluxe at `http://localhost:3000`.
|
|
For another address use `VOCALUXE_URL=http://192.168.0.10:3000 npm run dev`.
|
|
|
|
## REST API
|
|
|
|
* All endpoints are under `/api/v1`. Errors are returned as problem details (`{ "title": "...", "status": 403 }`).
|
|
* Swagger UI: `http://<address>:3000/swagger`, OpenAPI document: `/swagger/v1/swagger.json`.
|
|
* The TypeScript types of the WebApp (`WebApp/src/api/schema.d.ts`) are generated from the OpenAPI document.
|
|
After changing the API, start Vocaluxe (or set `VOCALUXE_URL`) and run `npm run api:generate` in `WebApp`.
|
|
|
|
## HTTPS
|
|
|
|
HTTP is the default. With `Options → Server → Server encryption` switched on, Vocaluxe uses HTTPS with a self-signed
|
|
certificate for the computer's name and IP addresses. Browsers do not trust it and show a warning the first time
|
|
("Your connection is not private"); the connection is encrypted nevertheless. The WebApp explains this on its help page.
|
|
Some browser features (camera, installing the WebApp on the home screen) only work over HTTPS. With the
|
|
self-signed certificate they depend on the browser: some browsers allow them after accepting the warning, others don't.
|
|
|
|
## Translations
|
|
|
|
The texts of the WebApp are in `WebApp/src/locales/<language>.json` (flat key/value JSON, `en.json` is the source).
|
|
They are translated on [Transifex](https://www.transifex.com/projects/p/vocaluxe/) like the game
|
|
(see `transifex.yaml`, format `KEYVALUEJSON`). New languages are picked up automatically when a file is added.
|
|
Placeholders like `{name}` must stay unchanged.
|
|
|
|
## Tests
|
|
|
|
The NUnit tests in `Tests/VocaluxeWeb` cover PIN hashing, settings and permissions, the fair queue order and the
|
|
device names shown to admins. They run with the other tests of the `Tests` project.
|