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

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

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

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

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