DiceRooms (learning playground)

DiceRooms is a tiny learning playground built with Rust + Axum. It lets you:

• create an ad‑hoc "room"
• invite friends by sharing the URL
• roll dice together (d4, d6, d8, d10, d12, d20, d100)
• see everyone’s rolls and presence instantly via WebSockets
• optionally name the room and yourself, and pick a color

Under the hood it uses:

• Axum for HTTP and WebSocket routing
• Tera for server‑side HTML templating
• A bit of front‑end JS/CSS for the room UI
• Optional Redis for persisting room state between restarts

This repository exists primarily as a playground to learn and experiment with these pieces.

Quick start (Cargo)

Prerequisites:

• Rust toolchain (stable) installed
• Optional: Redis running locally if you want room state to persist between restarts

Run the server:

cargo run

By default the server listens on 0.0.0.0:8000. You can change this with an environment variable:

ROOMS_LISTEN_ADDR=127.0.0.1:9000 cargo run

Access in your browser:

• Open http://localhost:8000/ (or whatever address/port you set)
• Click "create room"; you’ll be redirected to /rooms/{hash}
• Share that room URL with others

Optional persistence with Redis

If a Redis URL is provided, room state (players, rolls, room name) will be persisted between server restarts. Set either of these environment variables before starting the server:

• ROOMS_REDIS_URL
• REDIS_URL

Example:

export ROOMS_REDIS_URL=redis://127.0.0.1:6379
cargo run

Run with Docker

Build and run the image locally:

docker build -t dicerooms:local .
docker run --rm -p 8000:8000 dicerooms:local

Then open http://localhost:8000/ in your browser.

You can override the listen address inside the container too:

docker run --rm -e ROOMS_LISTEN_ADDR=0.0.0.0:9000 -p 9000:9000 dicerooms:local

Docker Hub

The image is available on Docker Hub:

docker run -p 8000:8000 sbroeckling/dicerooms:latest

Run with docker-compose (includes Redis)

A minimal compose file is included to run the web app alongside Redis.

docker compose up --build

Then open http://localhost:8000/.

Project layout

• src/main.rs — app setup, routes, static files, server startup
• src/rooms.rs — room routes (create room, open room, REST endpoints, WebSocket)
• src/models.rs — in‑memory state and optional Redis persistence
• templates/ — Tera HTML templates (index and room)
• static/ — front‑end assets (room.js, style.css)

Configuration

Environment variables:

• ROOMS_LISTEN_ADDR — address:port to bind (default: 0.0.0.0:8000)
• ROOMS_REDIS_URL or REDIS_URL — Redis connection string for persistence (optional)

Static files are served from /static.

Notes

• This is a learning playground, not production‑ready software.
• WebSocket URL is derived from the current page’s host (ws:// for http, wss:// for https).
• If Redis is not available, the app still works entirely in memory.