SITMUN Application Stack

The SITMUN Application Stack is a comprehensive multi-container geospatial platform that provides a complete solution for territorial information management, geographical services, and spatial applications. This stack integrates all SITMUN components into a unified, containerized environment designed for development, testing, and production deployment.

About SITMUN

SITMUN (Sistema de Información Territorial de la Mancomunidad de Municipios) is a geospatial information management system for territorial data, services, and spatial applications.

Architecture Overview

The stack has four main components:

┌─────────────────────────────────────────────────────────────┐
│                    SITMUN Application Stack                 │
├─────────────────────────────────────────────────────────────┤
│  Frontend Layer                                             │
│  ├── SITMUN Viewer App (Angular 19)                         │
│  └── SITMUN Admin App (Angular 19)                          │
├─────────────────────────────────────────────────────────────┤
│  Backend Layer                                              │
│  ├── SITMUN Backend Core (Spring Boot 3)                    │
│  └── SITMUN Proxy Middleware (Spring Boot 3)                │
├─────────────────────────────────────────────────────────────┤
│  Database Layer                                             │
│  ├── PostgreSQL 16 / Oracle 23c / H2                        │
│  └── Liquibase Migration                                    │
└─────────────────────────────────────────────────────────────┘

Component Architecture

Component	Technology	Purpose	Port
SITMUN Viewer App	Angular 19, TypeScript	Interactive map visualization and user interface	9000
SITMUN Admin App	Angular 19, TypeScript	Administrative interface and configuration	9000
SITMUN Backend Core	Spring Boot 3, Java 17	Core REST API and business logic	9001
SITMUN Proxy Middleware	Spring Boot 3, Java 17	Secure proxy and middleware services	9002
Database	PostgreSQL/Oracle/H2	Data persistence and geospatial storage	9003/9004

Technology Stack

Frontend: Angular 19, TypeScript, SITNA
Backend: Spring Boot 3, Java 17, Gradle
Database: PostgreSQL 16 (default), Oracle 23c, H2 (dev only), Liquibase
Infrastructure: Docker, Docker Compose, Git submodules, SonarCloud

Quick Start

Prerequisites

Docker Engine + Docker Compose (or Docker Desktop)
Git

Quick Setup

Clone the repository with submodules

git clone --branch dev --recurse-submodules https://github.com/sitmun/sitmun-application-stack.git
cd sitmun-application-stack

Setup the environment

For Unix-based systems (Linux/macOS):
```
./setup.sh
```
For Windows systems:
```
./setup.ps1
```
Select a profile (.env)

The stack is configured via .env. Recommended profiles are under profiles/:
```
# Development (PostgreSQL)
cp profiles/development-postgres.env .env

# Development (Oracle)
# cp profiles/development-oracle.env .env
```
Notes:
- The setup scripts create .env from profiles/postgres.env only if .env is missing.
- You can keep local overrides in .env.local (not committed); Docker Compose loads .env → .env.local → environment variables.
Start the SITMUN Application Stack
```
docker compose up -d
```
Access the applications
- Viewer Application: http://localhost:9000/viewer (public access)
- Admin Application: http://localhost:9000/admin (requires authentication)
- Backend API: http://localhost:9000/backend
- API Documentation: http://localhost:9001/swagger-ui/index.html
Default credentials
- Username: admin
- Password: admin

Installation

Development Installation

Clone the Repository

git clone --branch dev --recurse-submodules https://github.com/sitmun/sitmun-application-stack.git
cd sitmun-application-stack

Setup Environment

# Unix-based systems
./setup.sh

# Windows systems
./setup.ps1

Select a development profile (.env)

cp profiles/development-postgres.env .env
# Or: cp profiles/development-oracle.env .env

Start Services
```
docker compose up -d
```

Verify Installation

# Check service status
docker compose ps

# Check backend health
curl http://localhost:9001/api/dashboard/health

# Check proxy health
curl http://localhost:9002/actuator/health

Production Installation

Environment Configuration

