Installation

This guide provides comprehensive instructions for installing and configuring the DriveX Backend API in both development and production environments.

System Requirements

Minimum Requirements

Java

Java 17 or higher (LTS recommended)

Maven

Maven 3.9+ for dependency management

MySQL

MySQL 8.0+ for data persistence

Memory

Minimum 2GB RAM, 4GB recommended

Recommended for Production

CPU: 2+ cores
RAM: 4GB minimum, 8GB recommended
Storage: 20GB available disk space
OS: Linux (Ubuntu 20.04+, CentOS 8+) or Windows Server 2019+

Prerequisites Installation

Install Java 17

Download and install Java 17 from Eclipse Adoptium:

# Add Adoptium repository
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -
echo "deb https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | sudo tee /etc/apt/sources.list.d/adoptium.list

# Install Java 17
sudo apt update
sudo apt install temurin-17-jdk

# Verify installation
java -version

Expected output:

openjdk version "17.0.x" 2024-xx-xx
OpenJDK Runtime Environment Temurin-17.0.x

Install Maven

Download and install Apache Maven:

sudo apt update
sudo apt install maven

# Verify installation
mvn -version

Install MySQL

Install MySQL database server:

sudo apt update
sudo apt install mysql-server

# Start MySQL service
sudo systemctl start mysql
sudo systemctl enable mysql

# Secure installation
sudo mysql_secure_installation

Configure MySQL Database

Create the database and user for DriveX:

# Connect to MySQL
mysql -u root -p

# Create database
CREATE DATABASE drivex CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Create user (optional, for security)
CREATE USER 'drivex_user'@'localhost' IDENTIFIED BY 'secure_password';

# Grant privileges
GRANT ALL PRIVILEGES ON drivex.* TO 'drivex_user'@'localhost';
FLUSH PRIVILEGES;

# Verify database creation
SHOW DATABASES;
USE drivex;

Replace secure_password with a strong password. Never use default passwords in production.

Application Installation

Clone the Repository

Clone the DriveX Backend repository:

git clone https://github.com/rofaba/drivex-backend.git
cd drivex-backend

Configure Application Properties

Edit src/main/resources/application.properties with your environment settings:

# Application Name
spring.application.name=DriveX-backend

# Database Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/drivex
spring.datasource.username=drivex_user
spring.datasource.password=secure_password
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# JPA/Hibernate Configuration
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.database-platform=org.hibernate.dialect.MySQLDialect

# Server Configuration
server.servlet.context-path=/api
server.port=${PORT:8080}
server.address=0.0.0.0

The ${PORT:8080} syntax means the server will use the PORT environment variable if set, otherwise default to 8080.

Configuration Options Explained

Property	Description	Default
`spring.datasource.url`	JDBC connection URL to MySQL	`jdbc:mysql://localhost:3306/drivex`
`spring.jpa.hibernate.ddl-auto`	Database schema generation strategy	`update`
`spring.jpa.show-sql`	Log SQL queries to console	`true`
`server.servlet.context-path`	Base path for all endpoints	`/api`
`server.port`	HTTP server port	`8080`
`server.address`	Server bind address	`0.0.0.0`

For production, set spring.jpa.show-sql=false to avoid logging sensitive data.

Build the Application

Compile and package the application:

# Clean build with tests
mvn clean install

# Or skip tests for faster build
mvn clean install -DskipTests

This generates the JAR file: target/DriveX-0.0.1-SNAPSHOT.jar

The build process includes:

Dependency resolution from pom.xml
Java compilation with annotation processing (Lombok)
Resource bundling
JAR packaging with embedded Tomcat

Run the Application

Start the application using one of these methods:

mvn spring-boot:run

Verify Installation

Test the API to ensure it’s running correctly:

# Check server health
curl http://localhost:8080/api/vehicles

# Expected response: [] or list of vehicles

You should see logs indicating successful startup:

2026-03-01 10:00:00.000  INFO --- [main] c.D.D.DriveXBackendApplication
Started DriveXBackendApplication in 3.456 seconds (JVM running for 4.123)

Production Deployment

Using Systemd Service (Linux)

Create a systemd service for automatic startup and management:

Create Service User

sudo useradd -r -s /bin/false drivex
sudo mkdir -p /opt/drivex
sudo cp target/DriveX-0.0.1-SNAPSHOT.jar /opt/drivex/app.jar
sudo chown -R drivex:drivex /opt/drivex

Create Service File

Create /etc/systemd/system/drivex.service:

[Unit]
Description=DriveX Backend API
After=syslog.target network.target mysql.service

[Service]
User=drivex
Group=drivex
WorkingDirectory=/opt/drivex
ExecStart=/usr/bin/java -jar /opt/drivex/app.jar
SuccessExitStatus=143
StandardOutput=journal
StandardError=journal
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and Start Service

sudo systemctl daemon-reload
sudo systemctl enable drivex
sudo systemctl start drivex

# Check status
sudo systemctl status drivex

# View logs
sudo journalctl -u drivex -f

Docker Deployment

For containerized deployment:

Build Docker Image

The project includes a multi-stage Dockerfile:

# Etapa 1: Build with Maven
FROM maven:3.9-eclipse-temurin-17-alpine AS build
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn -DskipTests clean package

