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 everyday jobs and what to do when they fail, 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-DICOM
mkdir -p data
echo "PACS_UID=$(id -u)" >> .env
echo "PACS_GID=$(id -g)" >> .env
docker compose up -d --build
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-DICOM
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 before moving a single image: press Echo on the destination's row. On a machine with no dashboard, ./run.sh echo --name "Hospital PACS" does the same. If the 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 Point the modality at line on the receiver's card, and send a test study (see How do I…).
5. Watch the activity log, on the Logs tab of Activity. If something fails it shows up there, and on the service's card as Last problem; 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. How do I…

Short recipes for the jobs that come up on the floor. Each one ends with how you know it worked; if it did not, the next chapter is the list of what to check.

…point a modality at it to store images

1. Open Services. If the Receiver card says it is stopped, press Start.
2. Read the card's line Point the modality at: an AE title, an IP address and a port (by default CARINODICOM and 11112). The copy button beside it copies all three. If the machine has more than one address, use the one on the modality's network.
3. On the modality, add a storage destination — vendors call it a DICOM node, an archive, a "Send to" or a "Store" target — with those three values. The modality's own AE title is the calling AE; you do not have to enter it here.
4. If Configuration → Settings → This PACS lists AE titles under Accept only these AEs, add the modality's AE title there, or the receiver refuses it.
5. Run the modality's own connection test (often Verify or Echo), then send one study. It appears in Studies → History.

The card's Test button checks the receiver from this machine itself. If Test passes and the modality still fails, the problem is between the two: address, port, firewall or the AE allow-list.

…point a modality at it to print

For equipment whose only output is film. Carino pretends to be the film printer and captures each sheet for you to identify; nothing is printed on paper.

