The Carino DICOM manual

Carino DICOM is a DICOM gateway and a continuity appliance: it receives studies, routes and forwards them, publishes what it holds over Query/Retrieve and DICOMweb, and keeps an imaging department working when the PACS or the RIS stops answering. This manual covers deployment, the security model, every service, and the software's real limits.

Every screenshot here is a live instance of this software, holding studies that were invented for the picture. No patient appears anywhere in this manual.

1. What it is and what role it plays

Carino DICOM sits between the equipment that produces images and the systems that store or read them. It is not trying to replace your archive; it is trying to be the piece that connects them, and the piece still standing when one of the others falls over.

It plays two roles, and the distinction matters because it decides which services you enable:

• Permanent gateway. Receives over C-STORE, files to disk by patient/study/series, forwards to one or many destinations according to rules, de-identifies the outgoing copy when asked, and publishes what it holds over Query/Retrieve (for older equipment) and DICOMweb (for modern viewers).
• Safety net. If the primary PACS stops answering, it can bring up its own Modality Worklist so technologists keep scanning, hold what arrives during the outage, and forward it automatically once the primary is back. It also takes HL7 orders over MLLP — or hand-keyed ones — when the RIS is what went down.

Everything is driven by one config.json, and everything runs headless. The web dashboard is convenient, not required.

Default ports

2. Getting started

Pick a deployment shape

Desktop app

Download the package for your OS from the releases page and open it. It tucks into the system tray; clicking it opens the dashboard. It is not code-signed yet, so Windows and macOS warn on first launch — the landing page has the exact steps to open it anyway.

On first run it asks, once, whether it may check GitHub for a newer version. Answering no — or closing the question — leaves it off, which is the default. If it is on, a newer release shows up as a line in the tray menu and beside the version on the Overview panel; clicking either opens the release page in your browser. Nothing is downloaded and nothing installs itself. The tray menu's Check for updates tick turns it on or off whenever you like, and only this desktop build has it at all — the container and systemd deployments do not.

Docker

git clone https://github.com/MiguelCarino/Carino-DICOM
cd Carino-PACS
mkdir -p data && sudo chown -R $(id -u):$(id -g) data
docker compose up -d
docker compose logs -f pacs

The first boot generates and prints an access token into the log. Open http://127.0.0.1:8042/ and paste it when the dashboard asks. Everything — config, studies, logs, index — lives in ./data, which is what you back up.

systemd service (Linux)

git clone https://github.com/MiguelCarino/Carino-DICOM.git
cd Carino-PACS
sudo packaging/systemd/install.sh

The installer creates the carino-pacs system user, copies the code to /opt/carino-pacs, provisions /var/lib/carino-pacs, and installs the unit… and does not start it. That is not an oversight: starting a PACS opens listeners that accept patient data, and that decision belongs after reading the config, not before. Edit /var/lib/carino-pacs/config.json, then:

sudo systemctl enable --now carino-pacs
systemctl status carino-pacs
journalctl -u carino-pacs -f

Re-running the installer upgrades the code in place and never touches an existing config.json.

Where the data lives

config.json lives with the data, not in /etc, because relative paths in the config ("./received", "./logs", "./index.db") resolve against the directory the config file itself sits in. A config in /etc would scatter patient studies through /etc.

First run, in order

1. Choose the services. Everything ships off. The dashboard's setup chooser asks what this machine should run; enable only that.
2. Add your destinations (name, host, port, AE title) on the Destinations tab of Configuration, which is the tab that row opens on.
3. Prove connectivity with C-ECHO before moving a single image: ./run.sh echo --name "Hospital PACS". If C-ECHO fails, the problem is not Carino — it is the network, the firewall or the AE title.
4. Point one device at it using the receiver's AE title, IP and port, and send a test study.
5. Watch the activity log, on the Logs tab of Activity. If something fails it shows up there; this software would rather shout than fail quietly.

Headless

./run.sh init            # scaffold config.json and its folders
./run.sh init --token    # and generate web.auth_token
./run.sh serve           # dashboard at http://127.0.0.1:8042
./run.sh receive         # receiver only
./run.sh send            # folder watch / forwarding only
./run.sh qr              # Query/Retrieve only
./run.sh mwl             # worklist only
./run.sh ris             # HL7 order listener only
./run.sh print           # virtual printer only
./run.sh echo --host 10.0.0.5 --port 104 --aet REMOTEPACS

Every command takes -c / --config <path>. On Windows, run.ps1.

3. The security model and the token rule

Start with the part that matters: the dashboard is the key to the archive. Anyone who opens it can read every stored study, download the DICOM files, change every setting, start and stop services, delete studies and shut the server down. Out of the box there is one shared secret and whoever holds it can do everything — profiles are optional and off until you turn them on. Once you do, each person signs in as themselves with their own permissions, their own view of patient identifiers, and their own name in the audit trail; the shared token keeps working as an administrator so nothing that already uses it breaks.

