diff --git a/Reference-README.md b/Reference-README.md
new file mode 100644
index 0000000..b34ba5d
--- /dev/null
+++ b/Reference-README.md
@@ -0,0 +1,595 @@
+# Romexis Docker
+
+[English](README.md) | [Deutsch](README.de.md) | [Build process](BUILD.md) | [Developer notes](DEVELOPERS.md) | [![Build Status](https://drone.buchhorster.de/api/badges/patrick/romexis-server-docker/status.svg?ref=refs/heads/main)]
+
+> Containerized deployment of Planmeca Romexis Server 6.5 on Linux using Docker, Microsoft SQL Server and a reusable multi-architecture Romexis base image.
+
+---
+
+## Overview
+
+This project builds and runs the Planmeca Romexis Server in Docker.
+
+The build process extracts the required Romexis server files directly from the official Romexis Windows installer package. No Romexis application binaries are stored in this repository.
+
+The current build system is split into payload, base and server image layers:
+
+1. **Romexis Base Image**
+   - Provides the Java 11 runtime with JavaFX support.
+   - Provides Microsoft SQL Server command-line tools.
+   - Provides Firebird client libraries.
+   - Is built separately for `amd64` and `arm64`.
+
+2. **Romexis Server Image**
+   - Uses the Romexis base image.
+   - Downloads and extracts the selected Romexis installer.
+   - Builds the final `/opt/romexis` directory structure.
+   - Adds the Java property agent, runtime scripts and database initialization files.
+
+This separation keeps the final image easier to maintain and allows the shared runtime base image to be reused across multiple Romexis builds.
+
+---
+
+## Features
+
+- Romexis Server 6.5 in Docker
+- Microsoft SQL Server 2022 support
+- Automatic database initialization
+- Persistent storage for all application data
+- Automatic KeyVault and ProgramData preparation
+- Support for existing database volumes
+- Multi-stage Docker build
+- Multi-architecture image publishing for `amd64` and `arm64`
+- Dedicated reusable Romexis base image
+- Mapping-based installer extraction using `romexis-copy-map.tsv`
+- Selective InstallShield CAB extraction
+- Romexis installer versions managed through `romexis-versions.env`
+- No Windows Registry required
+- No RomexisConfig execution required
+- Linux-compatible runtime paths
+- Java property injection through `RomexisPropertyAgent`
+- CI/CD build support through Drone
+
+---
+
+## Architecture
+
+```text
++----------------------+
+|   Romexis Clients    |
++----------+-----------+
+           |
+           | RMI / Romexis protocol ports
+           v
++----------------------+
+|   Romexis Server     |
+|      Docker          |
++----------+-----------+
+           |
+           | JDBC
+           v
++----------------------+
+| Microsoft SQL Server |
+|      Docker          |
++----------------------+
+```
+
+---
+
+## Supported Platforms
+
+The build system supports the following target architectures:
+
+| Architecture | Docker platform | Tag suffix |
+|-------------|-----------------|------------|
+| x86_64      | `linux/amd64`   | `-amd64`   |
+| ARM64       | `linux/arm64`   | `-arm64`   |
+
+The Drone pipeline builds architecture-specific images and then publishes a multi-architecture manifest without an architecture suffix.
+
+---
+
+## Requirements
+
+### Runtime host
+
+- Linux host
+- Docker Engine
+- Docker Compose plugin
+- Network access between Romexis clients and the published RMI ports
+
+### Build host
+
+- Docker Engine with BuildKit support
+- Docker Buildx
+- Docker Compose plugin
+- Access to the Romexis installer download URLs listed in `romexis-payload/romexis-versions.env`
+- Access to the configured container registry
+- Sufficient disk space for installer extraction and image builds
+
+### Recommended resources
+
+- 8 GB RAM
+- 4 CPU cores
+- 20 GB free disk space for runtime
+- Additional free disk space on build hosts for Docker build cache and extracted installer files
+
+---
+
+## Container Images
+
+Images are published to the Gitea Container Registry namespace used by the project.
+
+### Image layout
+
+```text
+gitea.buchhorster.de/patrick/romexis-base-jre:11-amd64
+gitea.buchhorster.de/patrick/romexis-base-jre:11-arm64
+
+gitea.buchhorster.de/patrick/romexis-server:<version>-amd64
+gitea.buchhorster.de/patrick/romexis-server:<version>-arm64
+gitea.buchhorster.de/patrick/romexis-server:<version>
+```
+
+The architecture-specific tags are used internally by the multi-architecture manifest.
+
+### Example pull
+
+```bash
+docker pull gitea.buchhorster.de/patrick/romexis-server:6.5.3.444.203
+```
+
+### Verify installed Romexis version
+
+```bash
+docker run --rm \
+  --entrypoint cat \
+  gitea.buchhorster.de/patrick/romexis-server:6.5.3.444.203 \
+  /opt/romexis/version
+```
+
+---
+
+## Version Handling
+
+The file `romexis-payload/romexis-versions.env` maps supported Romexis versions to official installer URLs.
+
+Example entries:
+
+```text
+6_5_3_444_203=https://content.planmeca.com/files/Planmeca_Romexis_6.5.3.444.203_Win.zip
+6_5_2_189_213=https://content.planmeca.com/files/Planmeca_Romexis_6.5.2.189.213_Win.zip
+```
+
+The build argument `ROMEXIS_VERSION` may contain either a full version or a prefix.
+
+Example:
+
+```bash
+ROMEXIS_VERSION=6.5.3
+```
+
+The build resolves this to the newest matching entry, for example:
+
+```text
+6.5.3.444.203
+```
+
+The resolved version is stored inside the image:
+
+```text
+/opt/romexis/version
+```
+
+---
+
+## Project Structure
+
+```text
+.
+├── docker-compose.yml
+├── docker-compose.build.yml
+├── README.md
+├── README.de.md
+├── BUILD.md
+├── BUILD.de.md
+├── DEVELOPERS.md
+│
+├── romexis-base
+│   └── Dockerfile
+│
+├── romexis
+│   ├── Dockerfile
+│   ├── entrypoint.sh
+│   ├── fix-keystore-alias.sh
+│   ├── init-romexis-db.sh
+│   ├── RomexisPropertyAgent.java
+│   ├── 
+│
+└── data
+    ├── programdata
+    ├── sconfig
+    ├── romexis_images
+    ├── romexis_cache
+    └── romexis_ergodata
+```
+
+---
+
+## Runtime with pre-built images
+
+Use `docker-compose.yml` for normal runtime operation.
+
+```bash
+ROMEXIS_VERSION=6.5.3.444.203 docker compose up -d
+```
+
+View logs:
+
+```bash
+docker compose logs -f
+```
+
+Romexis only:
+
+```bash
+docker compose logs -f romexis
+```
+
+SQL Server only:
+
+```bash
+docker compose logs -f mssql
+```
+
+Stop the environment:
+
+```bash
+docker compose down
+```
+
+---
+
+## Local build with Docker Compose
+
+Use `docker-compose.build.yml` for local builds.
+
+The base image must be built before the Romexis Server image because the server Dockerfile uses the base image via the `ROMEXIS_BASE_IMAGE` build argument.
+
+```bash
+TARGETARCH=amd64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
+TARGETARCH=amd64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml up -d
+```
+
+For an ARM64 build host:
+
+```bash
+TARGETARCH=arm64 docker compose -f docker-compose.build.yml --profile build build romexis-base
+TARGETARCH=arm64 ROMEXIS_VERSION=6.5.3 docker compose -f docker-compose.build.yml build romexis
+```
+
+Further details are documented in [BUILD.md](BUILD.md).
+
+---
+
+
+---
+
+## Current Architecture Update
+
+The project now uses three build layers instead of only base and server images:
+
+1. **Romexis Payload Image**
+   - Built from `romexis-payload/Dockerfile`.
+   - Downloads and extracts the official Romexis installer.
+   - Contains `/opt/romexis` and `/opt/romexis-mssql-db`.
+   - Is architecture-independent and tagged as `romexis-payload:<version>`.
+
+2. **Romexis Base Image**
+   - Built from `romexis-base/Dockerfile`.
+   - Contains Java, JavaFX, SQL tools and common runtime libraries.
+   - Is architecture-specific.
+
+3. **Romexis Server Image**
+   - Built from `romexis/Dockerfile`.
+   - Consumes the payload image and the base image.
+   - Adds Chilkat, the Java Property Agent, runtime scripts and startup logic.
+
+The payload split avoids repeated installer downloads and keeps the final server image build independent from the original ZIP/CAB extraction step.
+
+---
+
+## Migration Service
+
+The repository now includes a Romexis Migration Service and a Windows Migration Client.
+
+The migration service provides:
+
+- Web UI and REST API for migration jobs
+- temporary per-job SFTP credentials
+- browser-based database backup upload
+- automatic server-side `manifest.json` creation
+- SQL Server database restore
+- upload validation
+- file restore workflow
+- migration cancellation and cleanup
+- migration completion with SFTP access removal
+- coordinated Romexis restart through a shared state file
+
+Supported migration paths:
+
+1. **Windows Migration Client**
+   - detects Romexis installation, SQL Server configuration and data directories
+   - creates or uses a database backup
+   - uploads data using rclone/SFTP
+   - communicates with the migration service API
+
+2. **Manual browser and SFTP workflow**
+   - create a migration job in the Web UI
+   - upload the database backup through the browser
+   - let the server generate the manifest
+   - upload `romexis_images`, `romexis_ergodata` and optionally `romexis_cache` via SFTP
+   - validate, restore and complete the migration
+
+The Romexis restart after restore is coordinated through:
+
+```text
+/data/romexis_images/.romexis_restart_state
+```
+
+The migration service writes the restart request, the Romexis entrypoint performs the restart and writes the final status back.
+
+
+## Persistent Data Directories
+
+### sconfig
+
+Mounted to:
+
+```text
+/opt/romexis/sconfig
+```
+
+Contains Romexis server configuration files that should persist across container recreations.
+
+### programdata
+
+Mounted to:
+
+```text
+/programdata/Planmeca/Romexis
+```
+
+This mirrors the Windows `%ProgramData%\Planmeca\Romexis` location and contains the KeyVault and related security files.
+
+### romexis_images
+
+Mounted to:
+
+```text
+/data/romexis_images
+```
+
+Stores patient images.
+
+### romexis_cache
+
+Mounted to:
+
+```text
+/data/romexis_cache
+```
+
+Stores cache data.
+
+### romexis_ergodata
+
+Mounted to:
+
+```text
+/data/romexis_ergodata
+```
+
+Stores ergo and additional Romexis data.
+
+---
+
+## Database Initialization
+
+On first startup:
+
+1. SQL Server starts.
+2. Romexis waits until SQL Server is healthy.
+3. The database `Romexis_db` is created if missing.
+4. The database user `romexis` is created if missing.
+5. Romexis SQL schema and update scripts are imported.
+6. Linux data paths are written to the database.
+
+Initialization is skipped when both the database and the Romexis database user already exist.
+
+The initialization can be disabled:
+
+```yaml
+ROMEXIS_INIT_DB: "0"
+```
+
+Verbose SQL output can be enabled:
+
+```yaml
+DB_CREATE_VERBOSE: "true"
+```
+
+---
+
+## KeyVault and ProgramData
+
+Romexis expects a Windows-like `ProgramData` location. The entrypoint sets:
+
+```bash
+ProgramData=/programdata
+```
+
+The KeyVault path is written to `romexis_server.properties`:
+
+```properties
+SERVER_KEYVAULT_PATH=/programdata/Planmeca/Romexis/sconfig
+```
+
+The entrypoint initializes missing key files from the image defaults:
+
+- `static_keys_default.p12` -> `static_keys.p12`
+- `initial_keyvault.p12` -> `keyvault.p12`
+
+---
+
+## RomexisConfig
+
+`RomexisConfig` is intentionally not executed.
+
+Inside a Linux container, RomexisConfig may attempt to access Windows Registry functions through Advapi32/JNA. The required configuration tasks are handled directly by the Docker entrypoint instead.
+
+Replaced responsibilities:
+
+- KeyVault preparation
+- ProgramData handling
+- Database configuration
+- Linux path configuration
+- Runtime property injection
+
+---
+
+## Advanced Configuration
+
+### Database URL
+
+By default, the entrypoint generates:
+
+```text
+jdbc:sqlserver://<host>:<port>;databaseName=<database>;encrypt=true;trustServerCertificate=true;
+```
+
+You may provide a complete JDBC URL:
+
+```yaml
+ROMEXIS_DB_URL: "jdbc:sqlserver://mssql:1433;databaseName=Romexis_db;encrypt=true;trustServerCertificate=true;"
+```
+
+### Database backend
+
+```yaml
+SERVER_DB: "5"
+```
+
+Value `5` represents Microsoft SQL Server.
+
+### RMI host and ports
+
+```yaml
+SERVER_RMI_HOSTNAME: "192.168.65.177"
+SERVER_RMI_LOW_PORT: "1100"
+SERVER_RMI_HIGH_PORT: "1120"
+```
+
+`SERVER_RMI_HOSTNAME` must be reachable by Romexis clients.
+
+### Property agent
+
+The Java property agent can set Romexis `RxProperties` from environment variables.
+
+Syntax:
+
+```yaml
+PROPERTY_AGENT_SET_<RXPROPERTY_NAME>: "<value>"
+```
+
+Default behavior:
+
+```yaml
+PROPERTY_AGENT_SET_KEY_B_KEYVAULT_PWD_LOCATION_SERVER_PROPERTIES: "true"
+```
+
+This is required for reliable KeyVault handling under Docker/Linux.
+
+---
+
+## Troubleshooting
+
+### Check SQL Server
+
+```bash
+docker compose logs mssql
+```
+
+### Check Romexis
+
+```bash
+docker compose logs romexis
+```
+
+### Test SQL Server connectivity
+
+```bash
+docker exec -it romexis-mssql \
+  /opt/mssql-tools18/bin/sqlcmd \
+  -C \
+  -S localhost \
+  -U sa \
+  -P 'Pwr0mex!s!!!' \
+  -Q "SELECT 1"
+```
+
+### Check resolved Romexis version
+
+```bash
+docker exec -it romexis-server cat /opt/romexis/version
+```
+
+### Keystore alias issues
+
+If Romexis reports:
+
+```text
+Failed to get keystore entry by alias:
+server_certificate_...
+```
+
+run:
+
+```bash
+docker exec -it romexis-server /opt/fix-keystore-alias.sh
+```
+
+---
+
+## Known Limitations
+
+- Only server operation has been tested.
+- `RomexisConfig` is not supported inside the container.
+- Microsoft SQL Server is the primary supported database backend.
+- Firebird client libraries are included in the base image, but the runtime Compose setup currently focuses on SQL Server.
+- Multi-architecture images are supported by the build pipeline; functional validation depends on the target platform and available Romexis components.
+
+---
+
+## License
+
+### Romexis
+
+Planmeca Romexis is proprietary software.
+
+This repository does not contain any Romexis program files. The official installer is downloaded during the build process based on `romexis-versions.env`.
+
+### Chilkat
+
+This project uses the Chilkat library required by Romexis. It is downloaded during the build process for the target architecture.
+
+---
+
+## Disclaimer
+
+This project is not affiliated with Planmeca Oy.
+
+Use at your own risk.
+
+Full backups and testing are strongly recommended before production use.