Copy a profile to .env and edit for production (see Database Configuration for all options):
```
# For PostgreSQL (default)
cp profiles/postgres.env .env

# For Oracle
cp profiles/oracle.env .env

# Edit environment variables for production
nano .env
```
The copied profile already sets the database, Spring, Liquibase, and frontend variables (all other compose variables have working defaults). The only variables you must add to boot are the two secrets — the compose profile marks them required (:?) and refuses to start without them:
```
# Secrets (mandatory, no default, min 32 chars each) -- see step 2
SITMUN_USER_SECRET=<32+ char random value>
MIDDLEWARE_SECRET=<32+ char random value>
```
For a real production deployment you should also override the database credentials, which otherwise default to sitmun3/sitmun3:
```
DATABASE=<db name>
DATABASE_USERNAME=<db user>
DATABASE_PASSWORD=<db password>
```
Secrets (mandatory)

Production profiles (profiles/postgres, profiles/oracle) do not ship secret defaults. You must set both variables in .env, each at least 32 characters:
```
# Backend JWT signing secret and backend-proxy shared secret
echo "SITMUN_USER_SECRET=$(openssl rand -hex 32)" >> .env
echo "MIDDLEWARE_SECRET=$(openssl rand -hex 32)" >> .env
```
Enforcement is fail-fast, so misconfiguration is caught before the platform serves traffic:
- A missing variable makes Docker Compose refuse to start (variable is required).
- A blank or shorter-than-32-character value aborts backend/proxy startup via SecuritySecretValidator / ProxySecretValidator (IllegalStateException), so the container never becomes healthy.
MIDDLEWARE_SECRET is shared: it is injected into the backend as SITMUN_PROXY_MIDDLEWARE_SECRET and into the proxy as SITMUN_BACKEND_CONFIG_SECRET. Both sides must match. Never commit secrets, and never reuse the development defaults.
Database Setup

Database settings are already set by the profile you copied. To change database type later, copy a different profile to .env or edit SITMUN_DB_PROFILE and COMPOSE_PROFILES in .env. See the Database Configuration section for details and verification steps.

SSL Configuration

# In .env, set for HTTPS (standard port 443)
PUBLIC_URL_SCHEME=https
# PUBLIC_PORT and PUBLIC_NON_STANDARD_PORT are not needed for standard port 443

Configuration

Environment Variables

The SITMUN Application Stack uses environment variables for configuration. Copy a profile from profiles/ to .env (see Database Configuration); the following variables are used:

Variable	Description	Default Value
`PUBLIC_URL_SCHEME`	Protocol (http/https)	`http`
`PUBLIC_HOSTNAME`	Public hostname	`localhost`
`PUBLIC_PORT`	Public port number (blank for standard port)	`9000`
`PUBLIC_NON_STANDARD_PORT`	Set to mark use of a non-standard port	`1`
`PUBLIC_BASE_PATH`	Application context path (must start and end with /)	`/`
`LOCAL_PORT`	Port the nginx container listens on	`9000`
`LOCAL_BASE_PATH`	Base path in the nginx container	`/`
`SITMUN_PROFILE`	SITMUN scenario profile	`development`
`SITMUN_DB_PROFILE`	Spring Boot database profile (postgres/oracle)	`postgres`
`COMPOSE_PROFILES`	Docker profiles: `postgres`, `oracle`, `demo` (example DB; `dev` alias), `mbtiles`	`postgres`
`DATABASE`	Database name	`sitmun3`
`DATABASE_URL`	JDBC URL	`jdbc:postgresql://postgres:5432/`
`DATABASE_USERNAME`	Database username	`sitmun3`
`DATABASE_PASSWORD`	Database password	`sitmun3`
`FORCE_USE_OF_PROXY`	Force proxy middleware	`false`
`SITMUN_PROXY_MIDDLEWARE_VALIDATE_USER_ACCESS`	Enable proxy access validation (blocks access to blocked services)	`true`
`SITMUN_USER_SECRET`	Backend JWT signing secret (min 32 chars)	Required in production profiles
`MIDDLEWARE_SECRET`	Backend-proxy shared secret (min 32 chars)	Required in production profiles
`ENVIRONMENT`	Frontend Docker build mode (development/production)	`development`

Docker frontend builds read each app's version from its submodule package.json (admin and viewer independently). The About dialog shows that value at runtime.

Database Configuration

The SITMUN Application Stack supports multiple database backends: PostgreSQL 16 (default), Oracle 23c, and H2 (development only). Three environment variables control setup:

