2

Reference MIGRATION_WORKFLOW

Patrick Gniza edited this page 2026-08-17 10:48:39 +02:00

Table of Contents

• Migration Workflow
• Updated Detailed Workflow
• Manual browser workflow
• Windows client workflow
• Restart after restore
• Phase 1: Preparation on the Source System
• Phase 2: Create Migration Job
• Phase 3: Upload Data
• Phase 4: Validate Upload
• Phase 5: Restore

Deutsch | English

Migration Workflow

This document describes the target workflow for migrating an existing Romexis installation into the Docker-based Romexis Server stack.

┌──────────────────────────────┐ │ Existing Romexis Server │ └──────────────┬───────────────┘ │ │ Romexis Migration Client │ ▼ SFTP / REST API │ ▼ ┌──────────────────────────────┐ │ Romexis Migration Service │ │ │ │ • Migration Jobs │ │ • Upload Validation │ │ • Restore Workflow │ └──────────────┬───────────────┘ │ ▼ ┌──────────────────────────────┐ │ Romexis Docker Container │ │ SQL Server │ │ Images │ │ Ergodata │ └──────────────────────────────┘

---

---

Updated Detailed Workflow

created
  -> database_uploaded
  -> database_restored
  -> upload_complete
  -> validated
  -> restored
  -> completed

Final states:

completed
cancelled
failed

Manual browser workflow

1. Create a migration job in the Web UI.
2. Upload the database backup in the browser.
3. The service creates manifest.json automatically.
4. Trigger database restore.
5. Upload file directories via SFTP.
6. Confirm upload complete.
7. Validate upload.
8. Run restore.
9. Complete migration and remove SFTP access.

Windows client workflow

1. Detect Romexis installation.
2. Detect SQL Server configuration.
3. Detect data directories.
4. Create or use a migration job.
5. Create database backup.
6. Upload data via rclone/SFTP.
7. Call API endpoints to advance the migration workflow.
8. Display logs and restore status.

Restart after restore

The migration service and Romexis container communicate via:

/data/romexis_images/.romexis_restart_state

The migration service writes a pending restart request. The Romexis entrypoint stops and restarts the Romexis process, writes the final status and the migration service removes the state file.

Phase 1: Preparation on the Source System

The source system is usually an existing Windows-based Romexis server.

Required data:

• SQL Server database backup (.bak)
• Romexis image directory
• Romexis ergo data directory
• optional cache directory

The cache directory can usually be skipped because it can be regenerated.

---

Phase 2: Create Migration Job

A migration job is created in the web UI.

The service generates:

• migration ID
• SFTP username
• SFTP password
• upload path

---

Phase 3: Upload Data

Recommended tools:

• rclone over SFTP
• WinSCP
• FileZilla
• OpenSSH SFTP

Example using rclone:

rclone copy ./migration-data sftp:upload \
  --transfers 8 \
  --checkers 16 \
  --progress

---

Phase 4: Validate Upload

The migration service validates:

• manifest exists
• SQL backup exists
• image directory exists
• ergo directory exists

Later versions should add:

• checksum validation
• file count comparison
• expected size validation

---

Phase 5: Restore

The restore process performs or coordinates:

1. stop the Romexis server container
2. restore the SQL Server database backup
3. copy data directories into the target volumes
4. fix ownership and permissions
5. start the Romexis server container
6. run a final validation

The current workflow uses explicit state transitions and keeps restart coordination separated through the shared state file.

Romexis Docker Wiki

English · Deutsch

English

• Home

Getting Started

• Project Overview
• Architecture
• Quick Start
• Synology Quick Start
• Use with Docker + WSL in Windows
• Compose Runtime
• Configuration
• Container Images

Runtime Services

• Romexis Admin
• Romexis Client
• mRomexis Web App
• Runtime Layout
• Backup and Restore
• Troubleshooting
• Security

Build System

• Build System
• Local Build Scripts
• Payload Images
• Base Image
• Server Image
• CI/CD Pipeline

Database

• Database Backends
• Microsoft SQL Server
• Firebird

Migration

• Migration Service
• Migration Workflow
• Migration Client

Development

• Developer Guide
• Java Property Agent
• Project Structure
• Release Process
• FAQ

Source Documents

• Source README References

Deutsch

• Startseite

Erste Schritte

• Projektübersicht
• Architektur
• Schnellstart
• Synology Quick Start
• Nutzung mit Docker + WSL unter Windows
• Compose-Runtime
• Konfiguration
• Container-Images

Runtime-Dienste

• Romexis Admin
• Romexis Client
• mRomexis Web App
• Runtime-Layout
• Sicherung und Wiederherstellung
• Fehlerbehebung
• Sicherheit

Build-System

• Build-System
• Lokale Build-Skripte
• Payload-Images
• Base-Image
• Server-Image
• CI/CD-Pipeline

Datenbank

• Datenbank-Backends
• Microsoft SQL Server
• Firebird

Migration

• Migrationsdienst
• Migrationsworkflow
• Migrationsclient

Entwicklung

• Entwicklerhandbuch
• Java Property Agent
• Projektstruktur
• Release-Prozess
• FAQ

Quelldokumente

• README-Quellreferenzen

---

Romexis Docker Project Wiki / Romexis-Docker-Projekt-Wiki

English Home · Deutsche Startseite · English source documents · Deutsche Quelldokumente · Security · Sicherheit

Internal operations and development wiki / Internes Betriebs- und Entwicklungswiki