Accordion Chat MVP - A self-hosted real-time chat application with Spring Boot WebSocket backend and LibGDX frontend.
The web app: two users chatting in real time, with a second channel in the sidebar.
How these were captured: the backend and web app jars were built and run locally (in-memory H2, backend JVM in UTC as in the Docker image, usage reporting off), two made-up accounts were registered through the web app, a game-night channel was created through the REST API, and the two browser windows were driven and screenshotted with headless Chromium (Playwright) on 2026-10-18.
Accordion is a Discord-like self-hosted chat application designed for simplicity and extensibility. This MVP demonstrates core chat functionality with multiple chat rooms/channels, password-based authentication, and real-time messaging.
Technology Stack:
- Backend: Spring Boot 3.x, WebSocket (STOMP), H2 Database, Spring Data JPA
- Web Frontend: Spring Boot, Thymeleaf, SockJS, STOMP.js (browser-based)
- Desktop Frontend: LibGDX, Java WebSocket client, Scene2D UI
- ✅ Multiple chat rooms/channels - Create and switch between different channels
- ✅ Single chat room (global) - Backwards compatible default channel
- ✅ Password-based authentication (Spring Security, BCrypt-hashed passwords, JWT bearer tokens)
- ✅ Authenticated WebSocket sessions (STOMP
CONNECTframes require a valid JWT) - ✅ Real-time message broadcasting via WebSocket
- ✅ Message persistence in H2 database (survives container restarts)
- ✅ Message history on login (channel-specific)
- ✅ Timestamp for each message
- ✅ User join notifications
- ✅ Browser-based web interface (accessible from any device)
- ✅ Cross-platform desktop support (LibGDX)
- ✅ Docker containerization for easy deployment
- Java 17 or higher
- Maven 3.6+ (for backend and webapp)
- Gradle 7+ (included via wrapper for LibGDX desktop frontend)
- Docker & Docker Compose (for containerized deployment)
Option 1: Using Docker Compose (Recommended)
# Copy sample environment file and customize if needed
cp sample.env .env
# Generate a signing secret and set it as JWT_SECRET in .env
# (the backend will not start without it)
openssl rand -base64 48
# Edit .env to configure ports and other settings
# Start all services (backend + web app)
docker compose up -d
# Access the web application
open http://localhost:3000
# For network access from other devices:
# 1. Set DOCKER_HOST_IP to your machine's IP in .env
# 2. Restart: docker compose down && docker compose up -d
# 3. Access from other devices: http://YOUR_IP:3000Option 2: Run services manually
# Terminal 1 - Start backend (JWT_SECRET is required; startup fails without it)
export JWT_SECRET="$(openssl rand -base64 48)"
cd backend
mvn spring-boot:run
# Terminal 2 - Start web application
cd webapp
mvn spring-boot:run
# Access at http://localhost:3000
# Optional: Terminal 3 - Start LibGDX desktop client
cd frontend
./gradlew desktop:runOption 3: Run backend + multiple LibGDX clients
# Terminal 1 - Start backend (JWT_SECRET is required; startup fails without it)
export JWT_SECRET="$(openssl rand -base64 48)"
cd backend && mvn spring-boot:run
# Terminal 2+ - Start as many LibGDX clients as you want
cd frontend && ./gradlew desktop:runWeb Application (Browser):
- Navigate to
http://localhost:3000 - Click "Register" to switch the form to registration mode on a first visit
- Enter your username (minimum 3 characters, alphanumeric + underscore) and a password (minimum 8 characters, containing an uppercase letter, a lowercase letter, and a digit)
- Submit the form — the returned JWT is used for the REST calls and the WebSocket handshake that follow
- Select a channel from the sidebar or create a new one with "+ New Channel"
- Type your message and click "Send" or press Enter
- Switch between channels by clicking on channel names in the sidebar
- Open in multiple browser tabs to test real-time messaging across channels
LibGDX Desktop Client:
Note: The desktop client predates the JWT authentication described below and has not been updated for it.
ChatWebSocketClientsends a STOMPCONNECTframe with noAuthorizationheader, whichWebSocketAuthInterceptorrejects, so the client cannot connect to the current backend. Use the web application until desktop parity lands.
- Frontend window will open (800x600)
- Enter your username (minimum 3 characters)
- Click "Login" to enter the chat room
- Type your message and click "Send" or press Enter
- Open multiple clients to test real-time messaging
Backend API:
- Backend runs on
http://localhost:8080 - WebSocket endpoint:
ws://localhost:8080/ws - Authentication: every endpoint except those marked public below requires an
Authorization: Bearer <token>header. Tokens are issued by the register and login endpoints. See MVP.md for request and response shapes. - REST API endpoints:
POST /api/users/register- Register a new user, returns a JWT (public)POST /api/users/login- Log in, returns a JWT (public)GET /api/users/check/{username}- Report whether a username is takenGET /api/channels- List all channelsPOST /api/channels- Create a new channelGET /api/channels/{id}- Get channel detailsGET /api/messages?limit={n}&channelId={id}- Get recent messages, optionally scoped to a channel
- STOMP destinations (application prefix
/app, broker prefix/topic):- Send
/app/chat.send→ broadcast on/topic/messages(default channel) - Send
/app/chat.send/{channelId}→ broadcast on/topic/messages/{channelId} - Send
/app/chat.join→ broadcast on/topic/messages(default channel) - Send
/app/chat.join/{channelId}→ broadcast on/topic/messages/{channelId} - Send
/app/chat.typing/{channelId}→ broadcast on/topic/typing/{channelId}
- Send
- Docker 20.10+
- Docker Compose 2.0+
The application uses environment variables for configuration. A sample.env file is provided with all available options:
# Copy and customize the environment file
cp sample.env .env
# Edit .env to configure:
# - The required JWT signing secret (JWT_SECRET)
# - Port numbers (BACKEND_PORT, WEBAPP_PORT)
# - CORS settings (APP_CORS_ALLOWED_ORIGINS)
# - Database configuration
# - Validation rules (message length, username and password constraints)
# - And more...Key configuration options:
JWT_SECRET: Required. JWT signing secret, at least 32 bytes, with no default — the backend fails to start when it is missing, blank, or too short. Generate one withopenssl rand -base64 48and use a distinct value per deployment.JWT_EXPIRATION: JWT lifetime in milliseconds (default: 86400000, i.e. 24 hours)BACKEND_PORT: Backend service port (default: 8080)WEBAPP_PORT: Web application port (default: 3000)APP_CORS_ALLOWED_ORIGINS: CORS allowed origins (default:*for development)APP_MESSAGE_MAX_LENGTH: Maximum message length (default: 1000)APP_USERNAME_MIN_LENGTH: Minimum username length (default: 3)APP_USERNAME_MAX_LENGTH: Maximum username length (default: 50)APP_PASSWORD_MIN_LENGTH: Minimum password length (default: 8)APP_CHANNEL_NAME_MIN_LENGTH: Minimum channel name length (default: 3)APP_CHANNEL_NAME_MAX_LENGTH: Maximum channel name length (default: 50)USAGE_REPORTING_ENABLED: Whether the backend reports that it is in use to the trace usage service (default when unset:true; anything buttrue/on/yes/1, blank included, is off; see Usage reporting)
See sample.env for the complete list of configurable options.
The easiest way to run the backend and web application in containers:
# Build and start both services
docker compose up -d
# View logs
docker compose logs -f backend
# Stop the service
docker compose downThe services will be available at:
- Web Application:
http://localhost:3000(browser-based UI) - Backend API:
http://localhost:8080(REST & WebSocket)
Note: If you customized ports in .env, use those port numbers instead.
Backend:
# Build the backend image
docker build -t accordion-backend:latest -f Dockerfile .
# Run the container
docker run -d \
-p 8080:8080 \
-e JWT_SECRET="$(openssl rand -base64 48)" \
--name accordion-backend \
accordion-backend:latestWeb Application:
# Build the webapp image
docker build -t accordion-webapp:latest -f Dockerfile.webapp .
# Run the container (requires backend to be running and reachable from the browser;
# the webapp server itself never calls the backend, so the URLs are the ones the
# browser will use)
docker run -d \
-p 3000:3000 \
-e ACCORDION_BACKEND_CLIENT_URL=http://localhost:8080 \
-e ACCORDION_BACKEND_CLIENT_WS_URL=http://localhost:8080/ws \
--name accordion-webapp \
accordion-webapp:latestView logs:
docker logs -f accordion-backend
docker logs -f accordion-webappStop and remove:
docker stop accordion-backend accordion-webapp
docker rm accordion-backend accordion-webappConfigure the application using environment variables:
docker run -d \
-p 8080:8080 \
-e JWT_SECRET="$(openssl rand -base64 48)" \
-e APP_CORS_ALLOWED_ORIGINS="https://yourdomain.com" \
-e APP_USERNAME_MIN_LENGTH=5 \
-e APP_MESSAGE_MAX_LENGTH=500 \
--name accordion-backend \
accordion-backend:latestSee compose.yml for all available environment variables.
View the database contents:
- URL:
http://localhost:8080/h2-console - JDBC URL: When using Docker Compose with persistence (default):
jdbc:h2:file:/app/data/chatdb;MODE=MySQL;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE - JDBC URL: When using in-memory mode:
jdbc:h2:mem:chatdb - Username:
sa - Password: (leave empty)
- Note: The JDBC URL (including parameters) should match your
SPRING_DATASOURCE_URLenvironment variable.
By default, when running via Docker Compose, the application uses a file-based H2 database with Docker volume persistence. This means your chat messages and channels are preserved across container restarts.
Note: When running the backend directly from source (without Docker), it defaults to in-memory H2 as configured in backend/src/main/resources/application.properties.
Default Configuration (with Docker Compose):
- Database is stored in a Docker volume named
h2_data - Data persists when containers are stopped and restarted
- Database files are stored at
/app/data/chatdbinside the container - Schema management uses
updatemode by default (convenient for development)- For production: Consider using
validatemode with proper database migrations (Flyway/Liquibase) - Override in
.env:SPRING_JPA_HIBERNATE_DDL_AUTO=validate
- For production: Consider using
To use in-memory database instead (data lost on restart):
Edit your .env file:
SPRING_DATASOURCE_URL=jdbc:h2:mem:chatdb
SPRING_JPA_HIBERNATE_DDL_AUTO=create-dropThen restart:
docker compose down && docker compose up -dTo clear persisted data:
# Stop containers and remove the volume
docker compose down -v
# Restart fresh
docker compose up -daccordion/
├── MVP.md # Detailed MVP documentation
├── README.md # This file
├── TICKETS.md # Development tickets and status
├── DOCKER.md # Docker deployment guide
├── sample.env # Environment variable template for Docker Compose
├── Dockerfile # Docker image for backend
├── Dockerfile.webapp # Docker image for web application
├── compose.yml # Docker Compose configuration
├── .dockerignore # Docker build exclusions
├── backend/ # Spring Boot backend
│ ├── pom.xml # Maven configuration
│ └── src/
│ ├── main/java/com/accordion/
│ │ ├── AccordionApplication.java
│ │ ├── config/ # WebSocket, Spring Security, and data seeding configuration
│ │ ├── controller/ # REST and WebSocket controllers
│ │ ├── dto/ # Request/response payloads (login, register, auth)
│ │ ├── model/ # JPA entities
│ │ ├── repository/ # Data repositories
│ │ ├── security/ # JWT issuing/validation and authentication filters
│ │ ├── service/ # Business logic
│ │ ├── trace/ # Vendored trace-client-java (usage reporting)
│ │ └── util/ # Validation utilities
│ └── test/ # JUnit 5 test suite (mirrors the main tree)
├── webapp/ # Spring Boot web application
│ ├── pom.xml # Maven configuration
│ └── src/
│ ├── main/
│ │ ├── java/com/accordion/webapp/
│ │ │ ├── AccordionWebApplication.java
│ │ │ └── controller/ # Web controllers
│ │ └── resources/
│ │ ├── templates/ # Thymeleaf HTML templates
│ │ │ ├── index.html # Login page
│ │ │ └── chat.html # Chat interface
│ │ └── application.properties
│ └── test/ # JUnit 5 test suite (mirrors the main tree)
└── frontend/ # LibGDX frontend (desktop)
├── build.gradle # Root Gradle config
├── core/ # Shared code
│ └── src/com/accordion/
│ ├── AccordionGame.java
│ ├── config/ # Configuration
│ ├── screen/ # Login & Chat screens
│ └── websocket/ # WebSocket client
└── desktop/ # Desktop launcher
└── src/com/accordion/desktop/
└── DesktopLauncher.java
cd backend
mvn clean installcd webapp
mvn clean packagecd frontend
./gradlew buildserver.port=8080
spring.datasource.url=jdbc:h2:mem:chatdb
spring.h2.console.enabled=trueThe backend also reports that it is in use to the project's usage service; the switch for
that is USAGE_REPORTING_ENABLED — see Usage reporting.
The desktop client's WebSocket endpoint comes from AppConfig.getWebSocketUrl(),
which defaults to ws://localhost:8080/ws and can be overridden by the
accordion.websocket.url system property of the client JVM. The desktop:run
Gradle task forwards every -Daccordion.* flag to the JVM it launches:
./gradlew desktop:run -Daccordion.websocket.url=ws://yourserver.com:8080/wsSee MVP.md for the complete roadmap and architecture details.
- ✅ Multiple chat rooms/channels
- ✅ Channel creation and management
- ✅ Channel-specific message history
- ✅ Password-based authentication with JWT (Spring Security)
- ✅ Typing indicators (web application)
- Desktop client parity with the web application (JWT authentication, channels, typing indicators)
- Private direct messages
- User online/offline status
- Message search and pagination
- PostgreSQL/MySQL support for production
- File/image sharing
- MVP.md - Complete MVP documentation including:
- Architecture details
- API documentation
- Setup instructions
- Feature roadmap
- Troubleshooting guide
Usage reporting is on by default: the backend reports that it is in use to the
trace usage service at
https://trace.danielstephenson.dev, so it is known how many Accordion servers are running
and on which versions, and it sends exactly two kinds of event — startup, once the backend
is ready (the program name accordion and its version), and channel-created, each time a
channel is created through the API (the program name and its version). Nothing else is sent: nothing
about users, messages, channel names, IP addresses, the host, or anything typed into a
channel. The send happens on its own daemon thread, never throws and never blocks startup; a
trace server that is unreachable is a dropped report, not an error. The backend logs one INFO
line at every start saying whether reporting is on and, if not, why:
Usage reporting is on: accordion sends its name, version and a random installation ID with a startup event and a channel-created event to https://trace.danielstephenson.dev - nothing about users, messages or channels. Turn it off with USAGE_REPORTING_ENABLED=false (usage-reporting.enabled), or with TRACE_USAGE_REPORTING=off in the environment. Details: https://danielstephenson.dev/usage-reporting
Every event also carries a random installation ID as the tag install, so the number of
running deployments can be counted rather than events. It is the value of TRACE_INSTALL_ID
when that is set (to pin one ID per deployment), and otherwise a random UUID written the first
time reporting runs to <user data dir>/accordion/trace-install-id ($XDG_DATA_HOME or
~/.local/share on Linux, ~/Library/Application Support on macOS, %APPDATA% on Windows)
and reused after that. In a container that directory is usually not on a volume, so a recreated
container counts as a new installation unless TRACE_INSTALL_ID is set. The ID identifies no
person, account, host or address; delete the file to get a new one. Every opt-out also stops
it: when reporting is off, no ID is made up and the file is neither read nor written.
To turn it off, any one of these is enough:
USAGE_REPORTING_ENABLED=falsein.env(Docker Compose) or in the backend's environmentusage-reporting.enabled=falseinbackend/src/main/resources/application.propertiesTRACE_USAGE_REPORTING=off(alsofalse,0,no) in the environment — the switch every trace client honours, checked before the backend's own settingDO_NOT_TRACK=1(alsotrue,yes) in the environment, per consoledonottrack.com
Every switch fails closed, so an opt-out is never read as "on": USAGE_REPORTING_ENABLED
keeps reporting on only for true, on, yes or 1 (any case) and turns it off for
anything else, blank or a typo included; TRACE_USAGE_REPORTING set to anything but blank
or one of those values turns it off; DO_NOT_TRACK set to anything but blank, 0, false,
off or no turns it off.
USAGE_REPORTING_ENDPOINT points it at a different trace server, and USAGE_REPORTING_KEY
supplies the key that server expects. Tests never report.
Details on what trace collects and why: https://danielstephenson.dev/usage-reporting
This is an MVP prototype. Contributions are welcome for:
- Bug fixes
- Performance improvements
- Documentation updates
- Feature implementations from the roadmap
This project is licensed under the Stephenson Software Non-Commercial License (Stephenson-NC).
© 2025 Daniel McCoy Stephenson. All rights reserved.
You may use, modify, and share this software for non-commercial purposes only.
Commercial use is prohibited without explicit written permission from the copyright holder.
Full license text: Stephenson-NC License
SPDX Identifier: Stephenson-NC
For issues or questions, please open an issue on GitHub.