SITMUN_PROFILE -- SITMUN scenario profile. Use development for local development scenarios.
SITMUN_DB_PROFILE -- Spring Boot database profile for the backend (postgres or oracle). Controls database dialect, Liquibase config, and which database service the backend depends on. Must always be set.
COMPOSE_PROFILES -- Built-in Docker Compose variable that selects which containers start. Set to postgres or oracle for a dockerized database. Add ,demo for the example demo database (host port 9005; ,dev remains a deprecated alias). Add ,mbtiles for the MBTiles service used by edition-mobile tile export. Omit entirely for external databases.

SITMUN_DB_PROFILE and COMPOSE_PROFILES must agree on the database type when using a dockerized database.

The backend automatically loads the appropriate configuration from:

profiles/development/backend/application-postgres.yml (for PostgreSQL)
profiles/development/backend/application-oracle.yml (for Oracle)

Using Profile .env Files (Recommended)

Pre-configured profile .env files are provided in profiles/. Copy the desired profile to the project root as .env, edit as needed, then start the stack:

# Dockerized PostgreSQL
cp profiles/postgres.env .env
docker compose up -d

# Dockerized Oracle
cp profiles/oracle.env .env
docker compose up -d

# Development PostgreSQL (main DB + Liquibase seed; no example DB / MBTiles)
cp profiles/development-postgres.env .env
docker compose up -d

# Development Oracle (same idea)
cp profiles/development-oracle.env .env
docker compose up -d

# External PostgreSQL (edit .env first)
cp profiles/postgres-external.env .env
# Edit .env with your connection details
docker compose up -d front backend proxy

# External Oracle (edit .env first)
cp profiles/oracle-external.env .env
# Edit .env with your connection details
docker compose up -d front backend proxy

PostgreSQL 16 (Default)

Using a profile .env file:

cp profiles/postgres.env .env
docker compose up -d

Or set variables directly in .env:

SITMUN_PROFILE=development
SITMUN_DB_PROFILE=postgres
COMPOSE_PROFILES=postgres
DATABASE_URL=jdbc:postgresql://postgres:5432/
DATABASE=sitmun3
DATABASE_USERNAME=sitmun3
DATABASE_PASSWORD=sitmun3

Then: docker compose up -d

Configuration details:

Container name: postgres
Port: 9003:5432 (external:internal)
JDBC URL format: jdbc:postgresql://postgres:5432/
Spring profile: postgres
Hibernate dialect: org.hibernate.dialect.PostgreSQLDialect

Oracle Database 23c

Using a profile .env file:

cp profiles/oracle.env .env
docker compose up -d

Or set variables directly in .env:

SITMUN_PROFILE=development
SITMUN_DB_PROFILE=oracle
COMPOSE_PROFILES=oracle
DATABASE_URL=jdbc:oracle:thin:@//oracle:1521/
DATABASE=sitmun3
DATABASE_USERNAME=sitmun3
DATABASE_PASSWORD=sitmun3

Then: docker compose up -d

Oracle may take 60+ seconds on first start. Monitor with:

docker compose logs -f oracle
# Wait for "DATABASE IS READY TO USE!" message

Configuration details:

Container name: oracle
Port: 9004:1521 (external:internal)
JDBC URL format: jdbc:oracle:thin:@//oracle:1521/
Spring profile: oracle
Hibernate dialect: org.hibernate.dialect.OracleDialect

Switching Between Databases

Stop all services:
```
docker compose down
```
Copy a different profile to .env and start:
```
cp profiles/oracle.env .env
docker compose up -d
```
Or update SITMUN_DB_PROFILE and COMPOSE_PROFILES in your .env file and run docker compose up -d.
Database migrations (Liquibase) run automatically on backend startup.

External Database

For an external database not managed by Docker Compose:

Copy the appropriate external profile to .env and edit with your connection details:

cp profiles/postgres-external.env .env
# Or: cp profiles/oracle-external.env .env
# Edit .env with your connection details

Start services without a database container:
```
docker compose up -d front backend proxy
```
The front backend proxy arguments are required because depends_on references the database service, which is not started. This selectively starts only the application services.

Or set variables directly in .env:

SITMUN_PROFILE=development
SITMUN_DB_PROFILE=postgres       # or oracle
# COMPOSE_PROFILES is omitted -- no database container starts
DATABASE_URL=jdbc:postgresql://your-host:5432/
DATABASE=your_database
DATABASE_USERNAME=your_username
DATABASE_PASSWORD=your_password

Then: docker compose up -d front backend proxy

Example Demo Database (Optional)

