---
title: Rehost Spring Boot Service to VM
description: "Executable migration runbook for rehosting a Spring Boot JAR and PostgreSQL to one STACKIT VM with rehearsal, evidence-based cutover, validation, and rollback."
sidebar:
  badge:
    text: "STACKIT"
    variant: success
scfAsset:
  managed: false
  category: "runbook"
  external: false
  tags: ["design-and-mobilize", "design", "runnable-example", "rehost", "spring-boot", "migration", "vm"]
  maintainers:
    - user: "lukas.weberruss"
      role: true
      website: true
source_url: "https://framework.stackit.cloud/migration/assetcontainer/stackit/runbook-rehost-spring-boot/"
source_file: "docs/migration/assetcontainer/stackit/runbook-rehost-spring-boot.mdx"
---

## Use Case

- **Migration strategy**: Rehost (lift and shift)
- **Application type**: Spring Boot service (JAR), no Kubernetes target
- **Target platform**: VM-based runtime on STACKIT
- **Data backend**: PostgreSQL

## Scope and Assumptions

- **In scope**: Terraform provisioning, Ansible configuration, source dump evidence, temporary-database
  rehearsal, controlled restore, runtime validation, rollback, Observability, and Server Backup schedule.
- **Out of scope**: Code refactoring, database engine change, load balancing, DNS switch, TLS termination,
  multi-VM availability, Kubernetes, Cloud Foundry, and PostgreSQL Flex.
- **Assumptions**: The source uses a PostgreSQL version compatible with the target restore tools, and
  approved source CIDRs are known for SSH and application access.

## Roles and Ownership

- **Migration lead**: Coordinates timeline, checkpoints, and go/no-go decision.
- **Application owner**: Validates app behavior and business-critical user journeys.
- **Platform engineer**: Prepares the VM, restricted network rules, monitoring, and backup schedule.
- **DB owner**: Executes DB backup, restore, consistency checks, and rollback trigger.
- **Operations owner**: Accepts handover and owns Day-1/Day-2 incident response.

## Pre-Migration Checks

- **Access readiness**: SSH, deployment credentials, DB access, secrets access validated.
- **Baseline captured**: Current versions, environment variables, ports, certificates, scheduled jobs documented.
- **Capacity validated**: CPU, RAM, disk IOPS, and storage capacity on target VM confirmed.
- **Security controls ready**: Firewall rules, IAM mapping, TLS cert chain, and logging in place.
- **Source evidence ready**: Dump checksum, expected record count, and deterministic data fingerprint recorded.
- **Rollback readiness**: Pre-restore dump path, expected original record count, authority, and deadline agreed.

## Run Plan (Cutover Window)

### Phase 1: Prepare target runtime

1. Create target app user and required filesystem layout.
2. Install Java runtime and supporting OS packages.
3. Deploy app artifact to target path.
4. Configure service unit (systemd) and environment file.
5. Install self-managed PostgreSQL, create the application role and database, and restrict access to localhost.
6. Enable node exporter, Observability scraping, and the Server Backup schedule.

### Phase 2: Data and config alignment

1. Create a custom-format PostgreSQL dump without source ownership or privileges.
2. Record and validate its checksum, expected row count, and deterministic fingerprint.
3. Run `./scripts/run_migration_rehearsal.sh` against a temporary target database.
4. Confirm that rehearsal removed its temporary database and left the production target database unchanged.
5. Verify the original target rollback dump in a separate temporary database.

### Phase 3: Cutover and release

1. Freeze source writes and create the final approved dump.
2. Run `./scripts/run_cutover.sh --confirm` with the approved source evidence.
3. Require the saved Terraform plan to change only the Ansible orchestration resource.
4. Validate row count, fingerprint, ownership, application-role write behavior, services, and endpoint.
5. Require a final Terraform no-op plan, record acceptance, and start stabilization watch.

## Validation Checklist

- **Technical health**: Spring Boot, PostgreSQL, and node exporter active; local and approved public HTTP checks pass.
- **Functional checks**: The application returns the migrated Spring Music records.
- **Data checks**: Expected row count and fingerprint match; table ownership belongs to the application role.
- **Security checks**: Runtime environment and rollback dump have root-only or database-owner-only permissions.
- **Operations checks**: Observability scrape, Server Backup schedule, evidence files, and escalation ownership verified.

## Rollback Criteria and Steps

### Rollback triggers

- **Critical functional failure**: Core business flow unavailable after fix window.
- **Data integrity risk**: Mismatch in critical records with no fast remediation.
- **Operational instability**: Repeated restarts or unresolved severe alerts.

### Rollback steps

1. Invoke the approved rollback decision before the deadline and preserve logs and evidence.
2. Run `./scripts/rollback_postgresql.sh --confirm` to stop Spring Boot and preserve the current target database.
3. Restore the protected pre-cutover dump and validate the expected original row count.
4. Restart Spring Boot and validate local and approved public reachability.
5. Resume the agreed source or target operating state and publish the rollback evidence and decision.

## Handover to Operations

- **Artifacts delivered**: Final config set, deployment manifest, validation evidence, rollback log.
- **Ownership transfer**: Named on-call owner and escalation route confirmed.
- **Stabilization period**: 24-72 hours with enhanced monitoring and daily status check.
- **Exit criteria**: No critical alerts, stable key metrics, and business owner sign-off.

## Evidence Log Template

| Checkpoint                     | Owner             | Timestamp        | Result    | Evidence Link |
| ------------------------------ | ----------------- | ---------------- | --------- | ------------- |
| Target VM runtime prepared     | Platform engineer | YYYY-MM-DD HH:MM | Pass/Fail | link          |
| Rehearsal completed            | DB owner          | YYYY-MM-DD HH:MM | Pass/Fail | link          |
| DB restore and integrity check | DB owner          | YYYY-MM-DD HH:MM | Pass/Fail | link          |
| Terraform no-op confirmed      | Platform engineer | YYYY-MM-DD HH:MM | Pass/Fail | link          |
| Post-cutover business checks   | Application owner | YYYY-MM-DD HH:MM | Pass/Fail | link          |
| Handover accepted              | Operations owner  | YYYY-MM-DD HH:MM | Pass/Fail | link          |