From 12520ff9961c6af9fb19a2ac952f4be3b7e30b7e Mon Sep 17 00:00:00 2001
From: Patrick Gniza <pgniza@gmx.de>
Date: Sun, 28 Jun 2026 19:46:55 +0000
Subject: [PATCH] =?UTF-8?q?Developer=20Guide=20hinzugef=C3=BCgt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Developer-Guide.md | 121 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 Developer-Guide.md

diff --git a/Developer-Guide.md b/Developer-Guide.md
new file mode 100644
index 0000000..7f66181
--- /dev/null
+++ b/Developer-Guide.md
@@ -0,0 +1,121 @@
+# Developer Guide
+
+This page describes the internal project structure and development workflow.
+
+---
+
+## Main Project Directories
+
+```text
+romexis-base/
+  Runtime base image.
+
+romexis-payload/
+  Windows installer payload extraction.
+
+romexis-firebird-payload/
+  macOS Firebird SQL payload extraction.
+
+romexis/
+  Final Romexis Server image.
+
+migration-service/
+  Migration Web UI, REST API, SFTP and restore orchestration.
+
+migration-client/
+  Source-side migration helper client.
+
+docs/
+  Extended markdown documentation.
+```
+
+---
+
+## Development Principles
+
+- Keep proprietary binaries out of Git.
+- Keep installer extraction in payload images.
+- Keep runtime dependencies in the base image.
+- Keep final server image focused on assembly and runtime logic.
+- Keep MSSQL and Firebird initialization separated.
+- Use the wrapper script only for backend routing.
+- Prefer explicit validation over silent incomplete images.
+
+---
+
+## Database Init Scripts
+
+```text
+init-romexis-db.sh
+  Routes to backend-specific init script.
+
+init-romexis-mssql-db.sh
+  Handles SQL Server initialization.
+
+init-romexis-firebird-db.sh
+  Handles Firebird initialization.
+```
+
+Do not put backend-specific required variables in the wrapper.
+
+Example:
+
+```bash
+MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:?MSSQL_SA_PASSWORD is required}"
+```
+
+must only be in the MSSQL script, not in the wrapper.
+
+---
+
+## Version-Aware Database Updates
+
+The database init scripts use an explicit Romexis update order.
+
+This is required because markers do not sort numerically.
+
+Example:
+
+```text
+600, 610, 63, 64, 651, 652, 653
+```
+
+The script resolves the target marker from `/opt/romexis/version` and runs updates until that marker.
+
+---
+
+## Testing Image Contents
+
+```bash
+docker run --rm --entrypoint find \
+  gitea.buchhorster.de/patrick/romexis-server:<tag> \
+  /opt -maxdepth 3 -type f | sort
+```
+
+Open shell:
+
+```bash
+docker run --rm -it --entrypoint bash \
+  gitea.buchhorster.de/patrick/romexis-server:<tag>
+```
+
+---
+
+## Local Debug Compose Override
+
+```yaml
+services:
+  romexis:
+    entrypoint:
+      - /bin/bash
+      - -c
+      - sleep infinity
+    stdin_open: true
+    tty: true
+```
+
+Then:
+
+```bash
+docker compose exec romexis bash
+```