An optional demo database with geospatial datasets is available for testing. It runs on port 9005 and includes UNESCO heritage sites, web publications, and materials management data from profiles/development/demo-data/.

Development profiles do not enable it by default. Opt in by adding the Compose profile demo (,dev is a deprecated alias that still works):

# In .env (PostgreSQL)
COMPOSE_PROFILES=postgres,demo

# Or temporarily:
COMPOSE_PROFILES=postgres,demo docker compose up -d

# Oracle:
# COMPOSE_PROFILES=oracle,demo

Tourism/demo tasks that use JDBC jdbc:postgresql://example/example need this container. The main SITMUN database still starts without it. Credentials: example/example (read-only role example_reader/example_reader).

MBTiles (Optional)

The MBTiles service supports edition-mobile offline tile export through proxy middleware. It is internal to the Compose network (no host port); nginx returns 404 for public /mbtiles.

Development profiles do not enable it by default. Opt in with ,mbtiles:

# In .env
COMPOSE_PROFILES=postgres,mbtiles

# With example demo DB as well:
# COMPOSE_PROFILES=postgres,demo,mbtiles

Admin, viewer, and normal WMS/WFS proxy flows work without it. Root Playwright mobile suites start MBTiles via npm run e2e:mbtiles (Gradle on port 18084), not this Compose service.

Application Configuration

Frontend Configuration

// Environment configuration for Angular apps
export const environment = {
  production: boolean,
  apiBaseURL: string,
  logLevel: LogLevel,
  hashLocationStrategy: boolean,
};

Backend Configuration

# Spring Boot application configuration
spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}
  datasource:
    url: ${DATABASE_URL}${DATABASE}
    username: ${DATABASE_USERNAME}
    password: ${DATABASE_PASSWORD}

sitmun:
  user:
    secret: ${SITMUN_USER_SECRET}
    token-validity-in-milliseconds: 36000000
  proxy-middleware:
    secret: ${SITMUN_PROXY_MIDDLEWARE_SECRET}

Services

Available Services

When the BASE_URL is http://localhost:9000/, the following services are available:

Application	URL	Description	Authentication
Viewer Application	`${BASE_URL}viewer`	Interactive map viewer	Optional
Admin Application	`${BASE_URL}admin`	Administrative interface	Required
Backend API	`${BASE_URL}backend`	Core REST API	JWT Token
Proxy Middleware	`${BASE_URL}middleware`	Proxy services	JWT Token

Service Endpoints

Backend Core API

Health Check: http://localhost:9001/api/dashboard/health
Authentication: http://localhost:9001/api/authenticate
User Management: http://localhost:9001/api/account
Application Config: http://localhost:9001/api/config/client/application
API Documentation: http://localhost:9001/swagger-ui/index.html

Proxy Middleware API

Health Check: http://localhost:9002/actuator/health
Proxy Configuration: http://localhost:9002/api/config/proxy
Service Proxy: http://localhost:9002/api/proxy/*

Service Dependencies

Viewer App ──┐
             ├── Backend Core ── Database
Admin App ───┘
             └── Proxy Middleware ── External Services

Development

End-to-end tests

Root Playwright tests exercise the admin and viewer apps against backend-core on in-memory H2 (no Docker Compose). Viewer suite also starts proxy middleware and a local secured WMS stub. Mobile web suite covers edition Bearer login, proxy-token exchange, and authenticated MBTiles through middleware (no public /mbtiles). Details: e2e/README.md.

# prerequisites: Java 17, Node ≥ 20.19, submodules initialized
# admin: cd front/admin/sitmun-admin-app && npm ci
# viewer: cd front/viewer/sitmun-viewer-app && npm ci
npm ci
npm run e2e:install
npm run e2e
npm run e2e:viewer
npm run e2e:mobile:web
# optional Android emulator + Maestro (requires ANDROID_HOME, adb, Maestro)
# npm run e2e:mobile:android

Owned ports: admin 4300, viewer 4400, backend 18080, proxy 18082, WMS stub 18093. Mobile adds gateway 18081, MBTiles 18084, WMTS stub 18094.

Project Structure

The SITMUN Application Stack uses Git submodules to include the source code of all SITMUN components:

