Skip to content

Configuration Management

Jump to bottom
Radch-enko edited this page Jul 24, 2025 · 2 revisions

Configuration Management

This document covers the configuration architecture of the Effective Office system, including application settings, environment variables, deployment configurations, and configuration best practices. It focuses on how configuration is structured across the Spring Boot backend and deployment environments.

For information about database migrations and schema management, see Database & Configuration. For deployment procedures and Docker setup, see Docker Deployment.

Configuration Architecture Overview

The Effective Office system uses a layered configuration approach with Spring Boot profiles, environment variables, and external credential files. Configuration is separated into application-level settings, feature-specific configurations, and deployment-specific overrides.

configuration-architecture-overview.svg

Application Configuration Structure

The main application configuration is defined in application.yml with modular profile inclusion and environment variable substitution.

Core Application Settings

Configuration Section Purpose Key Settings
Server HTTP server configuration Port 8080, context path /api
Spring Profiles Module inclusion repository profile included
JPA/Hibernate Database ORM settings DDL auto-update, PostgreSQL dialect
Flyway Database migrations Enabled by default, baseline on migrate
Jackson JSON serialization Non-null inclusion, case-insensitive enums
SpringDoc API documentation Swagger UI, package scanning
Management Actuator endpoints Health, info, metrics exposed
Logging Application logging Configurable log levels by package

Environment Variable Configuration

The system extensively uses environment variables for deployment flexibility:

environment-variable-configuration.svg

Database Configuration

Database configuration is handled through the repository profile with connection pooling and migration management.

Connection Pool Settings

The system uses HikariCP for database connection pooling with optimized settings:

  • Connection Timeout: 30 seconds
  • Maximum Pool Size: 10 connections
  • Minimum Idle: 5 connections
  • Pool Name: EffectiveOfficeHikariCP

Migration Configuration

Flyway handles database schema migrations with the following settings:

  • Enabled: Controlled by MIGRATIONS_ENABLE environment variable (default: true)
  • Baseline on Migrate: true for existing databases
  • Locations: classpath:db/migration
  • Table: flyway_schema_history

Calendar Integration Configuration

Google Calendar integration uses conditional configuration based on the calendar.provider property.

Calendar Provider Settings

Property Purpose Default/Example
calendar.provider Provider type google or dummy
calendar.default-calendar Default calendar ID From DEFAULT_CALENDAR env var
calendar.application-name Google API app name From CALENDAR_APPLICATION_NAME
calendar.delegated-user Impersonation email From CALENDAR_DELEGATED_USER
calendar.credentials.file OAuth2 credentials classpath:google-credentials.json

Google Calendar Bean Configuration

The GoogleCalendarConfig class provides conditional bean creation:

google-calendar-bean-configuration.svg

Notification Configuration

Calendar subscription and push notification configuration supports both production and test environments.

Calendar Subscription Settings

Property Purpose
calendar.subscription.default-app-email Default application email
calendar.subscription.application-url Production webhook URL
calendar.subscription.test-application-url Test environment webhook URL
calendar.subscription.calendars Production calendar list
calendar.subscription.test-calendars Test calendar list
calendar.subscription.firebase-credentials Firebase service account key

The CalendarSubscriptionScheduler uses these settings to maintain Google Calendar push notification channels with automatic renewal every 6 days.

Deployment Configuration

Docker Compose orchestrates the complete application stack with environment-based configuration.

service-configuration.svg

Key Deployment Settings

  • Application Port: 8080 (exposed internally)
  • Database Port: 5432 (exposed externally for development)
  • Reverse Proxy: Caddy with automatic SSL
  • Health Checks: PostgreSQL readiness checks
  • Restart Policy: unless-stopped for all services
  • Networks: Isolated bridge network with external Caddy network

Configuration Best Practices

Security Considerations

  1. Credential Management: Service account keys stored as external files, referenced via environment variables
  2. Environment Separation: Separate configuration for production and test environments
  3. Database Security: Connection credentials passed through environment variables, not hardcoded
  4. API Keys: JWT-based authentication with API key management through database

Operational Guidelines

  1. Environment Variables: All deployment-specific values externalized to .env files
  2. Profile Usage: Spring profiles separate concerns (repository, calendar provider)
  3. Conditional Configuration: Feature-specific beans loaded only when needed
  4. Health Monitoring: Actuator endpoints exposed for monitoring and health checks
  5. Logging Strategy: Configurable log levels with package-specific granularity

Configuration Validation

The system includes several validation mechanisms:

  • Database Health Checks: PostgreSQL readiness validation in Docker Compose
  • Calendar Provider Validation: Conditional bean loading prevents misconfiguration
  • Migration Safety: Flyway baseline-on-migrate prevents data loss
  • Connection Pool Monitoring: HikariCP provides connection pool metrics
Clone this wiki locally