Build

dotnet publish -c Release -r win-x64 --self-contained false -o ./publish

Adjust -r for your platform: win-x64, win-arm64, linux-x64, linux-arm64.

Windows Service

The gateway can be installed using PowerShell (Run as Administrator):

New-Service -Name "SecurePACSVaultGateway" `
  -BinaryPathName "C:\Path\To\Gateway\SecurePACS.Vault.Gateway.exe" `
  -DisplayName "SecurePACS Vault Gateway" `
  -Description "Receives DICOM studies and uploads them to SecurePACS." `
  -StartupType Automatic

Start-Service "SecurePACSVaultGateway"

Linux (systemd)

Create /etc/systemd/system/SecurePACS-gateway.service:

[Unit]
Description=SecurePACS Vault Gateway
After=network.target

[Service]
Type=notify
ExecStart=/path/to/gateway/SecurePACS.Vault.Gateway
WorkingDirectory=/path/to/gateway
User=gatewayuser
Group=gatewaygroup
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then run: sudo systemctl enable --now SecurePACS-gateway

When the gateway starts without a configured Gateway:SecurePacs:PublicKeyId it enters Setup Mode. In Setup Mode the gateway starts a minimal web server and redirects all requests to /setup.html — a guided browser wizard that collects the required settings.

What the Wizard Collects

• Gateway Instance ID
• SecurePACS Public Key ID and Base URL
• DICOM AE Title and listener port
• Storage and database paths
• Optional admin password (hashed before saving)

How It Works

1. The wizard calls GET /api/setup/status to confirm it is in Setup Mode.
2. A folder-browser widget calls POST /api/setup/folders/list (loopback only) to help select local paths.
3. On completion, the wizard calls POST /api/setup/save which writes appsettings.Local.json and restarts the gateway into normal operational mode after a 2-second delay.

Cleanup Policy Values