Submodule	GitHub Repository	Docker Service	Technology Stack
`front/admin/sitmun-admin-app`	SITMUN Admin App	`front`	Angular 19, TypeScript
`front/viewer/sitmun-viewer-app`	SITMUN Viewer App	`front`	Angular 19, TypeScript
`apps/touristic-mobile-app`	SITMUN Touristic Mobile App	—	Ionic/Angular, Capacitor
`apps/edition-mobile-app`	SITMUN Edition Mobile App	—	Ionic/Angular, Capacitor
`back/backend/sitmun-backend-core`	SITMUN Backend Core	`backend`	Spring Boot 3, Java 17
`back/proxy/sitmun-proxy-middleware`	SITMUN Proxy Middleware	`proxy`	Spring Boot 3, Java 17
`back/mbtiles/sitmun-mbtiles`	SITMUN MBTiles	`mbtiles` (internal)	Spring Boot 3, Java 17

Profile-Based Development Environments

The stack includes minimum viable database profiles for rapid backend + database bootstrapping:

profiles/
  development/
    backend/           # Backend Spring config (application.yml, Liquibase migrations)
    proxy/             # Proxy Spring config
  oracle/
    docker-compose.yml # Backend + Oracle DB with schema + seed data
  postgres/
    docker-compose.yml # Backend + Postgres DB with schema + seed data

Running a standalone profile:

# Start Postgres profile (backend + database with dev seed data)
cd profiles/postgres
docker compose up -d --build

# Verify backend health
curl http://localhost:8080/api/dashboard/health

# Start Oracle profile (mutually exclusive - use different terminal or stop postgres first)
cd ../oracle
docker compose up -d --build

Important notes:

Profiles use SPRING_LIQUIBASE_CONTEXTS=dev to bootstrap schema + development seed data via Liquibase on startup.
Backend listens on port 8080, databases on standard ports (5432 for Postgres, 1521 for Oracle).
Profiles share the same container names and ports - run only one profile at a time locally.
For production or custom contexts, override SPRING_LIQUIBASE_CONTEXTS in the compose environment section.

Development Workflow

Update Repository and Submodules

git fetch origin dev
git checkout dev
git submodule update --recursive --remote

Change Submodule Branch (if needed)

# Switch submodule to specific branch
git submodule set-branch -b branch_name submodule_name
git submodule sync
git submodule update --init

Rebuild and Restart Services

# Rebuild specific service
docker compose build --no-cache service_name
docker compose up service_name -d

# Rebuild all services
docker compose build --no-cache
docker compose up -d

Individual Component Development

Frontend Development (Angular)

# Navigate to admin app
cd front/admin/sitmun-admin-app
npm ci
npm start

# Navigate to viewer app
cd front/viewer/sitmun-viewer-app
npm ci
npm start

Backend Development (Spring Boot)

# Navigate to backend core
cd back/backend/sitmun-backend-core
./gradlew bootRun --args='--spring.profiles.active=dev'

# Navigate to proxy middleware
cd back/proxy/sitmun-proxy-middleware
./gradlew bootRun --args='--spring.profiles.active=dev'

Frontend Build Configurations

The frontend applications (Admin and Viewer) support three build configurations to cover different use cases:

Configuration	Use Case	API URL	Source Maps	Optimization
`development`	Local `ng serve`	`localhost:9000/backend`	Yes	No
`docker-dev`	Docker debugging	Template-based	Yes	No
`production`	Docker production	Template-based	No	Yes

Local Development

For local development using ng serve, the development configuration uses environment.ts which points to the local docker-compose stack:

# Admin app
cd front/admin/sitmun-admin-app
npm install
npm start  # Uses development configuration

# Viewer app
cd front/viewer/sitmun-viewer-app
npm install
npm start  # Uses development configuration

The API URL is set to http://localhost:9000/backend (the docker-compose stack backend).

Docker Production Build

For production Docker builds, the production configuration is used by default:

# Build production Docker image (default)
docker compose build front

This creates optimized builds without source maps, using the environment.prod.ts.template which injects the API URL via envsubst at build time.

Docker Development Build (Debugging)

For debugging issues in a Docker environment, use the docker-dev configuration which includes source maps:

# Build Docker image with source maps for debugging
BUILD_MODE=docker-dev docker compose build front

This creates unoptimized builds with source maps enabled, while still using the template-based API URL configuration for Docker.

Environment Files

