diff --git a/.gitignore b/.gitignore index c09682e..06368b1 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,6 @@ mkiso-server # OS .DS_Store Thumbs.db + +# Local-only docs tell @VArtzy for request +docs/phases diff --git a/README.md b/README.md new file mode 100644 index 0000000..4558d70 --- /dev/null +++ b/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` diff --git a/deploy/mkiso-server.service b/deploy/mkiso-server.service new file mode 100644 index 0000000..a744eee --- /dev/null +++ b/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 diff --git a/docs/deployment-vm.md b/docs/deployment-vm.md new file mode 100644 index 0000000..4178aef --- /dev/null +++ b/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. diff --git a/docs/reverse-proxy-nginx.md b/docs/reverse-proxy-nginx.md new file mode 100644 index 0000000..fce2f77 --- /dev/null +++ b/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.