By default the dashboard is served over plain HTTP on loopback only (http://127.0.0.1:11113). When you enable HTTPS, the gateway adds a separate HTTPS endpoint — it does not replace the existing HTTP one. Both listeners run simultaneously: HTTP stays on its original port (e.g. 11113, loopback only), and HTTPS is added on port + 1 (e.g. 11114, all interfaces) by default. This way loopback health checks remain available over plain HTTP while external access uses HTTPS.

You need a PFX/PKCS#12 certificate to enable HTTPS. Self-signed certificates are fine for testing; see the section below for generation commands.

Option A — Via the Dashboard (Recommended)

1. Open http://127.0.0.1:11113 and navigate to Settings → HTTPS Configuration.
2. Upload your PFX certificate file with its password and click Upload & Save. The certificate is written to data/certs/ and saved as the GatewayDefault certificate entry.
3. In the Network settings, add a new HTTPS endpoint referencing GatewayDefault and click Save Changes.
4. Restart the gateway (via the System → Restart button or the service manager) to activate HTTPS.

Option B — Via the API

Upload the certificate, then add the HTTPS endpoint via PATCH /config, then restart:

# Step 1: Upload the certificate (saves as GatewayDefault, does not add endpoint automatically).
curl -X POST http://127.0.0.1:11113/certs/upload \
  -H "X-Gateway-Admin: true" \
  -F "file=@/path/to/cert.pfx" \
  -F "password=secret"

# Step 2: Add the HTTPS endpoint via config PATCH.
curl -X PATCH http://127.0.0.1:11113/config \
  -H "X-Gateway-Admin: true" \
  -H "Content-Type: application/json" \
  -d '{"Network":{"Endpoints":{"StatusApiHttps":{"Url":"https://0.0.0.0:11114","Certificate":"GatewayDefault"}}}}'

# Step 3: Restart to activate.
curl -X POST http://127.0.0.1:11113/system/restart -H "X-Gateway-Admin: true"

Option C — Manual Edit

Add a StatusApiHttps entry alongside the existing StatusApi entry in appsettings.Local.json, then restart. The HTTP endpoint is untouched:

{
  "Gateway": {
    "Network": {
      "Endpoints": {
        "StatusApi": {
          "Url": "http://127.0.0.1:11113/"
        },
        "StatusApiHttps": {
          "Url": "https://0.0.0.0:11114",
          "Certificate": "GatewayDefault",
          "MinTlsVersion": "Tls12"
        }
      },
      "Certificates": {
        "GatewayDefault": {
          "Source": "File",
          "Path": "data/certs/THUMBPRINT.pfx",
          "Password": "secret"
        }
      }
    },
    "StatusApi": {
      "AllowNonLoopbackPrefixes": true,
      "BearerToken": "your-secret-token"
    }
  }
}

DICOM TLS

The same dual-port pattern applies to the DICOM listener. To run both plain DICOM and DICOM-TLS simultaneously, add a second endpoint alongside the existing one:

{
  "Gateway": {
    "Network": {
      "Endpoints": {
        "DicomListener": {
          "Url": "dicom://0.0.0.0:11112"
        },
        "DicomListenerTls": {
          "Url": "dicomtls://0.0.0.0:11113",
          "Certificate": "GatewayDefault"
        }
      }
    }
  }
}

Convention: TLS port = plain port + 1. Modalities that support DICOM-TLS can connect on the TLS port; legacy modalities continue on the plain port. Both listeners run at the same time with no interaction.

Generating a Self-Signed Certificate (Testing Only)

Windows (PowerShell):

$cert = New-SelfSignedCertificate -DnsName "localhost" -CertStoreLocation "cert:\LocalMachine\My"
$pwd  = ConvertTo-SecureString "YourPassword" -AsPlainText -Force
Export-PfxCertificate -Cert $cert -FilePath "data\certs\gateway.pfx" -Password $pwd

Linux / macOS (openssl):

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"
openssl pkcs12 -export -out data/certs/gateway.pfx -inkey key.pem -in cert.pem -passout pass:YourPassword

All configuration keys can be set via environment variables using double-underscores as the hierarchy separator:

Gateway__SecurePacs__PublicKeyId=your-key-id
Gateway__SecurePacs__BaseUrl=https://secure.dicom.link
Gateway__SecurePacs__BearerToken=optional-securepacs-token
Gateway__Storage__DeleteRawFilesAfterUpload=true
Gateway__Cleanup__Enabled=true
Gateway__Network__Certificates__GatewayDefault__Password=cert-password
Gateway__UploadWorker__ParallelFileUploads=4
Gateway__Hosting__EnableSelfRestart=true

For Linux systemd units, add them to the [Service] section:

[Service]
Environment="Gateway__SecurePacs__PublicKeyId=your-key-id"
Environment="Gateway__StatusApi__BearerToken=your-secret-token"

For Windows services, set them via the service properties or in the system environment variables. The gateway picks them up on next start.

The Study Lifecycle

DICOM lacks an explicit "End of Study" signal. The gateway uses a Settling Mechanism to determine when a study is ready for upload.

Study Status States

1. Study Settling

The StudySettlingService scans the local database for studies in the Receiving state every StudySettling:ScanInterval (default 30 seconds). If no new instances have been received for StudySettling:InactivityTimeout (default 10 minutes), the study is marked Settled and moved to the upload queue.

2. Secure Upload Worker

The upload worker processes studies one at a time to ensure system stability. It performs the following steps:

• Metadata Extraction: Scans local files to build a complete SecurePACS study map and study info objects.
• Local Encryption: Fetches the public key from SecurePACS, generates an ephemeral ECDH P-521 keypair, derives a shared secret, and creates an AES-256-CBC data key. All DICOM files are zstd-compressed (level 3) and AES-CBC encrypted before upload.
• Multipart Upload: Transmits encrypted DICOM files to SecurePACS. Tune UploadWorker:ParallelFileUploads (1–4) to speed up large study transfers.
• Finalization: Sends encrypted study map, study info, and metadata to the SecurePACS finalize endpoint.

3. Retry Policy

Failed uploads are retried automatically. Each attempt uses an exponential back-off:

Set UploadWorker:MaxAttempts = 0 for unlimited retries. Any positive value marks the study FailedPermanent after that attempt count. Failed studies can be manually reset to Settled via the dashboard or POST /studies/{uid}/retry.

4. Cleanup Policies

Once a study is successfully uploaded, the StudyCleanupService manages the local files based on your policy (see the Cleanup configuration table above). Both Cleanup:Enabled = true and Storage:DeleteRawFilesAfterUpload = true must be set for any automatic deletion to occur.

5. Database Maintenance

The gateway automatically maintains its SQLite database. Every DatabaseAdmin:MaintenanceInterval (default 24 hours), the scheduled maintenance task runs:

• Integrity Check: Verifies the database file is not corrupted.
• Vacuum (if EnableScheduledVacuum = true): Reclaims unused space and defragments the database.

On-demand vacuum, index rebuild, integrity check, backup, and restore are also available via the Database page in the dashboard or the /db/* API endpoints.

6. Upload Audit Trail

Every upload attempt is persisted in the database with start time, end time, result, error message, and the SecurePACS study ID assigned for that attempt. View the full audit trail for any study via GET /studies/{uid}/attempts or the study detail modal in the dashboard.

Opening the gateway URL (default http://127.0.0.1:11113) in any modern browser loads the management dashboard. It has five pages accessible from the left sidebar:

Authentication

The dashboard uses cookie-based authentication. Two modes of operation exist:

• Open mode (no password configured): all endpoints are accessible without authentication. Suitable for loopback-only installs during initial setup. A warning is printed at startup and displayed in the dashboard.
• Password mode (AdminPasswordHash set): a login form is shown on first visit. After successful login a GatewaySession HttpOnly cookie is issued. Sessions last 8 hours with sliding expiration. Changing the password invalidates all existing sessions immediately.

• Exception — anonymous loopback: GET /health is always accessible from 127.0.0.1 / ::1 without authentication (useful for health-probe scripts).
• Auth endpoints (/auth/login, /auth/logout, /auth/status) are reachable without a valid session.
• State-changing requests (POST, PATCH, DELETE) must include the X-Gateway-Admin: true header as an additional safety guard against accidental writes.
• Rate limiting: POST /auth/login and POST /auth/change-password are limited to 5 requests per 15 minutes per IP. Exceeded attempts receive HTTP 429 with a Retry-After: 900 header.

Authentication Endpoints

System & Status

Studies

Connections

Configuration

Logs

Database

Certificates

Log Inspection

Logs are the first line of defense. Check data/logs/gateway.log for overall activity and data/logs/gateway.errors.log for failures. The dashboard Logs page provides a filterable view without opening files.

Common Issues

• Modality can't connect: Check that port 11112 (or your configured DICOM port) is open in Windows Firewall or Linux iptables. Ensure the called AE Title matches the gateway's configured Dicom:AeTitle.
• Studies stuck in Receiving: This is normal when InactivityTimeout is long and the modality is still sending. Check the Connections dashboard page to confirm whether the association is still active.
• Upload failures — 404 Not Found: The PublicKeyId is invalid or does not exist on the SecurePACS server. Check the startup banner and the /status API for a validation note.
• Upload failures — 401 / 403: Incorrect SecurePacs:BearerToken (if configured). Check the SecurePACS server logs for more details.
• HTTPS not working after save: A restart is required to apply HTTPS changes. Use the dashboard's System → Restart button or your service manager. After restart, connect on the HTTPS port (e.g. 11114), not the original HTTP port. Also verify that the HTTPS endpoint referencing GatewayDefault was saved to configuration (Settings → Network) before restarting.
• Dashboard returns 401 / login loop: Either no password is configured (open mode, should not redirect) or your session expired. Open /auth/status to check. If openMode: false, log in again at /auth/login. If you forgot the password, use POST /system/config/reset from loopback to delete the local settings and re-run setup.
• Dashboard returns 403: All state-changing requests require the X-Gateway-Admin: true header. Add it to your API call.
• Login rate-limited (HTTP 429): More than 5 login attempts were made from the same IP within 15 minutes. Wait for the Retry-After: 900 period to pass.
• Disk full: Ensure both Cleanup:Enabled = true and Storage:DeleteRawFilesAfterUpload = true. If using ManualReview policy, studies must be individually approved. The dashboard Database → Vacuum can reclaim space from the SQLite file itself.
• Database restore not applied: Staged restores are applied on the next gateway startup. Restart the service after uploading a restore file.

Encryption Protocol

The gateway uses the SecurePACS Cryptographic Protocol:

• An ephemeral ECDH P-521 key pair is generated for each study upload.
• A 256-bit AES data key is generated using a cryptographically secure random number generator (RandomNumberGenerator.Fill).
• An ECDH shared secret is derived from the ephemeral private key and the server's P-521 public key.
• Each DICOM file is zstd-compressed (level 3) and AES-CBC encrypted with the data key before being transmitted.
• Study metadata (map, info) is also compressed and encrypted. Only the holder of the server-side private key can decrypt it.

Data at Rest

Raw DICOM files are stored in data/studies. These files contain PHI and are not encrypted at rest by the gateway itself. It is strongly recommended to use OS-level disk encryption (BitLocker on Windows, LUKS on Linux) to protect the data directory.

Dashboard Security

The status API defaults to loopback-only access. If you expose it to other network interfaces:

• Always set an admin password via the dashboard Settings → Security page (POST /auth/change-password).
• Always enable HTTPS to prevent credential interception (the session cookie is HttpOnly but still transmitted in plaintext over plain HTTP on non-loopback).
• Restrict firewall access to trusted IP ranges.