WebSocket Demo Application

This project demonstrates a WebSocket-based chat application with a Vue.js frontend and Spring Boot backend.

Project Structure

• websocket-vue-front/: Vue.js 3 frontend with TypeScript
• websocket-spring-back/: Spring Boot backend with WebSocket support

Features

• Real-time bidirectional communication using WebSockets
• Structured message passing with different message types
• Username management and user presence notifications
• User count tracking and display
• Automatic reconnection on connection loss
• Ping/pong mechanism to keep connections alive
• Message timestamps and formatted display
• Responsive UI that works on mobile and desktop
• Flexible deployment options (standalone, integrated, or Docker)

Running the Application

This application can run in three modes:

1. Standalone Mode (Development)

In this mode, the frontend and backend run as separate applications:

• Frontend runs on: http://localhost:5173
• Backend runs on: http://localhost:8080/api
• WebSocket connects to: ws://localhost:8080/api/chat

To run in standalone mode:

# Option 1: Use the provided script
./run-standalone.sh

# Option 2: Start each application manually
# Terminal 1 - Start backend
cd websocket-spring-back
API_CONTEXT_PATH=/api ./mvnw spring-boot:run

# Terminal 2 - Start frontend
cd websocket-vue-front
npm run dev

2. Integrated Mode (Production)

In this mode, the Vue.js frontend is built and served by the Spring Boot application:

• Both frontend and backend run on: http://localhost:8080
• WebSocket connects to: ws://localhost:8080/chat

To run in integrated mode:

# Option 1: Use the provided script
./run-integrated.sh

# Option 2: Build and run manually
# Build frontend and copy to backend resources
cd websocket-vue-front
npm run dist

# Run the integrated application
cd ../websocket-spring-back
./mvnw spring-boot:run

3. Docker Mode (Production)

In this mode, the entire application runs in a Docker container:

• Both frontend and backend run on: http://localhost:8080
• WebSocket connects to: ws://localhost:8080/chat (default) or ws://localhost:8080/api/chat (with context path)

To run in Docker mode:

# Build the Docker image with no context path (integrated mode)
./build-docker.sh

# Run the Docker container
docker-compose up

# Or, build with a context path
./build-docker.sh latest "/api"
docker-compose up

# Run in detached mode
docker-compose up -d

The Docker build process uses a single-stage build to:

1. Install Node.js and npm in the Maven container
2. Build the Vue.js frontend directly into the Spring Boot's static resources directory
3. Build the Spring Boot application with the integrated frontend
4. Create a lightweight JRE container for running the application

The application will be accessible at http://localhost:8080

4. Building for Production

To build a production-ready JAR file containing both applications:

./build-integrated.sh

The resulting JAR file can be found in websocket-spring-back/target/ and can be run with:

java -jar path/to/file.jar

Build Process Management

The project includes several scripts to manage the build process:

• run-standalone.sh: Runs both frontend and backend in development mode
• run-integrated.sh: Builds the frontend and integrates it with the backend
• build-integrated.sh: Creates a production JAR with frontend included
• build-docker.sh: Builds a Docker image containing the entire application

All scripts include automatic cleaning of the src/main/resources/static directory to prevent issues with stale files. The static directory is excluded from git tracking (except for a .gitkeep file) to avoid conflicts.

Technologies Used

• Frontend:

  • Vue.js 3
  • TypeScript
  • Vite
  • Vue Router

• Backend:

  • Spring Boot 3.4
  • Spring WebSocket
  • Java 21
  • Jackson for JSON processing
  • Lombok for reducing boilerplate code

• Deployment:

  • Docker
  • Docker Compose (with Java 21 support)

Communication Protocol

The application uses a structured message format for WebSocket communication:

{
  "name": "Username",
  "message": "Message content",
  "timestamp": "2025-03-27T10:15:30.123Z",
  "type": "CHAT"
}

Message types include:

• CHAT: Regular chat messages
• JOIN: User joined notifications
• LEAVE: User left notifications
• ERROR: Error messages
• USER_COUNT: User count updates
• PING/PONG: Connection heartbeat

Configuration

• Frontend configuration is in .env.development and .env.production files
• Backend configuration is in application.properties and application-docker.properties
• Docker configuration is in Dockerfile and docker-compose.yml