Setup and Installation
The current local setup is the Local setup page. The rest of this file describes an older single-module layout.
1.1. Minimum Requirements
- JDK 21 (Temurin/Adoptium, Zulu, Oracle — all fine)
- Maven 3.9+ or Gradle 8+ (demo repo uses Maven)
- Docker & Docker Compose (recommended for fast dev setup)
- IntelliJ IDEA (Community or Ultimate works with Spring Boot)
- (Optional) cURL or any HTTP client (Postman/Bruno/Insomnia)
1.2. Quick Installation
macOS
# JDK 21 + Maven + Docker
brew install --cask temurin
brew install maven
brew install --cask docker
Ubuntu/Debian
sudo apt update
sudo apt install -y wget unzip
# Temurin JDK 21
sudo apt install -y temurin-21-jdk || sudo apt install -y openjdk-21-jdk
sudo apt install -y maven
# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
Log out and log back in to apply the
dockergroup.
Windows
- Install Temurin 21 from Adoptium
- Install Maven (add
MAVEN_HOMEand%MAVEN_HOME%\binto PATH) - Install Docker Desktop
- Install IntelliJ IDEA
2. Clone the Project & Structure
git clone <repo-url> laptech-api
cd laptech-api
Main structure:
src/main/resources/
application.yml
application-dev.yml
application-staging.yml
application-prod.yml.example
Dockerfile
docker-compose.yml
.env.example
run.sh
3. Environment Variables Setup
3.1. Create .env from template
cp .env.example .env
# Then open .env and adjust values for your machine
Important variables:
- SPRING_PROFILES_ACTIVE:
dev/staging/prod - DB_URL, DB_USERNAME, DB_PASSWORD
- REDIS_HOST, REDIS_PORT, REDIS_PASSWORD (if used)
- Docker Compose vars:
MYSQL_DATABASE,MYSQL_USER,MYSQL_PASSWORD,MYSQL_ROOT_PASSWORD
Do not commit the real
.envfile.
3.2. Set environment variables in IntelliJ
-
Go to Run > Edit Configurations…
-
Select your Spring Boot run configuration
-
In the Configuration tab:
-
Environment variables → click
...→ add:SPRING_PROFILES_ACTIVE=dev(or staging/prod)DB_URL=jdbc:mysql://localhost:3306/mydb?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTCDB_USERNAME=app_userDB_PASSWORD=change_meREDIS_HOST=localhost,REDIS_PORT=6379,REDIS_PASSWORD=(if used)
-
(Optional. Program args:
--spring.profiles.active=staging
-
-
Click OK → Run
Tip: Install the EnvFile plugin → enable it → select
.envto auto-load your env vars.
4. Prepare MySQL & Redis
Two options:
4.1. Using Docker (fast — recommended)
# Start DB/Redis for local dev
docker compose up -d mysql redis
# View logs
docker compose logs -f mysql
docker compose logs -f redis
- MySQL runs at
localhost:3306(db based on.env) - Redis runs at
localhost:6379
Manually create DB/user (if needed):
docker exec -it mysql bash
mysql -u root -p$MYSQL_ROOT_PASSWORD
-- Inside MySQL shell:
CREATE DATABASE mydb_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'devuser'@'%' IDENTIFIED BY 'devpass';
GRANT ALL PRIVILEGES ON mydb_dev.* TO 'devuser'@'%';
FLUSH PRIVILEGES;
4.2. Using installed MySQL & Redis
- Ensure services are running on 3306 and 6379
- Create DB/user with SQL above
- Update
application-dev.ymlor environment variables accordingly
5. Spring Profiles Configuration
-
Default in
application.yml:spring.profiles.active=dev -
Override via:
- ENV:
SPRING_PROFILES_ACTIVE=staging - Program args:
--spring.profiles.active=staging - JVM args:
-Dspring.profiles.active=staging
- ENV:
Profiles:
- dev → local DB, DEBUG logs
- staging → ENV secrets, INFO logs
- prod → swagger disabled, WARN logs, secrets from ENV
6. Start the Application
6.1. Run locally with Maven
# Method 1: load .env then run
./run.sh
# Method 2: pure Maven
./mvnw spring-boot:run
# or
mvn spring-boot:run
If using Docker DB/Redis: App running on your machine → use
localhostApp running inside container → host becomesmysqlorredis
6.2. Build JAR & run
./mvnw -DskipTests package
java -jar target/*.jar
# or with profile:
java -Dspring.profiles.active=staging -jar target/*.jar
6.3. Run everything with Docker Compose (app + DB + Redis)
docker compose up --build
# or rebuild only the app service
docker compose up -d --build app
- App runs on:
http://localhost:8080 - Compose uses
SPRING_PROFILES_ACTIVE=stagingby default (configurable in.env)
7. Post-startup Checks
7.1. Actuator
curl http://localhost:8080/actuator/health
curl http://localhost:8080/actuator/info
curl http://localhost:8080/actuator/metrics
7.2. Swagger / OpenAPI
- Dev/Staging:
http://localhost:8080/swagger - Prod: disabled (per
application-prod.yml.example)
8. Flyway (if using migrations)
-
Add SQL files in
src/main/resources/db/migration:V1__init.sql,V2__add_user_table.sql
-
Flyway auto-migrates at startup (
spring.flyway.enabled=true)
Example V1__init.sql:
CREATE TABLE IF NOT EXISTS sample (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(255. NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
9. IntelliJ Integration: Run/Debug like a Pro
-
Open project → let IntelliJ index/import Maven
-
Create/Edit Run Configuration:
- Main class: e.g.
com.example.MyAppApplication - Environment variables: add vars from section 3.2
- VM options (optional):
-Xms512m -Xmx1g
- Main class: e.g.
-
Debug: click the 🐞 icon → set breakpoints → F9
With EnvFile plugin: enable it → select
.env
10. Common Troubleshooting
-
❌
Communications link failure(MySQL)- DB not ready → check
docker compose logs -f mysql - Incorrect host/port/credentials → verify env vars
- Need
allowPublicKeyRetrieval=truefor MySQL 8 auth issues
- DB not ready → check
-
❌
Access denied for user- User lacks privileges → run SQL GRANT commands
-
❌
Cannot connect to Redis- Check
REDIS_HOST,REDIS_PORT - Inside Docker → host =
redis - Local machine → host =
localhost
- Check
-
❌ Swagger 404
- Dev/Staging →
/swagger - Prod → disabled
- Dev/Staging →
-
❌ Flyway migration error
- Check ordering
V1__*.sql,V2__*.sql - Don't rename already-run migrations
- Reset
flyway_schema_historyonly if you know what you're doing
- Check ordering
11. Security & Commit Rules
- ✅ Commit:
application.yml,application-dev.yml,application-staging.yml,application-prod.yml.example,.env.example - ❌ Do NOT commit: real
application-prod.yml, actual.env, secrets - For staging/prod → use ENV or a secret manager (Vault, AWS/GCP/Azure)
12. Quick Commands (cheat sheet)
# Start DB/Redis
docker compose up -d mysql redis
# Run app locally (dev)
./mvnw spring-boot:run
# Build JAR & run
./mvnw -DskipTests package
java -Dspring.profiles.active=staging -jar target/*.jar
# Run entire stack
docker compose up --build
# Health check
curl http://localhost:8080/actuator/health
# Swagger (dev/staging)
open http://localhost:8080/swagger