refactor: phase 2 production requirements

docs/deployment-vm.md

@@ -0,0 +1,63 @@
+# Deploying on a VM
+
+This service is meant to run as a small Go process on a VM or VPS.
+
+A simple setup is enough:
+- the Go binary
+- a local `config.yaml`
+- DCMTK binaries
+- MicroDicom files
+- a reverse proxy in front
+- a `systemd` service to keep the process running
+
+## Suggested layout
+A plain layout is easier to operate:
+
+- app directory: `/opt/dicom-iso`
+- binary: `/opt/dicom-iso/mkiso-server`
+- config: `/opt/dicom-iso/config.yaml`
+- logs: `journalctl` through `systemd`
+- temp work: `/tmp` or another writable local path
+
+## What must exist before start
+The service needs:
+- working DCMTK binaries
+- working PACS access
+- working patient API access
+- working CD publisher access
+- a real MicroDicom directory
+- a writable temp directory
+- a free port range for `storescp`
+
+## Build note
+The build environment cannot depend on public internet access.
+That means the binary must be built through an approved offline-friendly path.
+
+## Running the service
+The simplest production shape is:
+- build the binary
+- copy the binary to the VM
+- place `config.yaml` next to it
+- install the `systemd` unit
+- start the service
+- put nginx in front of it if legacy paths are still needed
+
+## Rollback
+Keep rollback simple:
+- keep the previous binary
+- keep the previous config
+- restart the old version through `systemd`
+
+## First checks after deploy
+After the service starts, verify:
+- the process is running
+- the configured port is listening
+- `/api/health` responds
+- DCMTK paths are valid
+- MicroDicom path is valid
+- one real accession works end to end
+
+## Operational note
+Real secrets must stay out of git.
+Only `config.example.yaml` belongs in the repo.
+The real `config.yaml` should be created on the VM.

docs/reverse-proxy-nginx.md

@@ -0,0 +1,47 @@
+# nginx example
+
+If you still want old URLs like `mkiso.php`, nginx can forward them to the Go service.
+
+This keeps the client side stable while the backend moves to Go.
+
+## Basic idea
+The browser still calls the old path.
+nginx receives that request and passes it to the Go API.
+
+## Example
+
+```nginx
+server {
+    listen 80;
+    server_name _;
+
+    location = /mkiso.php {
+        proxy_pass http://127.0.0.1:8080/api/iso/download$is_args$args;
+    }
+
+    location = /mkiso_multiple.php {
+        proxy_pass http://127.0.0.1:8080/api/iso/download-multiple$is_args$args;
+    }
+
+    location = /send_rimage_multiple.php {
+        proxy_pass http://127.0.0.1:8080/api/iso/print$is_args$args;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8080;
+    }
+}
+```
+
+## If API key auth is enabled later
+If the Go service is protected with `X-API-Key`, nginx can inject that header before proxying.
+That keeps the browser code unchanged.
+
+```nginx
+location = /mkiso.php {
+    proxy_set_header X-API-Key "REDACTED";
+    proxy_pass http://127.0.0.1:8080/api/iso/download$is_args$args;
+}
+```
+
+Do not commit real keys into nginx config stored in git.