1. Open Services and press Start on the Print receiver card.
2. Read its line Point the modality at (by default CARINOPRINT, this machine's IP and port 11113).
3. On the modality, add a DICOM printer — sometimes called a laser imager or film printer — with those three values. Grayscale is always offered; if the modality only prints in colour, tick Also accept color print jobs under Configuration → Settings → Printing.
4. Press Send a test print on the card. A sheet marked TEST PRINT — safe to discard appears in Studies → Pending within a few seconds. That proves the receiver works; discard the sheet.
5. Print one film from the modality. The card shows Last print with the number of films, the modality's AE title and its address, the Captured counter goes up, and the film waits in Pending for you to approve (see below).

Store each captured film as (under Printing) decides what the film becomes when you approve it. Many archives and viewers store a PDF but do not display it; choose Image (Secondary Capture) if the film has to be read on the other side.

The printer AE title typed on the modality is not checked: a mistyped one still prints. Only the modality's own AE title is filtered, and only if you fill in Accept only these AEs. If a print fails, the card shows Last problem; the print troubleshooting table lists every message and its fix.

…point a modality at it to pull its worklist

1. Make sure there are orders. Either the RIS sends HL7 orders to the Emergency RIS service (port 2575), or someone types them in Orders → New order.
2. Under Configuration → Modalities, register the room with its exact station AE title. An order's target is then picked from that list instead of typed.
3. Open Services, press Start on the Worklist card and read its line Point the modality at (by default CARINOMWL and port 11114).
4. On the modality, set the worklist provider (MWL, "HIS/RIS" or "worklist server") to those values and query it.

An order with no target appears on every station; an order with a target appears only on the station whose AE title matches it exactly. When the study comes back it is matched to its order by accession number and the order closes itself.

…approve a pending film

Captured films, and PDFs or images found beside a study, wait in Studies → Pending. The 📎 count next to Studies says how many.

1. Open Preview and look at the sheet.
2. If the patient has an open order, press Match to order… and pick it. Name, patient ID, accession and study come from the order, and the order is closed as captured.
3. Otherwise type the identity yourself. Patient ID and Patient name are required; accession, date and description are strongly recommended.
4. If the item arrived beside a study and you changed the patient, choose what it belongs to: Attach to the original study only if that study really is this patient's, otherwise New study. A wrong choice files one patient's sheet inside another patient's study.
5. Press Approve & send. It is converted to DICOM and forwarded like any other study.

There is no undo: once approved, the original file is gone from Pending and the DICOM copy is on its way. A mistake is fixed on the archive. Discard removes an item without sending it.

…fix a stuck forward

Open Studies → Stuck (the ⚠ count next to Studies). Rows are grouped by study, with the patient, accession and description, and sorted into three kinds:

• Retrying automatically — a destination refused or did not answer. Read the error on the row: it says whether the remote rejected us (and why, for example "add CARINOSCU to the remote's allowed AE titles"), dropped the connection, or never answered. Fix that, press Echo on the destination's row under Configuration → Destinations, then Retry now.
• Held — nothing is being sent — a de-identification hold. No timer releases it; use the two buttons on the row, and see De-identify on forward.
• No destination left to retry — the files are routed to a destination that was removed or turned off. Turn it back on, or press Send to… and pick another destination, or Remove from queue (it asks first) to accept the loss.

…find out why something failed

1. Look at the service's card. Every listener shows Last problem when something went wrong; click it to open the log already filtered to that service.
2. On Activity → Logs, use the service chips (store, send, print, worklist, Q/R, RIS…), Errors and warnings only, and the text filter — an AE title, an IP address or an accession number narrows it fast.
3. To hand the problem to someone else, copy the visible lines, or download a whole day's log.
4. Press Test on the card. If the test passes from this machine but the modality still fails, look at the network between them.
5. If a setting changed and nobody knows who changed it, Activity → Audit names the person and the sections they changed.

4. When something goes wrong

Symptom first, then where to look, then the fix. Almost every row starts in the same two places: the service's card on Services (its Last problem) and Activity → Logs.

Sending, receiving and the worklist

Printing

Every refusal and failure of the print receiver is a line in the log (the print chip), counts in the card's Errors, and shows as its Last problem. A successful job shows as Last print.

Two things that are not the cause: the printer AE title typed on the modality (it is not checked), and the modality leaving the film session and film box numbers to the printer (they are created here when missing). A Presentation LUT is accepted and ignored, and a modality that first asks for the printer's configuration gets an answer.

5. 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.

6. 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.

Each service has one switch. Start on its card starts it and keeps it on after a restart; Stop asks first, then stops it and keeps it off. In Configuration → Settings the same switch is the box Run this service (also at startup), so the card and the setting can never disagree. Saving settings restarts only the services whose own settings changed, and the dashboard says which.

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.

Registered modalities

No port · Configuration → Modalities

What it does

The list of rooms this appliance serves — a name a person recognises, the station AE title the worklist matches exactly, the modality code, and an optional station name. It is not a permission list: a scanner does not have to be registered here to send images, and being here does not let it. What it buys is that an order's target becomes a pick from a list rather than a field somebody types, and it is the list the worklist probe below borrows an AE title from.

Fill it in when

You are serving the worklist or hand-keying orders. Until one station is registered, an order's target is typed by hand and a typo cannot be caught.

Worklist probe — asking the other RIS

Outbound client · worklist C-FIND · Configuration → Modalities

What it does

Answers “why is this scanner not seeing its list?” without touching the scanner. Give the hospital's real RIS or its broker an address under Settings, then press Test worklist on a modality's row: Carino asks that RIS the question that modality would ask, using that modality's own AE title, and files every answer under Activity → Worklist probes. One run asks the same question five times, widened a key at a time — station and date and modality, then without the modality, without the date, without the station — because the difference between the answers is what locates the fault. Nothing comes back to any of them and the other RIS has nothing scheduled; only the narrowest comes back empty and it is the station AE title that is wrong.

Before you press it

Take the modality off the network first. The probe calls as that modality, and two things answering to one AE title on one RIS is a confusion somebody then has to go and undo.

What it is not

Not a service, not a schedule and not a queue. What Worklist probes holds is a record of what somebody else answered: those orders are never served on this appliance's own worklist, and it claims none of them. Clear empties that record and does nothing else.

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 or Secondary Capture output

What it does

Presents itself as a DICOM printer (AE title CARINOPRINT by default) and captures every film sheet sent to it. For equipment whose only output is film, this is how you keep something filable. A film carries no reliable patient identity, so each one waits in Pending for a person to identify it; nothing printed is forwarded on its own.

Turn it on when

You have a print-only modality whose output you want to rescue. The steps are under How do I… print.

Settings

Under Configuration → Settings → Printing: the AE title and port, Accept only these AEs (the modalities allowed to print; empty means any), Also accept color print jobs, and Store each captured film as PDF or Image. Pick Image when the receiving PACS or viewer does not display PDFs — many do not.

How you know it works

Send a test print on the card runs a whole print through the receiver and drops a sheet marked "TEST PRINT — safe to discard" into Pending. After a real job the card shows Last print (how many films, from which AE and address) and the Captured counter. A refusal or failure shows as Last problem; see the print troubleshooting table.

What it tolerates

Modalities that leave the film session and film box numbers to the printer, a Presentation LUT (accepted and ignored), and a printer AE title typed differently on the modality — the called AE is not checked.

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 records are the tabs of Activity — Logs, Connections, Audit and Worklist probes. Connections lists recent DICOM connections both ways and says why one failed and what to change, on which machine; the What it accepts button on a destination row asks that node about every kind of image stored here. Worklist probes is 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.

7. 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.

8. 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, Portuguese, Japanese and Russian manuals are part of the project, not an extra.

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