Permissions also decide what the dashboard draws. A profile sees only the sidebar rows, and only the tabs inside them, that its capabilities pay for: a Radiologist who holds routing.read but not config.read gets Configuration with Destinations and Routing and no Settings tab, and Reception, holding none of the three, has no Configuration row at all. The service chips in the top header are the deliberate exception — see Web dashboard below.

The rule

The reason is concrete. Unauthenticated on 127.0.0.1, the operating system is the access control: only a process on this machine can reach the API. That is defensible. But web.host is operator-configurable, and the moment somebody changes it to 0.0.0.0 so they can "get in from the other PC" — in a hurry, on a Tuesday, not thinking about security — that same API hands any LAN neighbour the study list, the storage paths, the DICOM bytes and /api/shutdown. The rule exists because that change takes ten seconds and its consequences last years.

Every container is always in that situation: a container publishes on 0.0.0.0 by construction. So the image generates a 256-bit token on first boot when you do not supply one — and prints it. What it never does is generate one quietly: a secret nobody sees is a secret nobody rotates.

Generating and presenting the token

./run.sh init --token                                  # writes it into config.json
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
openssl rand -base64 32

The server accepts the credential three ways:

• Authorization: Bearer <token>
• X-Carino-Token: <token>
• a session cookie issued by POST /api/login

The cookie exists so the dashboard asks for the token once instead of holding it in JavaScript, where every XSS and every browser extension can read it. It never carries the token: it carries an HMAC over a secret generated at startup and kept in memory only. That is why a restart logs everyone out — the right trade for a single-operator appliance: no session store on disk, nothing to leak, and at worst the token is retyped once a shift.

The DICOM side

• allowed_aets — an allow-list of calling AE titles. Empty means "accept anyone". It is a useful filter, not authentication: DICOM does not authenticate the caller.
• DICOM-TLS — available on both sides, independently, including mutual TLS with a client certificate. It uses the same port: a plaintext peer cannot talk to a TLS receiver, and vice versa. TLS encrypts and authenticates the transport, not the application — combine it with allowed_aets or client certificates for real access control.
• Firewall — the DICOM listeners bind 0.0.0.0 by default (though every listener is off until you enable it). That is right for something modalities must reach, and it means restricting them to the modality subnet is your job.

What the model does not protect

• Profiles are off until you turn them on. Until then there is one shared secret for the whole appliance and no accounts, no roles and no permissions. That is still the default, because switching it on silently during an upgrade would break every machine client on the site.
• No directory integration. Accounts live on the appliance. There is no LDAP, no Active Directory, no single sign-on, and no way to disable somebody centrally when they leave.
• The audit trail can be truncated. It catches a record edited in place, one removed from the middle, records reordered, and a file cut mid-line — each breaks a digest and Check integrity names the record and the reason. It cannot catch the last few records being deleted, because what remains is a genuinely valid chain, and it cannot stop a wholesale rewrite by somebody with write access to the audit folder. If you need non-repudiation, copy the chain head somewhere this machine cannot write and compare it later.
• No encryption at rest. Studies are ordinary DICOM files, the sqlite index holds names and identifiers in the clear, orders are JSON, and config.json holds the token in plaintext. Encrypt the volume underneath (LUKS, BitLocker, FileVault) and restrict the data directory's permissions.
• The HL7/MLLP listener has no TLS and no credential. It is a TCP socket with MLLP framing. Its only control is allowed_hosts, a peer-address check and therefore spoofable. Anyone who can open a connection to that port can inject orders that appear on the worklist. Bind it to a trusted clinical segment and firewall it.
• De-identification does not touch pixels. See that service below: burned-in demographics survive every profile.

4. The services, one by one

Everything that opens a port ships off. The right question is not "what can it do?" but "what does this machine need to do?" Every enabled service is one more open port. The index below is the one exception — it starts on its own, because it is a local sqlite cache that binds nothing.

Receiver — Storage SCP

Port 11112 · C-STORE, C-ECHO

What it does

Accepts studies pushed by modalities and files them to disk, optionally organised by Patient / Study / Series. It accepts all transfer syntaxes and stores compressed objects as-is — no transcoding, so nothing is altered on the way in.

Turn it on when

Anything needs to send images here: modalities, another PACS, a workstation. This is the central service.

Leave it off when

This machine only forwards what something else drops in a folder.

Auto-send — Storage SCU and routing rules

Outbound client · C-STORE

What it does

Watches a folder and forwards every new file to whichever destinations apply. A file is only sent once it is stable (size unchanged between two scans), so a half-written file is never forwarded. Progress is tracked per destination: a file counts as done only when every enabled destination has accepted it, and failed hosts are retried on the next scan. On success the original can be kept, moved or deleted.

Rules

With routing enabled, a rule picks destinations by modality, calling AE title, station, patient ID or study description (case-insensitive * and ? globs). Example: CT from ER_* to the teaching archive, de-identified.

The guarantee

A study can never end up going nowhere. Routing off, no rule matched, an unreadable header, a rule naming a destination that no longer exists — every one of those falls back to every enabled destination. Over-sending annoys an operator; under-sending loses an image.

