Skip to content

Deployment

The local deployment uses six services:

  • postgres: PostgreSQL 17 with a persistent named volume;
  • api: Spring Boot application published on port 8989;
  • backend: static Vite build served by Nginx on port 5173.
  • docs: MkDocs site published on port 8000.
  • java-site: Maven Site with aggregated Javadocs published on port 8083.
  • presentation: Marp presentation published on port 8082.

Start the Stack

make docker-up

After startup:

  • Documentation: http://localhost:8000
  • Java Maven Site: http://localhost:8083
  • Java API documentation: http://localhost:8083/apidocs/
  • API health: http://localhost:8989/actuator/health
  • Swagger UI: http://localhost:8989/swagger-ui.html
  • Management console: http://localhost:5173

The local Compose file supplies a development administrator account and JWT secret. The default console login is admin / admin.

Inspect service logs with:

make docker-logs

Stop containers while retaining PostgreSQL data:

make docker-down

Persistence Behavior

The API persists DomainTemplateEntity rows in domain_templates. The Compose volume is named from the project and the declared postgres-data volume; Docker Compose resolves the final volume name automatically.

The API also persists local authentication data in auth_roles, auth_users, and auth_user_roles. At startup it seeds the ADMIN and USER roles, then forces the administrator account from APP_ADMIN_USERNAME and APP_ADMIN_PASSWORD. If that username already exists, the account is enabled, its password hash is replaced from the environment value, and the ADMIN role is guaranteed.

Hibernate uses ddl-auto: update. This is convenient for this solution because it initializes domain_templates, but it does not remove obsolete schema objects. A volume created by an earlier version may therefore still contain domain_records. That table is unused and its presence does not indicate that the current application writes to it.

Reset the Demo Database

Reset the volume when you want to remove all demo data and obsolete tables. This operation is destructive.

docker compose -f docker/compose.yml down --volumes
make docker-up

The second command creates a fresh PostgreSQL volume and Hibernate recreates domain_templates on API startup.

Build Documentation and Slides

make docs-build
make presentation-build

Production Considerations

Keep the API, database, console, and documentation as independently deployable units. Replace ddl-auto: update with versioned migrations, provide managed PostgreSQL credentials through secrets, terminate TLS at the platform edge, and set the console API base URL to the public API origin.

Provide these security variables through the deployment secret store:

Variable Required Purpose
APP_ADMIN_USERNAME Yes Forced administrator username.
APP_ADMIN_PASSWORD Yes Forced administrator password, stored only as a BCrypt hash.
APP_JWT_SECRET Yes JWT HMAC signing secret, at least 32 characters.
APP_JWT_EXPIRATION_SECONDS No Access token lifetime; defaults to 3600 seconds.