java21-template/STARTUP_GUIDE.md

Java Service Template - Quick Start Guide

This guide explains how to initialize the database, establish Flyway baseline, and start the application.

Prerequisites

Before running the application, ensure you have:

1. Java 21 installed
2. Maven installed
3. PostgreSQL server running locally (or configure external access)
4. Redis server running locally (or configure external access)

Quick Start Script

The project includes a script to automate the entire setup process:

Using the Start Script

# Make the script executable (if not already done)
chmod +x start_app.sh

# Run the complete setup and start the application
./start_app.sh

This script will:

1. Check PostgreSQL connectivity
2. Build the application using Maven
3. Create the database named java_template
4. Establish Flyway baseline and run migrations
5. Start the application

Manual Steps (Alternative)

If you prefer to run the steps manually:

1. Build the Application

mvn clean package -DskipTests

2. Set Up Database

Make sure PostgreSQL is running, then:

# Connect to PostgreSQL as superuser
psql -h localhost -p 5432 -U postgres

# Create the database
CREATE DATABASE java_template;
\q

3. Run the Application with Flyway

# The application will automatically run Flyway migrations on startup
java -jar tmpl-api/target/tmpl-api-0.1.0-SNAPSHOT.jar \
  -Dspring.profiles.active=dev \
  -DDB_HOST=localhost \
  -DDB_PORT=5432 \
  -DDB_NAME=java_template \
  -DDB_USER=postgres \
  -DDB_PASS=postgres

Configuration

The application uses the following default configuration:

• Database: PostgreSQL at localhost:5432, database name java_template
• Database User: postgres with password postgres
• Redis: At localhost:6379
• Application Port: 8080
• Management Port: 8080 (in dev profile, merged with app port)

These can be overridden using environment variables:

• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS
• REDIS_HOST, REDIS_PORT

Database Migrations

The application includes Flyway migrations:

• V1__init.sql: Basic schema initialization
• V2__create_order.sql: Creates the order table with audit columns

Flyway will automatically apply these migrations on application startup.

Accessing the Application

Once started, the application will be available at:

• Main endpoint: http://localhost:8080
• API Documentation: http://localhost:8080/swagger-ui.html
• Health check: http://localhost:8080/actuator/health
• Metrics: http://localhost:8080/actuator/prometheus

Troubleshooting

Common Issues:

1. PostgreSQL not accessible: Make sure PostgreSQL server is running and accessible
2. Database permissions: Ensure the database user has CREATE privileges
3. Port conflicts: Check if ports 8080 and 6379 are available
4. Connection timeouts: Verify network connectivity to database and Redis

Environment Variables:

You can customize the configuration using environment variables:

export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=java_template
export DB_USER=postgres
export DB_PASS=postgres
export REDIS_HOST=localhost
export REDIS_PORT=6379

Then run the application normally.