WebSocket Broadcaster

This project provides a small FastAPI app that accepts raw WebSocket connections and an HTTP API to forward messages to connected websocket clients.

Features

• WebSocket endpoint: /ws (returns a generated client id as __id__:<id> on connect)
• HTTP POST /message JSON body {"message": "...", "client_id": "optional-id"}
  • if client_id is provided, the message is sent only to that client
  • otherwise the message is broadcast to all connected clients
• Test HTML client at / (loads static/index.html)

Package management

• This project uses the uv tool for managing Python environments and running the app as you requested. requirements.txt is provided for direct pip installs.

Docker

• A Dockerfile and docker-compose.yml are provided. The container runs the app via uv run main:app.

Quick start (local, without docker)

1. Run with uv

uv run uvicorn main:app --host 0.0.0.0 --port 8000

With Docker

docker build -t websocket-broadcast .
docker run -p 8000:8000 websocket-broadcast

Notes on TLS / Production

• For simplicity, TLS should be terminated at a reverse proxy (nginx, Caddy) or via Hetzner Load Balancer. I can add a sample nginx config and a systemd unit or Docker Compose setup with an automated cert manager (Let's Encrypt + Caddy) if you want.

Next steps I can do for you

• Add nginx reverse proxy + TLS example
• Add systemd/service file for bare VM deployment
• Add deployment script to build/pull and restart the container on the Hetzner box