Running the server

​

Start the server

​

Using Gradle (recommended for development)

./gradlew bootRun

• Compile the application if needed
• Start the Spring Boot application
• Enable hot reload with DevTools
• Display startup logs in the console

​

Using the JAR file (recommended for production)

java -jar build/libs/server-0.0.1-SNAPSHOT.jar

​

With custom environment variables

export JWT_SECRET="your-secure-base64-secret"
./gradlew bootRun

​

Verify the server is running

Started APIServerApplication in X.XXX seconds

Tomcat started on port 8080 (http)

curl http://localhost:8080/actuator/health

{"status":"UP"}

ls -la main.db

​

Access Swagger UI

​

Open Swagger UI

http://localhost:8080/swagger-ui.html

http://localhost:8080/swagger-ui/index.html

​

Features available in Swagger UI

• Interactive API documentation: View all available endpoints
• Request/response schemas: See data models and validation rules
• Try it out: Execute API requests directly from the browser
• Authentication: Test endpoints with JWT tokens

​

View OpenAPI specification

http://localhost:8080/v3/api-docs

​

Stopping the server

# Press Ctrl+C in the terminal where the server is running

​

Troubleshooting

​

Port already in use

Web server failed to start. Port 8080 was already in use.

1. Change the port: Create application.properties override or use command line:
   ./gradlew bootRun --args='--server.port=8081'
   
2. Kill the existing process:
   # Linux/macOS
   lsof -ti:8080 | xargs kill -9
   
   # Windows
   netstat -ano | findstr :8080
   taskkill /PID <PID> /F
   

​

Database locked error

SQLite database is locked

1. Check for multiple server instances: Ensure only one server process is accessing the database
2. Remove lock files: Delete main.db-shm and main.db-wal files (only when server is stopped)
3. Verify WAL mode: The server configures WAL mode automatically via connection-init-sql in application.properties:8-12

​

JWT authentication errors

JWT signature does not match

1. Verify JWT_SECRET: Ensure the environment variable is set correctly and is Base64-encoded
   echo $JWT_SECRET  # Linux/macOS
   echo %JWT_SECRET%  # Windows CMD
   
2. Check token expiration: Tokens expire after 30 days (Configuration.java:15). Generate a new token by logging in again.
3. Use the default secret: For development only, the server falls back to a default secret if JWT_SECRET is not set

​

Out of memory errors

java.lang.OutOfMemoryError: Java heap space

1. Increase heap size:
   # Using Gradle
   ./gradlew bootRun --args='-Xmx512m'
   
   # Using JAR
   java -Xmx512m -jar build/libs/server-0.0.1-SNAPSHOT.jar
   
2. Adjust SQLite cache: Reduce the cache size in application.properties from -10000 to -5000 (5MB)

​

Connection refused errors

Connection refused: localhost:8080

1. Bind to all interfaces: Add to application.properties:
   server.address=0.0.0.0
   
2. Check firewall settings: Ensure port 8080 is allowed through your firewall
3. Verify server is running: Check the process is active:
   # Linux/macOS
   ps aux | grep APIServerApplication
   
   # Windows
   tasklist | findstr java
   

​

Schema validation errors

Schema-validation: missing table

1. Delete the database: Remove main.db and restart (development only)
   rm main.db main.db-shm main.db-wal
   ./gradlew bootRun
   
2. Change DDL mode: In application.properties, temporarily use create instead of update:
   spring.jpa.hibernate.ddl-auto=create
   
   Using create will drop all existing tables and data. Only use in development.

​

Enable debug logging

./gradlew bootRun --args='--logging.level.org.uwgb.compsci330=DEBUG'

​

Production deployment

export JWT_SECRET=$(openssl rand -base64 64)

./gradlew clean build -x test

spring.datasource.url=jdbc:sqlite:/var/lib/chatserver/production.db