mirror of
https://github.com/imgfloat/server.git
synced 2026-02-05 11:49:25 +00:00
87 lines
3.9 KiB
Markdown
87 lines
3.9 KiB
Markdown
# Imgfloat
|
||
|
||
A Spring Boot overlay server for Twitch broadcasters and their channel admins. Broadcasters can authorize via Twitch OAuth and invite channel admins to manage images that float over a transparent canvas. Updates are pushed in real time over WebSockets so OBS browser sources stay in sync.
|
||
|
||
## Features
|
||
- Twitch OAuth (OAuth2 login) with broadcaster and channel admin access controls.
|
||
- Admin console with Twitch player embed and canvas preview.
|
||
- Broadcaster overlay view optimized for OBS browser sources.
|
||
- Real-time asset creation, movement, resize, rotation, visibility toggles, and deletion via STOMP/WebSockets.
|
||
- In-memory channel directory optimized with lock-free collections for fast updates.
|
||
- Optional SSL with local self-signed keystore support.
|
||
- Dockerfile, Makefile, CI workflow, and Maven build.
|
||
- OpenAPI/Swagger UI docs available at `/swagger-ui.html`.
|
||
|
||
## Getting started
|
||
### Prerequisites
|
||
- Java 17+
|
||
- Maven 3.9+
|
||
- Twitch Developer credentials (Client ID/Secret)
|
||
|
||
### Local run
|
||
```bash
|
||
TWITCH_CLIENT_ID=your_id TWITCH_CLIENT_SECRET=your_secret \
|
||
TWITCH_REDIRECT_URI=http://localhost:8080/login/oauth2/code/twitch mvn spring-boot:run
|
||
```
|
||
The default server port is `8080`. Log in via `/oauth2/authorization/twitch`. The redirect URI above is what Twitch should be configured to call for local development.
|
||
|
||
### Hot reload during development
|
||
- The project includes Spring Boot DevTools so Java and Thymeleaf changes trigger a restart automatically when you run `make run` (which now forks the Spring Boot process so devtools can watch the classpath).
|
||
- Static assets under `src/main/resources/static` are refreshed through the built-in LiveReload server from DevTools; install a LiveReload browser extension to automatically reload the overlay or dashboard when CSS/JS files change.
|
||
|
||
### Enable TLS locally
|
||
```bash
|
||
make ssl
|
||
SSL_ENABLED=true SSL_KEYSTORE_PATH=file:$(pwd)/local/keystore.p12 \
|
||
TWITCH_CLIENT_ID=your_id TWITCH_CLIENT_SECRET=your_secret \
|
||
mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=8443"
|
||
```
|
||
|
||
### Make targets
|
||
- `make run` – start the dev server (exports `TWITCH_REDIRECT_URI` to `http://localhost:8080/login/oauth2/code/twitch` if unset).
|
||
- `make test` – run unit/integration tests.
|
||
- `make package` – build the runnable jar.
|
||
- `make docker-build` / `make docker-run` – containerize and run the service.
|
||
- `make ssl` – create a self-signed PKCS12 keystore in `./local`.
|
||
|
||
### Docker
|
||
```bash
|
||
make docker-build
|
||
TWITCH_CLIENT_ID=your_id TWITCH_CLIENT_SECRET=your_secret docker run -p 8080:8080 imgfloat:latest
|
||
```
|
||
|
||
### Data storage configuration
|
||
- `IMGFLOAT_DB_PATH` – filesystem location for the SQLite database (default: `imgfloat.db`).
|
||
- `IMGFLOAT_ASSETS_PATH` – root directory where uploaded assets are persisted (default: `assets`).
|
||
- `IMGFLOAT_PREVIEWS_PATH` – root directory for generated preview images (default: `previews`).
|
||
|
||
### Docker Compose example with persistent storage
|
||
```yaml
|
||
services:
|
||
imgfloat:
|
||
image: imgfloat:latest
|
||
environment:
|
||
TWITCH_CLIENT_ID: your_id
|
||
TWITCH_CLIENT_SECRET: your_secret
|
||
TWITCH_REDIRECT_URI: https://yourdomain/login/oauth2/code/twitch
|
||
IMGFLOAT_DB_PATH: /var/lib/imgfloat/imgfloat.db
|
||
IMGFLOAT_ASSETS_PATH: /var/lib/imgfloat/assets
|
||
IMGFLOAT_PREVIEWS_PATH: /var/lib/imgfloat/previews
|
||
ports:
|
||
- "8080:8080"
|
||
volumes:
|
||
- ./data/db:/var/lib/imgfloat
|
||
- ./data/assets:/var/lib/imgfloat/assets
|
||
- ./data/previews:/var/lib/imgfloat/previews
|
||
```
|
||
The `volumes` map local folders into the container so database and uploaded files survive container restarts.
|
||
|
||
### OAuth configuration
|
||
Spring Boot reads Twitch credentials from `TWITCH_CLIENT_ID` and `TWITCH_CLIENT_SECRET`. The redirect URI comes from `TWITCH_REDIRECT_URI` (defaulting to `{baseUrl}/login/oauth2/code/twitch`).
|
||
|
||
### CI
|
||
GitHub Actions runs `mvn verify` on pushes and pull requests via `.github/workflows/ci.yml`.
|
||
|
||
### License
|
||
MIT
|