# Etapa 2: Runtime image
FROM eclipse-temurin:17-jdk
WORKDIR /app
COPY --from=build /app/target/DriveX-0.0.1-SNAPSHOT.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

Build the image:

docker build -t drivex-backend:latest .

Run with Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: drivex
      MYSQL_USER: drivex_user
      MYSQL_PASSWORD: secure_password
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    image: drivex-backend:latest
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/drivex
      SPRING_DATASOURCE_USERNAME: drivex_user
      SPRING_DATASOURCE_PASSWORD: secure_password
    ports:
      - "8080:8080"
    restart: unless-stopped

volumes:
  mysql-data:

Start services:

docker-compose up -d

# View logs
docker-compose logs -f api

Environment Variables

Override configuration using environment variables:

Variable	Description	Example
`PORT`	Server port	`8080`
`SPRING_DATASOURCE_URL`	Database connection URL	`jdbc:mysql://localhost:3306/drivex`
`SPRING_DATASOURCE_USERNAME`	Database username	`drivex_user`
`SPRING_DATASOURCE_PASSWORD`	Database password	`secure_password`
`SPRING_JPA_HIBERNATE_DDL_AUTO`	Schema generation	`update`, `validate`, `none`
`SPRING_JPA_SHOW_SQL`	Log SQL queries	`true`, `false`

Verification Checklist

After installation, verify the following:

Database Connection

Check application logs for successful database connection:

HikariPool-1 - Start completed.

API Endpoints

Test key endpoints:

curl http://localhost:8080/api/vehicles
curl http://localhost:8080/api/vehicles/brands

Table Creation

Verify Hibernate created tables:

USE drivex;
SHOW TABLES;

Expected tables: vehicles, users, rentals, favorites, vehicle_images

CORS Configuration

Test cross-origin requests if you have a frontend:

curl -X OPTIONS http://localhost:8080/api/vehicles \
  -H "Origin: http://localhost:3000" \
  -H "Access-Control-Request-Method: GET"

Security Considerations

Before deploying to production, review these security measures:

Change Default Passwords: Never use default or simple passwords
Enable HTTPS: Use a reverse proxy (Nginx, Apache) with SSL/TLS certificates
Firewall Rules: Restrict MySQL port (3306) to localhost only
Environment Variables: Store sensitive data in environment variables, not in application.properties
SQL Injection: The JPA layer provides protection, but always validate user input
Update Dependencies: Regularly update Spring Boot and dependencies for security patches

Troubleshooting

Application fails to start - Port already in use

Change the port or stop the conflicting process:

# Find process using port 8080
lsof -i :8080
# Or on Windows
netstat -ano | findstr :8080

# Kill the process or change port
PORT=8081 java -jar target/DriveX-0.0.1-SNAPSHOT.jar

Cannot connect to MySQL - Access denied

Verify MySQL credentials and permissions:

# Connect as root
mysql -u root -p

# Check user exists
SELECT User, Host FROM mysql.user WHERE User='drivex_user';

# Re-grant permissions if needed
GRANT ALL PRIVILEGES ON drivex.* TO 'drivex_user'@'localhost';
FLUSH PRIVILEGES;

Hibernate schema validation fails

If you get schema validation errors:

Drop and recreate database:

DROP DATABASE drivex;
CREATE DATABASE drivex CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Or change ddl-auto to recreate tables:

spring.jpa.hibernate.ddl-auto=create-drop

create-drop will delete all data on restart. Use only in development!

Maven build fails - dependency resolution

Clear Maven cache and retry:

# Clear local repository cache
rm -rf ~/.m2/repository

# Force update dependencies
mvn clean install -U

Lombok compilation errors

Ensure Lombok annotation processor is configured in pom.xml (line 87-93):

<annotationProcessorPaths>
    <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.32</version>
    </path>
</annotationProcessorPaths>

If using an IDE, install the Lombok plugin:

IntelliJ IDEA: Settings → Plugins → Search “Lombok”
Eclipse: Download lombok.jar and run it to install

Next Steps

Quickstart Guide

Make your first API call

API Reference

Explore all endpoints

Get Started

Core Concepts

Guides

System Requirements

Minimum Requirements

Java

Maven

MySQL

Memory

Recommended for Production

Prerequisites Installation

Application Installation

Configuration Options Explained

Production Deployment

Using Systemd Service (Linux)

Docker Deployment

Environment Variables

Verification Checklist

Security Considerations

Troubleshooting

Next Steps

Quickstart Guide

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​System Requirements

​Minimum Requirements

Java

Maven

MySQL

Memory

​Recommended for Production

​Prerequisites Installation

​Application Installation

​Configuration Options Explained

​Production Deployment

​Using Systemd Service (Linux)

​Docker Deployment

​Environment Variables

​Verification Checklist

​Security Considerations

​Troubleshooting

​Next Steps

Quickstart Guide

API Reference

Build docs developers (and LLMs) love

System Requirements

Minimum Requirements

Recommended for Production

Prerequisites Installation

Application Installation

Configuration Options Explained

Production Deployment

Using Systemd Service (Linux)

Docker Deployment

Environment Variables

Verification Checklist

Security Considerations

Troubleshooting

Next Steps