refactor: phase 2 production requirements

.gitignore

@@ -17,3 +17,6 @@ mkiso-server
 # OS
 .DS_Store
 Thumbs.db
+
+# Local-only docs tell @VArtzy<farrelnikoson@gmail.com> for request
+docs/phases

README.md

@@ -0,0 +1,82 @@
+# dicom-iso
+
+This repo is a Go service for downloading DICOM studies from PACS, building ISO files, and relaying studies to a CD publisher.
+
+It replaces the old PHP scripts, which are now kept in `legacy/` only for reference.
+
+## What is in the repo
+- `main.go` and `internal/`: the Go application
+- `pkg/`: lower-level helpers
+- `config.example.yaml`: config template
+- `docs/`: project notes
+- `legacy/`: old PHP scripts and raw reference files
+
+## Important constraints
+- no secrets in the repo
+- no outbound internet in the build environment
+- restricted package sources
+
+## Runtime dependencies
+The service needs:
+- DCMTK binaries
+- PACS access
+- patient API access
+- CD publisher access
+- MicroDicom files
+- writable temp storage
+
+## Setup
+Before running the service, make sure the VM has:
+- Go installed, if you are building on that machine
+- DCMTK binaries available
+- MicroDicom files in a real directory
+- network access to PACS, the patient API, and the CD publisher
+- a writable temp directory
+
+Create a local config file from the template:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+Then adjust the paths, hosts, ports, and tokens for your environment.
+
+## Build
+A normal Go build is enough in a friendly environment:
+
+```bash
+go build -o mkiso-server .
+```
+
+In production, the build must follow your approved offline package path.
+This repo should not depend on live public downloads during a restricted build.
+
+## Run
+You can run the service directly:
+
+```bash
+./mkiso-server
+```
+
+Or pass a config path explicitly:
+
+```bash
+./mkiso-server /path/to/config.yaml
+```
+
+By default, the app looks for `./config.yaml`.
+
+## Health check
+After startup, check:
+
+```bash
+curl http://127.0.0.1:8080/api/health
+```
+
+## Config
+Use `config.example.yaml` as the starting point.
+Keep real `config.yaml` local and untracked.
+
+## More notes
+- VM deployment: `docs/deployment-vm.md`
+- nginx example: `docs/reverse-proxy-nginx.md`

deploy/mkiso-server.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=mkiso Go service
+After=network.target
+
+[Service]
+Type=simple
+User=mkiso
+WorkingDirectory=/opt/dicom-iso
+ExecStart=/opt/dicom-iso/mkiso-server /opt/dicom-iso/config.yaml
+Restart=on-failure
+RestartSec=5
+
+# Keep logs in journald
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target

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.