Skip to main content

Getting Started

This guide covers how to run the backend API locally using Docker or a native Kotlin/Gradle setup.

Prerequisites​

ToolVersionNotes
Docker & Docker ComposeLatestRecommended path
Java (OpenJDK)21+Required for native run
Gradle8.5Included via wrapper (./gradlew)
PostgreSQL16Provided by Docker Compose

Option 1 — Docker Compose (Recommended)​

This starts PostgreSQL, MailHog (email testing), and the API together.

# Clone the repo
git clone <repo-url>
cd association-app-backend

# Copy the example env file
cp .env.example .env
# Edit .env and fill in required values (see Environment Variables below)

# Start everything
docker-compose up --build
ServiceURL
APIhttp://localhost:8080
Swagger UIhttp://localhost:8080/swagger-ui.html
MailHog (email preview)http://localhost:8025
PostgreSQLlocalhost:5432

To stop:

docker-compose down

To reset the database:

docker-compose down -v
docker-compose up --build

Option 2 — Native Run​

Use this if you want faster iteration without Docker overhead for the app itself.

# 1. Start only PostgreSQL and MailHog
docker-compose up postgres mailhog

# 2. Set the Spring profile
export SPRING_PROFILES_ACTIVE=local

# 3. Run the app
./gradlew bootRun

Or run AssociationappApplication.kt directly from IntelliJ IDEA.

Common Gradle Commands​

./gradlew bootRun          # Run the app
./gradlew build            # Compile + test + package
./gradlew test             # Run tests only
./gradlew clean build      # Clean build
./gradlew dependencies     # List all dependencies

Environment Variables​

Create a .env file in the project root (or set these in your environment / Docker Compose).

Required​

# Database
DB_HOST=localhost
DB_NAME=associationapp
DB_USER=associationapp
DB_PASSWORD=associationapp

# JWT — generate a strong secret for production
# openssl rand -base64 64
JWT_SECRET=replace-with-base64-encoded-256-bit-key

# Frontend (for CORS and email links)
FRONTEND_URL=http://localhost:3000
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:4200

Email​

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password
MAIL_FROM=[email protected]
MAIL_FROM_NAME=Association App
EMAIL_ENABLED=true
Development Email

Use the bundled MailHog service (docker-compose up mailhog) instead of a real SMTP server. Set MAIL_HOST=mailhog and MAIL_PORT=1025. All outbound emails appear at http://localhost:8025.

Storage​

Choose one storage provider:

# Local filesystem (default for development)
STORAGE_PROVIDER=local
STORAGE_LOCAL_PATH=./storage
STORAGE_LOCAL_URL=http://localhost:8080/storage
STORAGE_SIGNED_URL_SECRET=dev-secret

# Google Cloud Storage
STORAGE_PROVIDER=gcs
GCS_BUCKET_NAME=your-bucket
GCS_PROJECT_ID=your-project-id
GCS_CREDENTIALS_PATH=/path/to/service-account.json
GCS_CDN_DOMAIN=cdn.example.com           # optional

# AWS S3
STORAGE_PROVIDER=aws-s3
S3_BUCKET_NAME=your-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_ENDPOINT_URL=https://s3.amazonaws.com
S3_CDN_DOMAIN=your-cloudfront-domain.com # optional

System​

# Encryption key for system settings stored in the DB
# openssl rand -base64 32
SETTINGS_ENCRYPTION_KEY=replace-with-base64-encoded-32-byte-key

# Active Spring profile
SPRING_PROFILES_ACTIVE=local   # local | docker | dokploy | cloudrun | production

Optional​

# Mobile deep links
DEEPLINK_SCHEME=myapp
DEEPLINK_HOST=my-url.com

Spring Profiles​

ProfileUse case
localLocal dev with localhost database
dockerDocker Compose (postgres hostname)
dokployDokploy cloud deployment
cloudrunGoogle Cloud Run (Cloud SQL socket factory)
productionProduction with full security hardening

Health Check​

Once the server is running, verify it's healthy:

curl http://localhost:8080/actuator/health
# {"status":"UP"}

curl http://localhost:8080/api/auth/health
# {"status":"UP"}

Default Development Credentials​

ResourceValue
DB hostlocalhost:5432
DB nameassociationapp
DB userassociationapp
DB passwordassociationapp
API basehttp://localhost:8080
warning

Never use these defaults in production. Always override credentials via environment variables.