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 (
devprofile), 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-searchandcis-emailerare internal library modules compiled directly intocis-api(implementation project(":cis-search")andimplementation 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