Mboascout Backend

Mboascout is a comprehensive backend service built with Spring Boot 3. It leverages a modern tech stack to provide a robust, scalable, and secure API.

Tech Stack

• Java 21
• Spring Boot 3.5.9 (Web, Data JPA, Data MongoDB, Data Redis Reactive, Security, Mail)
• Databases: PostgreSQL (Relational) & MongoDB (Document)
• Caching: Redis
• Messaging: Apache Kafka
• Security: Spring Security with JWT (JSON Web Tokens)
• Cloud Storage: AWS S3 with CloudFront CDN
• API Documentation: Springdoc OpenAPI (Swagger UI)
• Database Migrations: Liquibase
• Object Mapping: MapStruct
• Build Tool: Maven

Prerequisites

Before you begin, ensure you have the following installed on your local machine:

• Java 21 (JDK 21)
• Maven 3.8+ (or use the provided mvnw wrapper)
• PostgreSQL (running on port 5432)
• MongoDB (running on port 27017)
• Redis (running on port 6379)
• Apache Kafka (running on port 9092)

Alternatively, you can use Docker and Docker Compose to spin up the required databases and message brokers.

Environment Configuration

The application relies on environment variables for configuration. A .env file must be present in the root directory.

Create a .env file in the root directory and configure the following properties based on your local setup:

# --- POSTGRESQL (Primary DB) ---
DB_URL=jdbc:postgresql://localhost:5432/mboa
DB_USERNAME=root
DB_PASSWORD=password

# --- MONGODB (Document DB) ---
MONGO_HOST=localhost
MONGO_PORT=27017
MONGO_DATABASE=mboa
MONGO_USERNAME=root
MONGO_PASSWORD=password

# --- KAFKA (Messaging) ---
KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# --- SERVER SETTINGS ---
SERVER_PORT=8080

# --- S3 Storage Configuration ---
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_STORAGE_BUCKET_NAME=mboascout
AWS_REGION=eu-north-1
AWS_S3_REGION_NAME=eu-north-1

# --- CloudFront Configuration ---
AWS_CLOUDFRONT_DOMAIN=your_cloudfront_domain.cloudfront.net
AWS_CLOUDFRONT_KEY_PAIR_ID=your_key_pair_id
AWS_CLOUDFRONT_PRIVATE_KEY_PATH=/path/to/private_key.pem

# --- Email Configuration ---
EMAIL_USERNAME=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
DEFAULT_FROM_EMAIL=Mboascout <your_email@gmail.com>
EMAIL_PORT=587
EMAIL_HOST=smtp.gmail.com

# --- Security ---
JWT_SECRET=your_super_secret_jwt_key_here_minimum_32_chars
JWT_EXPIRATION=86400000

# --- CORS ---
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,https://mboascout.com

# --- Redis ---
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_USER=root
REDIS_PASSWORD=password

# --- INITIAL USERS ---
ADMIN_EMAIL=admin@mboascout.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=password
TEST_USER_EMAIL=test@mboascout.com
TEST_USER_USERNAME=testuser
TEST_USER_PASSWORD=password
TEST_TAGGER_EMAIL=tagger@mboascout.com
TEST_TAGGER_USERNAME=tagger
TEST_TAGGER_PASSWORD=password

(Note: Never commit your actual .env file containing sensitive production credentials to version control.)

🛠️ Running the Application Locally

1. Start infrastructure services: Ensure PostgreSQL, MongoDB, Redis, and Kafka are running and accessible at the ports specified in your .env file.

   • Create the mboa database in PostgreSQL and MongoDB if they don't exist yet.

2. Build the project: Use the Maven wrapper to build the application and skip tests initially to verify the build.

   ./mvnw clean install -DskipTests

3. Run the Spring Boot application:

   ./mvnw spring-boot:run

The application will start on the port specified in .env (default is 8080).

API Documentation

Once the application is running, you can access the interactive API documentation (Swagger UI) provided by Springdoc OpenAPI:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

Database Migrations

This project uses Liquibase for relational database migrations. When the application starts, Liquibase will automatically apply any pending changelogs to your PostgreSQL database. Ensure your database credentials and URL are correctly set in the .env file.

Testing

To run the test suite, which includes tests for Spring Context, Web layer, Data layers, and Kafka integrations:

./mvnw test

Deployment

The application includes a deploy.sh script for deployment operations. Review and modify the script according to your target deployment environment.

To package the application for production:

./mvnw clean package -DskipTests

The compiled .jar file will be located in the target/ directory.