Backend Deployment

This guide covers manual deployment of the Justina backend without Docker. The backend is built with Spring Boot 4.0.2 and Java 21.

Prerequisites

Ensure you have the following installed:

Java Development Kit (JDK) 21+
Maven 3.9+ (optional, can use included wrapper)
PostgreSQL 15+ (for production)

See the Prerequisites page for detailed installation instructions.

Clone Repository

Clone the Source Code

git clone <repository-url>
cd S02-26-Equipo-24-Web-App-Development/backend

Verify Project Structure

ls -la

You should see:

pom.xml - Maven configuration
mvnw - Maven wrapper
src/ - Source code directory
Dockerfile - Docker configuration (not needed for manual deployment)

Configure Environment

Set Required Environment Variables

The backend requires specific environment variables to run. See the Environment Variables page for complete documentation.

# Required
export JWT_SECRET_KEY="dev-secret-key-change-in-production"
export PORT=8080

# H2 Database (default)
export SPRING_DATASOURCE_URL="jdbc:h2:mem:justina"
export SPRING_DATASOURCE_USERNAME="sa"
export SPRING_DATASOURCE_PASSWORD=""
export SPRING_DATASOURCE_DRIVER_CLASS_NAME="org.h2.Driver"
export SPRING_JPA_HIBERNATE_DDL_AUTO="create-drop"
export SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT="org.hibernate.dialect.H2Dialect"

Generate a strong JWT_SECRET_KEY for production:

openssl rand -base64 32

Setup PostgreSQL Database (Production)

Create Database

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE justina;

# Create user
CREATE USER justina_user WITH PASSWORD 'your_secure_password';

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE justina TO justina_user;

Verify Connection

psql -U justina_user -d justina -h localhost

Build Application

Using Maven Wrapper (Recommended)

The project includes a Maven wrapper that doesn’t require Maven installation:

Make Wrapper Executable

chmod +x mvnw

Clean and Build

./mvnw clean install -DskipTests

This command:

Downloads dependencies
Compiles source code
Runs unit tests (skip with -DskipTests)
Creates JAR file in target/ directory

Expected output:

[INFO] BUILD SUCCESS
[INFO] Total time: 45.123 s

Verify JAR Creation

