Skip to content

CONFIGURATION.md

Latest commit

 

History

History
242 lines (176 loc) · 7.83 KB

CONFIGURATION.md

File metadata and controls

242 lines (176 loc) · 7.83 KB
Raw

Configuration Reference

Complete configuration guide for nullInvoice including environment variables, timezone setup, and advanced settings.

Environment Variables

An example configuration file is provided at .env.example. Copy this to .env and adjust values for your environment.

Required Variables

Variable Description Example
TZ System timezone Europe/Sofia, America/New_York, UTC
DB_HOST Database host localhost, mariadb
DB_USER Database username nullinvoice
DB_PASSWORD Database password your_secure_password
DB_NAME Database name nullinvoice
DB_PARAMS JDBC connection parameters (must include serverTimezone) ?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Europe/Sofia

Optional Variables

Variable Default Description
APP_PORT 8080 Application port
DB_PORT 3306 Database port
QUEUE_ENABLED true Master switch for the async invoice generation worker. Set to false to disable the background poller. See Async Queue.

Timezone Configuration

⚠️ CRITICAL: You MUST set the timezone in TWO places:

  1. TZ environment variable - sets the system/application timezone
  2. serverTimezone parameter in DB_PARAMS - sets the database connection timezone

Both values MUST match your database server's timezone to ensure date/time values are correctly interpreted and stored.

Example Configuration

TZ=Europe/Sofia
DB_PARAMS=?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Europe/Sofia

Common Timezone Values

  • UTC - Coordinated Universal Time
  • Europe/London - UK time
  • Europe/Sofia - Bulgaria time
  • America/New_York - US Eastern time
  • America/Los_Angeles - US Pacific time
  • Asia/Tokyo - Japan time

See full list of timezones.

Warning: Mismatched timezones will cause incorrect invoice dates and timestamps.

Session Timeout

By default, UI sessions expire after 30 minutes of inactivity (Spring Boot/Tomcat default). Users will be automatically logged out and redirected to the login page.

To customize the session timeout, add the following to nullInvoice/src/main/resources/application.yml:

server:
  servlet:
    session:
      timeout: 60m  # Options: 15m, 30m, 1h, 2h, etc.

Common Timeout Values

  • 15m - 15 minutes (stricter security)
  • 30m - 30 minutes (default)
  • 1h - 1 hour (convenience for active users)
  • 8h - 8 hours (extended for long sessions)

Security & Best Practices

Authentication Architecture

  • UI Access: Session-based authentication with form login
  • API Access: Stateless Bearer token authentication (API keys)
  • Passwords: BCrypt hashed with 10 rounds
  • API Keys: UUID format, BCrypt hashed, shown once on generation

Production Deployment Checklist

  • ✅ Enable HTTPS/TLS for all connections
  • ✅ Use strong admin password
  • ✅ Generate separate API keys per application/environment
  • ✅ Deploy behind firewall or VPN
  • ✅ Configure rate limiting at reverse proxy level
  • ✅ Set up proper logging and monitoring
  • ✅ Regularly review API key usage (last used timestamps)
  • ✅ Revoke unused or compromised API keys immediately
  • ✅ Keep API keys in environment variables, never in code
  • ✅ Use secure secret management (HashiCorp Vault, AWS Secrets Manager, etc.)

CSRF Protection

  • Enabled for all UI form submissions
  • Disabled for API endpoints (stateless Bearer token auth)

First-Run Security

  • Application is unusable until admin account is created via /setup
  • Setup page is only accessible when no admin exists
  • After setup, requires login for all functionality

Database Configuration

Connection Parameters

The DB_PARAMS variable accepts standard JDBC connection parameters:

DB_PARAMS=?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Europe/Sofia

Common parameters:

  • useSSL=false - Disable SSL (enable in production)
  • allowPublicKeyRetrieval=true - Allow MySQL public key retrieval
  • serverTimezone=Europe/Sofia - Database timezone (REQUIRED)
  • characterEncoding=utf8 - Character encoding
  • autoReconnect=true - Automatic reconnection

Connection Pool

Spring Boot uses HikariCP for connection pooling. Default settings are optimized for most use cases. To customize, add to application.yml:

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 30000

Application Properties

The main configuration file is nullInvoice/src/main/resources/application.yml.

Current Default Configuration

server:
  port: ${APP_PORT:8080}

spring:
  datasource:
    url: jdbc:mariadb://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_NAME:nullinvoice}${DB_PARAMS:?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Europe/Sofia}
    username: ${DB_USER:nullinvoice}
    password: ${DB_PASSWORD:}
  flyway:
    baseline-on-migrate: true
    baseline-version: 1
  jpa:
    open-in-view: false
    hibernate:
      ddl-auto: none
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MariaDBDialect

springdoc:
  api-docs:
    path: /openapi
  swagger-ui:
    path: /swagger

nullinvoice:
  queue:
    enabled: ${QUEUE_ENABLED:true}
    poll-interval-ms: 2000
    batch-size: 10
    max-attempts: 3

Async Queue

The nullinvoice.queue.* block controls the background worker that powers the async invoice generation endpoints (/api/v1/invoice-requests). See the API Reference for endpoint documentation.

Property Env var Default Description
nullinvoice.queue.enabled QUEUE_ENABLED true Master switch. When false, the worker bean is not created - no background polling, no scheduled tasks. The submit endpoint still accepts requests but they will sit at PENDING forever until the worker is enabled.
nullinvoice.queue.poll-interval-ms - 2000 How often (in milliseconds) the worker checks for PENDING rows. The next poll only fires after the previous batch finishes, so this is a minimum gap, not a strict interval.
nullinvoice.queue.batch-size - 10 Maximum number of queue rows fetched per poll cycle. Each row is processed in its own transaction.
nullinvoice.queue.max-attempts - 3 Default cap on retries before a queue row is marked FAILED. The actual cap per row is stored on the row at submit time, so changing this property only affects newly submitted requests.

Disabling the queue. Set nullinvoice.queue.enabled=false (or omit the property) to fully disable the worker. The async endpoints remain available structurally but PENDING requests will accumulate without being processed. Use this if you only want the synchronous generation path.

Customization

You can override these settings by:

  1. Environment variables (recommended for Docker)
  2. Custom application.yml mounted as volume
  3. System properties via JVM args

Example with custom config file:

# docker-compose.yml
volumes:
  - ./custom-application.yml:/app/config/application.yml:ro

Logging

Default logging level is INFO. To customize, add to application.yml:

logging:
  level:
    root: INFO
    com.nullinvoice: DEBUG
    org.springframework: WARN

Or set via environment variable:

LOGGING_LEVEL_COM_NULLINVOICE=DEBUG

Health Checks

Health check endpoint: GET /api/v1/health

Returns 200 OK when the application is healthy (no authentication required).

Example Docker health check:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s