front/
├── admin/
│   ├── environment.prod.ts.template          # Docker builds (envsubst)
│   └── sitmun-admin-app/src/environments/
│       ├── environment.ts                    # Local development
│       └── environment.prod.ts               # Production fallback
└── viewer/
    ├── environment.prod.ts.template          # Docker builds (envsubst)
    └── sitmun-viewer-app/src/environments/
        ├── environment.ts                    # Local development
        └── environment.prod.ts               # Production fallback

Code Quality

# Frontend quality checks
cd front/admin/sitmun-admin-app
npm run lint
npm test

cd front/viewer/sitmun-viewer-app
npm run lint
npm test

# Backend quality checks
cd back/backend/sitmun-backend-core
./gradlew test
./gradlew spotlessCheck

cd back/proxy/sitmun-proxy-middleware
./gradlew test
./gradlew spotlessCheck

API Documentation

Backend Core API Reference

The SITMUN Backend Core provides comprehensive REST API functionality:

Authentication Endpoints

POST /api/authenticate
Content-Type: application/json
{
  "username": "admin",
  "password": "admin"
}

GET /api/account
Cookie: access_token=<jwt-token>

POST /api/authenticate/logout
Cookie: access_token=<jwt-token>

User Management Endpoints

GET /api/account/all
GET /api/account/{id}
GET /api/account/public/{id}
POST /api/user-verification/verify-password
POST /api/user-verification/verify-email
POST /api/recover-password
GET /api/userTokenValid

Configuration Endpoints

GET /api/config/client/application
GET /api/config/client/territory
GET /api/config/client/profile/{appId}/{territoryId}
POST /api/config/proxy

Health and Monitoring

GET /api/dashboard/health
GET /api/dashboard/info
GET /api/dashboard/metrics

Proxy Middleware API Reference

The SITMUN Proxy Middleware provides secure proxy functionality:

Proxy Endpoints

GET /actuator/health
POST /api/config/proxy
GET /api/proxy/{service-type}/{service-id}

Service Types Supported

WMS: Web Map Service proxy
WFS: Web Feature Service proxy
WMTS: Web Map Tile Service proxy
JDBC: Database connection proxy
Custom: Custom service proxy

API Documentation Access

Backend Core Swagger: http://localhost:9001/swagger-ui/index.html
Proxy Middleware: Available through backend configuration endpoints
OpenAPI Specification: Available in /static/v3/ directory

Security

Authentication and Authorization

JWT Tokens: Secure token-based authentication with configurable expiration
OIDC Authentication: Multi-provider OpenID Connect support for enterprise single sign-on (new in 1.2.1)
Database Authentication: Traditional username/password authentication
LDAP Integration: Enterprise directory service authentication
Role-Based Access Control: Fine-grained permissions based on user roles and territories
Application Privacy: Applications can be marked as private to restrict public access
Public User Support: Anonymous access with appropriate restrictions

Security Features

// Route protection example
{
  path: 'admin',
  component: AdminComponent,
  canActivate: [AuthGuard],
  data: { roles: ['ADMIN'] }
}

// HTTP interceptor for token handling
@Injectable()
export class AuthInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    const token = this.authService.getToken();
    if (token) {
      req = req.clone({
        setHeaders: { Authorization: `Bearer ${token}` }
      });
    }
    return next.handle(req);
  }
}

Security Configuration

Secrets

Two secrets must be provided in production, each at least 32 characters:

# .env file
SITMUN_USER_SECRET=<32+ char random value>   # backend JWT signing secret
MIDDLEWARE_SECRET=<32+ char random value>     # shared backend <-> proxy secret

# Generate secure random values
openssl rand -hex 32

IMPORTANT for production:

MIDDLEWARE_SECRET is injected into the backend as SITMUN_PROXY_MIDDLEWARE_SECRET and into the proxy as SITMUN_BACKEND_CONFIG_SECRET; both sides must share the same value.
SITMUN_USER_SECRET signs user JWTs and is backend-only.
Startup is fail-fast: SecuritySecretValidator (backend) and ProxySecretValidator (proxy) reject blank or shorter-than-32-character secrets with an IllegalStateException, so the service never comes up misconfigured. Production compose profiles also mark the variables as required and refuse to start without them.
Never commit secrets to version control, and never reuse the development defaults.

JWT Configuration

sitmun:
  user:
    secret: ${SITMUN_USER_SECRET}
    token-validity-in-milliseconds: 36000000
  proxy-middleware:
    secret: ${SITMUN_PROXY_MIDDLEWARE_SECRET}

