Bruno GaoandQwen-Coder
a977951366
- Add start_app.sh script for one-click application startup - Add STARTUP_GUIDE.md with detailed startup instructions - Add init_and_start.sh alternative startup script - Fix JpaAuditingConfig to remove duplicate @EnableJpaRepositories - Update application-dev.yml to use environment variables for database config - Fix TenantContextFilterTest to use proper MockFilterChain implementation - Fix OrderAuditIntegrationTest to use correct TenantScope constructor - Fix OrderCacheIntegrationTest to use correct method names and return types - Add tmpl-admin frontend project - Update OrderControllerTest with correct method mappings and return codes Co-authored-by: Qwen-Coder <[email protected]>
123 lines
3.2 KiB
Markdown
123 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
mvn clean package -DskipTests
|
|
```
|
|
|
|
#### 2. Set Up Database
|
|
|
|
Make sure PostgreSQL is running, then:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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. |