Skip to main content
This quickstart guide walks you through setting up the Chat Server, creating your first user, and making your first API call.

​
Prerequisites

Before you begin, ensure you have:
  • Java 25 or later - Check your version with java -version
  • Gradle - Included via Gradle wrapper in the repository
  • Git - To clone the repository

​
Installation

1

Clone the repository

Clone the Chat Server repository from GitHub:
git clone https://github.com/brys0/CompSci330Final.git
cd CompSci330Final
2

Navigate to the server directory

The server code is located in the server/ subdirectory:
cd server
3

Start the server

Use the Gradle wrapper to build and run the Spring Boot server:
./gradlew bootRun
The server will start on http://localhost:8080. You should see output similar to:
Started APIServerApplication in 3.245 seconds
The server uses an embedded H2 database by default, so no additional database setup is required for local development.

​
Your first API calls

Now that your server is running, let’s create a user and authenticate.
1

Register a new user

Create your first user account using the registration endpoint:
cURL
curl -X POST http://localhost:8080/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "mySecurePass123"
  }'
The server returns a JWT token valid for 30 days:
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhbGljZSIsImlhdCI6MTcwOTU2NzgwMCwiZXhwIjoxNzEyMTU5ODAwfQ.XYZ...
Save this token - you’ll need it for authenticated requests.
Username requirements: 2-8 characters
Password requirements: Minimum 6 charactersThese constraints are defined in Configuration.java (MIN_USERNAME_LENGTH=2, MAX_USERNAME_LENGTH=8, MIN_PASSWORD_LENGTH=6).
2

Get your user profile

Use the JWT token to fetch your user information:
cURL
curl -X GET http://localhost:8080/users/@me \
  -H "Authorization: YOUR_JWT_TOKEN_HERE"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "alice",
  "status": 0
}
The response uses the SafeUser DTO, which excludes sensitive fields like the password hash.
All authenticated endpoints require the Authorization header with your JWT token. Requests without a valid token will receive a 401 Unauthorized response.
3

Send a friend request

Register a second user (e.g., “bob”) and send a friend request from alice to bob:
cURL
# First, register bob
curl -X POST http://localhost:8080/users/register \
  -H "Content-Type: application/json" \
  -d '{"username": "bob", "password": "bobSecure456"}'

# Then, send friend request as alice
curl -X POST http://localhost:8080/users/@me/relationships/bob \
  -H "Authorization: ALICE_JWT_TOKEN"

{
  "id": "rel-123456",
  "requester": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "username": "alice",
    "status": 0
  },
  "requestee": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "username": "bob",
    "status": 0
  },
  "status": "PENDING"
}
The relationship starts in PENDING status. Bob must accept it to change the status to ACCEPTED.
4

Accept the friend request

Log in as bob and accept the incoming friend request:
cURL
# Bob sends a friend request to alice (accepting the incoming request)
curl -X POST http://localhost:8080/users/@me/relationships/alice \
  -H "Authorization: BOB_JWT_TOKEN"

{
  "id": "rel-123456",
  "requester": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "username": "alice",
    "status": 0
  },
  "requestee": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "username": "bob",
    "status": 0
  },
  "status": "ACCEPTED"
}
The status changes to ACCEPTED, and both users are now friends.

​
Explore the API

You’re now ready to explore the full API:

OpenAPI Documentation

Interactive API documentation with Swagger UI

Authentication Endpoints

Register, login, and manage user accounts

Relationship Endpoints

Send, accept, and manage friend requests

Core Concepts

Learn about JWT tokens, relationships, and messaging

​
What’s next?

1

Configure the server

Set up environment variables, database options, and security settings.Server Configuration →
2

Set up the JavaFX client

Install and run the desktop client application.Client Installation →
3

Understand the architecture

Learn about the layered architecture, data models, and authentication flow.Architecture Overview →

​
Troubleshooting

If port 8080 is occupied, you can change it by setting the SERVER_PORT environment variable:
SERVER_PORT=8081 ./gradlew bootRun
Or update application.properties with:
server.port=8081
This error occurs when:
  • The Authorization header is missing
  • The JWT token is invalid or expired (tokens expire after 30 days)
  • The JWT_SECRET environment variable changed after token generation
Solution: Register a new user or login again to get a fresh token.
If you see database errors, delete the local database file and restart:
rm -f server/data.db
./gradlew bootRun
For production deployment, always set a secure JWT_SECRET environment variable. The default value is only for local development.

Build docs developers (and LLMs) love

Get started for freeTalk to us