Skip to content

Local Development Setup

CIS services rely on infrastructure services (Oracle 23, Redis 7, OpenLDAP, Mailpit) orchestrated via Docker Compose.


1. Environment Configuration

CIS uses environment variable separation across runtime profiles (dev, uat, prod): - Root .env.dev: Controls Docker Compose port bindings and volume mounts. - Service .env.dev: Controls Spring Boot properties for each respective service.

Ensure you have a .env.dev created in the repository root from .env.dev.example (or existing dev template).


2. Starting Local Companion Infrastructure

You can launch the backing data stores and companion services without running the Spring Boot applications inside containers:

# Start Oracle Database, Redis, OpenLDAP, and Mailpit
docker compose --env-file=.env.dev up -d oracle-db redis cis-ldap mailpit

Port Allocation Reference

Deployable Service Host Port Protocol / Purpose
cis-bff 8080 Backend-For-Frontend Reverse Proxy & Browser Gateway
cis-auth 8085 OAuth2 / OIDC Authorization Server
cis-api 8089 Core Cadastral REST APIs (Embeds cis-search & cis-emailer)
cis-workflow 8090 Workflow Execution Engine
Oracle DB 1521 Database Listener (SID: XE / PDB: FREEPDB1)
Redis 6379 Token Blacklist & Session Store
OpenLDAP 10389 LDAP Directory Service (Host: 10389 -> Container: 389)
Mailpit Web UI 8025 Mock SMTP Mailbox Browser
Mailpit SMTP 1025 Local SMTP Server

[!NOTE] - Local File Storage: In local development (dev profile), file uploads are written directly to local disk (app.file-storage.storage-location: runtime/uploads), so running an S3 object store like RustFS is not required locally. RustFS is utilized in server deployments (UAT / Production). - Embedded Submodules: cis-search and cis-emailer are internal library modules compiled directly into cis-api (implementation project(":cis-search") and implementation project(":cis-emailer")). They do not expose standalone HTTP/REST ports.


3. Running Services Locally

You can launch any service using the Spring Boot Gradle plugin or your IDE:

# Run cis-auth (port 8085)
.\gradlew.bat :cis-auth:bootRun --args="--spring.profiles.active=dev"

# Run cis-bff (port 8080)
.\gradlew.bat :cis-bff:bootRun --args="--spring.profiles.active=dev"

# Run cis-api (port 8089)
.\gradlew.bat :cis-api:bootRun --args="--spring.profiles.active=dev"

# Run cis-workflow (port 8090)
.\gradlew.bat :cis-workflow:bootRun --args="--spring.profiles.active=dev"

Once running: - BFF login entrypoint: http://localhost:8080/bff/auth/authorize?clientId=cis-bff-internal-client - OIDC Discovery: http://localhost:8085/.well-known/openid-configuration - Mailpit UI: http://localhost:8025