The one exception

A rule that asks to de-identify for a destination, where the scrub cannot actually be performed, holds that destination: it is not sent to at all, rather than sent identified. Two things stop the scrub — the profile is off, or the profile is on and no de-identifier can be built from the settings — and they need different fixes. Nothing is lost either way; see De-identify on forward below.

Turn it on when

This machine has to deliver images onward: to the central PACS, to a reading workstation, or as copies to a teaching archive.

Emergency RIS — HL7 orders

Port 2575 · HL7 ORM^O01 over MLLP

What it does

Receives HL7 orders over MLLP, and also lets you hand-key them into the dashboard when nothing upstream is alive. When the study comes back by C-STORE it is matched to its order by accession number (patient ID as a fallback), and the order is closed and archived for the trail — never erased.

Turn it on when

The RIS is down, or you are testing an integration.

What it guarantees

Image delivery is never gated on an order match. A study with no matching order is still stored and forwarded; the order simply stays open for manual reconciliation.

No TLS, no credential. See the security section: anyone who can open a socket to that port can inject orders. Trusted clinical network and a firewall, or not at all.

Virtual print

Port 11113 · DICOM Print, PDF output

What it does

Presents itself as a DICOM printer and captures whatever is sent to it as PDF. For equipment whose only output is film, this is how you keep something filable.

Turn it on when

You have a print-only modality whose output you want to rescue.

Web dashboard

Port 8042 · HTTP, 127.0.0.1 by default

What it does

Per-service status, destinations, orders, a live activity log, settings and a bundled DICOM editor. Everything the dashboard does also exists in the CLI.

Getting around

The sidebar has six rows: Overview, Services, Studies, Orders, Configuration and Activity — and a seventh, Dev peer, only in a process started with --dev-peer. The three questions asked of the same pile of files are the tabs of Studies — History, Pending and Stuck; what you set when commissioning the machine are the tabs of Configuration — Destinations, Routing, Settings, Modalities and People, and it opens on Destinations, not on Settings; and the three records are the tabs of Activity — Logs, Audit and Caught, the last being what another RIS answered when this appliance asked it as one of your modalities. Orders keeps its own strip of open and closed. The Studies row carries two counts that are buttons in their own right, 📎 pending and ⚠ stuck, and each opens its own tab: so reaching Stuck is one click while something is stuck, and two — the row, then the tab — when nothing is, because a count of zero hides itself. A counter that permanently reads 0 is an alarm that is always on, and nobody looks at those. Orders carries its own count on the same terms. Every panel and tab has its own address — #studies/stuck, #configuration/routing, #activity/logs — so a place in the dashboard can be bookmarked, read out over a phone during an outage, and left with the browser's Back button; older #dlgStuck-style links still resolve. Overview is the one exception: it answers to #overview if you type it, but it is never written to the address bar and leaves no history entry, because it prints a patient's name and an unattended screen must not come back to it after a reload.

The chips in the header

The service chips along the top are unchanged for anyone who may start and stop services. A profile without services.control still sees them, as indicators, but they are disabled: service state is not privileged — the front desk has to be able to see that the receiver is dead — and a switch the server would refuse is not worth offering.

Move it off loopback when

Only with a concrete reason — and then with a token (mandatory) and HTTPS in front. See the token rule.

5. This is not a medical device

Stated plainly, because that is more useful than a footnote:

• If you deploy it, the validation is yours. Regulatory compliance, risk assessment, data protection and clinical responsibility sit with the organisation that puts it into production, not with the project.
• It is distributed with no warranty of any kind, as its AGPL-3.0 licence says.
• It does not replace your PACS or your RIS. It is the gateway between them, and the thing that keeps a department working through an outage until they come back.
• Treat it as clinical infrastructure anyway. Not being a medical device does not make it harmless: it moves patient data. Volume encryption, firewalling, TLS, a token and backups are not optional.
• If a patient's care depends on it, the responsibility for that is yours, not this software's.

None of this is pessimism. The project takes seriously that an image that silently never arrives is worse than a crash — which is why it would rather refuse to start, count failed sub-operations explicitly, and over-send than under-send. It withholds a delivery in exactly one case, loudly and reversibly: a destination a rule asks to de-identify for, while the scrub that was promised cannot be performed — because the profile is off, or because the profile is on and no de-identifier could be built. It says which of the two, because the two are fixed differently. But software can only answer for what it does; the rest is yours.

6. Licence and where to get help

Carino DICOM is released under AGPL-3.0-or-later. Because it is a network server, §13 applies: if you run a modified version as a service, you must offer its source to the people who use it. Keep the LICENSE file and a pointer to the source with any modified deployment.

• Source and issue tracker on GitHub
• Security policy — what is protected, what is not, and how to report a vulnerability
• How to contribute

Found an error in this manual — or a translation a radiologist would never say? Open an issue. The Spanish and Portuguese documentation is part of the project, not an extra.

Carino DICOM · landing page · part of the carino.systems workshop · AGPL-3.0-or-later.