CORS Configuration

Backend CORS is configured in WebSecurityConfigurer.corsConfigurationSource(). The current policy allows credentials, all headers, OPTIONS, GET, POST, PUT, and DELETE, and uses allowedOriginPattern("*").

Content Security Policy

// Angular CSP configuration
{
  "content_security_policy": {
    "default-src": ["'self'"],
    "script-src": ["'self'", "'unsafe-inline'"],
    "style-src": ["'self'", "'unsafe-inline'"],
    "img-src": ["'self'", "data:", "https:"],
    "connect-src": ["'self'", "https:"]
  }
}

Troubleshooting

Common Issues

Docker Issues

# Clean up Docker resources
docker compose down -v
docker system prune -f
docker volume prune -f

# Check service logs
docker compose logs service_name
docker compose logs -f service_name

Database Connection Issues

Check database container status:

# Check if database container is running
docker compose ps postgres  # For PostgreSQL
docker compose ps oracle    # For Oracle

# Check database logs
docker compose logs postgres
docker compose logs oracle

Verify database connectivity from backend:

# Test network connectivity
docker compose exec backend ping postgres  # For PostgreSQL
docker compose exec backend ping oracle   # For Oracle

# Check backend health (includes database connection check)
curl http://localhost:9001/api/dashboard/health

PostgreSQL-specific troubleshooting:

# Connect to PostgreSQL container
docker compose exec -it postgres psql -U sitmun3 -d sitmun3

# Check PostgreSQL logs
docker compose logs postgres | grep -i error

# Verify PostgreSQL is accepting connections
docker compose exec postgres pg_isready -U sitmun3

Oracle-specific troubleshooting:

# Oracle takes 60+ seconds to start on first run
docker compose logs -f oracle
# Wait for "DATABASE IS READY TO USE!" message

# Connect to Oracle container
docker compose exec -it oracle sqlplus sitmun3/sitmun3@//localhost:1521/sitmun3

# Check Oracle logs
docker compose logs oracle | grep -i error

# Verify Oracle is ready (may take time)
docker compose exec oracle sqlplus -L sitmun3/sitmun3@//localhost:1521/sitmun3 -c "SELECT 1 FROM DUAL;"

Common database configuration errors:

Wrong profile configuration: Ensure SITMUN_DB_PROFILE and COMPOSE_PROFILES agree on the database type (both postgres or both oracle)
Incorrect DATABASE_URL format:
- PostgreSQL: jdbc:postgresql://postgres:5432/
- Oracle: jdbc:oracle:thin:@//oracle:1521/
Database not ready: Wait for health checks to pass before starting backend
Port conflicts: Check if ports 9003 (PostgreSQL) or 9004 (Oracle) are already in use

Authentication Issues

# Check the authenticated account using a saved login cookie
curl -b cookies.txt http://localhost:9001/api/account

# Verify user credentials
curl -X POST http://localhost:9001/api/authenticate \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

Frontend Build Issues

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm ci

# Check Node.js version
node --version  # Should be 20.19.0 or higher

Backend Build Issues

# Clean Gradle cache
./gradlew clean

# Check Java version
java --version  # Should be 17 or higher

# Run with debug logging
./gradlew bootRun --args='--spring.profiles.active=dev --logging.level.org.sitmun=DEBUG'

Debug Mode

Enable Debug Logging

# Backend debug logging
export LOGGING_LEVEL_ORG_SITMUN=DEBUG
export LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY=DEBUG

# Restart services
docker compose restart backend proxy

Frontend Debug Mode

# Angular debug mode
ng serve --configuration=development --verbose

# Check browser console for errors
# Enable source maps in browser dev tools

Performance Issues

Memory Issues

# Increase Docker memory limits
docker compose down
docker system prune -f
docker compose up -d

# Increase Java heap size
export JAVA_OPTS="-Xmx4g -Xms2g"

Database Performance

# Check database performance
docker compose exec postgres psql -U sitmun3 -d sitmun3 -c "SELECT * FROM pg_stat_activity;"

# Optimize database queries
# Check database indexes
# Monitor slow queries

Contributing

Development Guidelines

Fork the repository and create a feature branch
Follow coding standards:
- Angular: Follow Angular style guide and use conventional commits
- Spring Boot: Follow Spring Boot best practices and use conventional commits
- Use functional code with complete but terse documentation
Write tests for new functionality
Update documentation as needed