ls -lh target/*.jar

You should see:

Justina-0.0.1-SNAPSHOT.jar

Using Installed Maven

If you have Maven installed system-wide:

mvn clean install -DskipTests

Run Application

Run with Maven (Development)

Run directly with Maven for development:

./mvnw spring-boot:run

The application will:

Start Spring Boot
Initialize H2/PostgreSQL database
Create default users (surgeon_master, ia_justina)
Listen on port 8080

Run JAR File (Production)

Run the compiled JAR for production:

java -jar target/Justina-0.0.1-SNAPSHOT.jar

Ensure environment variables are set before running the JAR.

Run with Custom Port

java -jar target/Justina-0.0.1-SNAPSHOT.jar --server.port=8888

Verify Deployment

Check Application Health

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

You should see the Swagger UI interface.

Test Authentication Endpoint

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "surgeon_master",
    "password": "justina2024"
  }'

Expected response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "surgeon_master",
  "role": "ROLE_SURGEON"
}

Check WebSocket Endpoint

The WebSocket is available at:

ws://localhost:8080/ws/simulation

Default Users

The backend automatically creates default users on first startup:

Username	Password	Role
`surgeon_master`	`justina2024`	`ROLE_SURGEON`
`ia_justina`	`ia_secret_2024`	`ROLE_IA`

Change these default passwords immediately in production!

Access API Documentation

Once running, access the interactive API documentation:

Tool	URL
Swagger UI	`http://localhost:8080/swagger-ui/index.html`
OpenAPI JSON	`http://localhost:8080/v3/api-docs`
OpenAPI YAML	`http://localhost:8080/v3/api-docs.yaml`

Running as a Service

Systemd Service (Linux)

Create /etc/systemd/system/justina-backend.service:

[Unit]
Description=Justina Backend Service
After=network.target postgresql.service

[Service]
Type=simple
User=justina
WorkingDirectory=/opt/justina/backend
Environment="JWT_SECRET_KEY=your-secret-key"
Environment="SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/justina"
Environment="SPRING_DATASOURCE_USERNAME=justina_user"
Environment="SPRING_DATASOURCE_PASSWORD=your_password"
ExecStart=/usr/bin/java -jar /opt/justina/backend/target/Justina-0.0.1-SNAPSHOT.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Manage the service:

# Reload systemd
sudo systemctl daemon-reload

# Enable auto-start
sudo systemctl enable justina-backend

# Start service
sudo systemctl start justina-backend

# Check status
sudo systemctl status justina-backend

# View logs
sudo journalctl -u justina-backend -f

Production Optimization

JVM Options

Optimize JVM for production:

java -Xms512m -Xmx2g \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -jar target/Justina-0.0.1-SNAPSHOT.jar

Application Properties

For production, consider tuning application.properties or using profiles:

java -jar target/Justina-0.0.1-SNAPSHOT.jar --spring.profiles.active=production

Troubleshooting

Port Already in Use

Check what’s using port 8080:

lsof -i :8080
# or
netstat -tulpn | grep 8080

Kill the process or use a different port:

export PORT=8888

Database Connection Failed

Verify PostgreSQL is running:

sudo systemctl status postgresql

Test connection:

psql -U justina_user -d justina -h localhost

Check firewall rules:

sudo ufw status

JWT Token Errors

Ensure JWT_SECRET_KEY is set and is at least 256 bits (32 characters):

echo $JWT_SECRET_KEY | wc -c

Build Failures

Clear Maven cache and rebuild:

./mvnw clean
rm -rf ~/.m2/repository/project/Justina
./mvnw install

Monitoring and Logs

View Application Logs

# If running in terminal
./mvnw spring-boot:run

# If running as JAR
java -jar target/Justina-0.0.1-SNAPSHOT.jar > app.log 2>&1 &
tail -f app.log

Enable SQL Logging

export SPRING_JPA_SHOW_SQL=true

Next Steps

After deploying the backend:

Deploy Frontend - Deploy the Next.js frontend
Deploy AI Service - Deploy the AI analysis service
Configure reverse proxy (Nginx, Apache)
Set up SSL certificates
Configure monitoring and alerting
Set up automated backups

Additional Resources

Environment Variables - Complete variable reference
Docker Deployment - Container-based deployment
Backend source: /backend/README.md
Tech stack: Spring Boot 4.0.2, Java 21, PostgreSQL 15+

Setup

Components

Backend Deployment

Prerequisites

Clone Repository

Configure Environment

Set Required Environment Variables

Setup PostgreSQL Database (Production)

Build Application

Using Maven Wrapper (Recommended)

Using Installed Maven

Run Application

Run with Maven (Development)

Run JAR File (Production)

Run with Custom Port

Verify Deployment

Default Users

Access API Documentation

Running as a Service

Systemd Service (Linux)

Production Optimization

JVM Options

Application Properties

Troubleshooting

Monitoring and Logs

View Application Logs

Enable SQL Logging

Next Steps

Additional Resources

Build docs developers (and LLMs) love

Setup

Components

​Prerequisites

​Clone Repository

​Configure Environment

​Set Required Environment Variables

​Setup PostgreSQL Database (Production)

​Build Application

​Using Maven Wrapper (Recommended)

​Using Installed Maven

​Run Application

​Run with Maven (Development)

​Run JAR File (Production)

​Run with Custom Port

​Verify Deployment

​Default Users

​Access API Documentation

​Running as a Service

​Systemd Service (Linux)

​Production Optimization

​JVM Options

​Application Properties

​Troubleshooting

​Monitoring and Logs

​View Application Logs

​Enable SQL Logging

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Clone Repository

Configure Environment

Set Required Environment Variables

Setup PostgreSQL Database (Production)

Build Application

Using Maven Wrapper (Recommended)

Using Installed Maven

Run Application

Run with Maven (Development)

Run JAR File (Production)

Run with Custom Port

Verify Deployment

Default Users

Access API Documentation

Running as a Service

Systemd Service (Linux)

Production Optimization

JVM Options

Application Properties

Troubleshooting

Monitoring and Logs

View Application Logs

Enable SQL Logging

Next Steps

Additional Resources