Ensure quality checks pass:

# Frontend
npm run lint
npm test
npm run build -- --configuration=production

# Backend
./gradlew test
./gradlew spotlessCheck
./gradlew build

Submit a pull request with a clear description

Conventional Commits

We use Conventional Commits for commit messages:

# Examples
git commit -m "feat(auth): add LDAP authentication support"
git commit -m "fix(api): resolve JWT token validation issue"
git commit -m "docs(readme): update installation instructions"
git commit -m "test(components): add unit tests for user component"
git commit -m "style(formatting): apply prettier formatting"

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks
perf: Performance improvements
ci: CI/CD changes
build: Build system changes

Code Review Process

Automated Checks: All PRs must pass CI/CD pipeline
Code Review: At least one maintainer review required
Quality Gate: SonarCloud quality gate must pass
Testing: All tests must pass with adequate coverage
Documentation: Update docs for new features

Support

Getting Help

Documentation: Check component-specific README files in submodules
Issues: GitHub Issues
Component Issues:
Discussions: GitHub Discussions

Reporting Issues

When reporting issues, please include:

Environment: OS, Docker version, Node.js version, Java version
Steps to reproduce: Clear step-by-step instructions
Expected behavior: What should happen
Actual behavior: What actually happens
Screenshots: If applicable
Logs: Docker logs, browser console errors, application logs
Configuration: Relevant environment variables and configuration files

Community Resources

SITMUN Documentation: https://sitmun.github.io/
SITMUN Organization: https://github.com/sitmun
SonarCloud Quality Gates:

License

This project is licensed under the European Union Public Licence V. 1.2 (EUPL-1.2). The EUPL is a copyleft open-source license compatible with major open-source licenses including GPL, AGPL, MPL, and others. See the LICENSE file for the full license text.

License Compatibility

The EUPL v1.2 is compatible with:

GNU General Public License (GPL) v2, v3
GNU Affero General Public License (AGPL) v3
Mozilla Public License (MPL) v2
Eclipse Public License (EPL) v1.0
And many others

Name		Name	Last commit message	Last commit date
Latest commit History 378 Commits
.github		.github
apps		apps
back		back
e2e		e2e
front		front
profiles		profiles
scripts		scripts
tools		tools
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.markdownlint.json		.markdownlint.json
CHANGELOG.md		CHANGELOG.md
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
VERSION		VERSION
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
playwright.application-contact.config.ts		playwright.application-contact.config.ts
playwright.config.ts		playwright.config.ts
playwright.mia-cross.config.ts		playwright.mia-cross.config.ts
playwright.mobile.config.ts		playwright.mobile.config.ts
playwright.viewer.config.ts		playwright.viewer.config.ts
setup.ps1		setup.ps1
setup.sh		setup.sh

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

SITMUN Application Stack

Table of Contents

About SITMUN

Architecture Overview

Component Architecture

Technology Stack

Quick Start

Prerequisites

Quick Setup

Installation

Development Installation

Production Installation

Configuration

Environment Variables

Database Configuration

Using Profile .env Files (Recommended)

PostgreSQL 16 (Default)

Oracle Database 23c

Switching Between Databases

External Database

Example Demo Database (Optional)

MBTiles (Optional)

Application Configuration

Frontend Configuration

Backend Configuration

Services

Available Services

Service Endpoints

Backend Core API

Proxy Middleware API

Service Dependencies

Development

End-to-end tests

Project Structure

Profile-Based Development Environments

Development Workflow

Individual Component Development

Frontend Development (Angular)

Backend Development (Spring Boot)

Frontend Build Configurations

Local Development

Docker Production Build

Docker Development Build (Debugging)

Environment Files

Code Quality

API Documentation

Backend Core API Reference

Authentication Endpoints

User Management Endpoints

Configuration Endpoints

Health and Monitoring

Proxy Middleware API Reference

Proxy Endpoints

Service Types Supported

API Documentation Access

Security

Authentication and Authorization

Security Features

Security Configuration

Secrets

JWT Configuration

CORS Configuration

Content Security Policy

Troubleshooting

Common Issues

Docker Issues

Database Connection Issues

Authentication Issues

Frontend Build Issues

Backend Build Issues

Debug Mode

Enable Debug Logging

Frontend Debug Mode

Performance Issues

Memory Issues