IRIS Atrium

A browser-based administration console for InterSystems IRIS. IRIS Atrium is a
single, demo-ready Angular single-page app that inspects and operates an IRIS
instance through the platform’s native management APIs (security, tasks,
processes, web applications, OS and logs) — no SQL, no direct global access
from the browser, and no dependency on the vendor’s own Management Portal UI.

The console is organized into six sections:

1. Web Apps & REST API Explorer — list web applications; explore and test the
   OpenAPI spec of any REST-enabled app installed on the instance.
2. Permissions — list IRIS users, roles and resources; edit user role
   assignments and enable/disable users.
3. Security & Secrets — dashboard of SSL configurations, X.509 credentials,
   wallets and OAuth clients (read-only).
4. Tasks — view scheduled tasks and history; run, suspend and resume tasks.
5. Operating System — CPU/memory/disk dashboard, namespaces and the IRIS
   process list with terminate support.
6. Logs — unified viewer over console, messages, audit and task history with
   filters and CSV export.

Stack

• Backend: InterSystems IRIS Community Edition (mp ISOS package,
  %CSP.REST dispatch class mp.disp).
• Frontend: Angular 17 single-page app built with Node (web/).
• Tooling: Docker + Compose, ZPM module iris-atrium, GitHub Actions CI,
  %UnitTest.Manager suites under tests/UnitTest.

How the application works

Overall architecture

Browser (Angular SPA)
   │  HTTPS/HTTP, Basic auth on every request
   ▼
/webapps, /permissions, /security, /tasks, /system, /logs
   │
   ▼
CSP web application "/csp/iris-atrium"           (static SPA shell)
CSP REST web application "/api/mp"               (mp.disp %CSP.REST router)
   │
   ▼
mp.disp  →  mp.impl.{webapps, permissions, security, tasks, system, logs}
   │
   ▼
IRIS native management APIs (what actually powers the console):
   Security.Users / Security.Roles / Security.Resources / Security.Applications
   Security.SSLConfigs / Security.X509Credentials / Security.Wallets / SSL
   %SYS.Task + TaskHistory / %SYS.ProcessQuery / Config.Namespaces
   %SYSTEM.OBJ (file system) / ^$SYSTEM files (messages.log, console.log)
   %SYS.Configuration, HSM, etc.

The browser never talks to IRIS globals or SQL. Every panel is served by
/api/mp, a thin %CSP.REST facade (dispatch class mp.disp) that delegates to
one implementation class per domain. Each implementation maps the request onto
the corresponding InterSystems IRIS management API — the same classes the
native Management Portal uses — and returns a small JSON envelope to the SPA.

Request flow (concrete example)

1. The Angular service builds a URL under /api/mp, e.g. GET /api/mp/tasks.
2. mp.disp (the %CSP.REST router) matches the path, checks that the caller
   holds the required privilege (e.g. %Admin_Task), and invokes
   mp.impl.tasks.List().
3. The implementation queries the IRIS management APIs
   (##class(%SYS.Task).%ExistsId(), ##class(%SYS.Task).%OpenId(),
   ##class(%SYS.Task).RunNow(), %SYS.TaskHistory) and shapes the rows.
4. The result is serialized to JSON (mp.util.json) and returned with the
   proper status code.
5. The Angular component renders the table / chart / form from the JSON.

Authentication & session

• Login (POST /api/mp/login) validates the credentials against IRIS and the
  entire session is driven by each request carrying
  Authorization: Basic <base64(user:password)>.
• The SPA stores that header in localStorage (keys mp.credentials,
  mp.username) and an Angular HTTP interceptor re-attaches it to every call.
• No cookie or JWT is used; authorization is re-evaluated by IRIS on every
  request, so revoking a user or dropping a role takes effect immediately.
• Privilege enforcement happens server-side: each /api/mp route carries a
  minimum privilege (%Admin_Manage, %Admin_Secure, %Admin_Task,
  %Admin_Operate) and returns 403 for callers who lack it.

Request body encoding

The 2026.1 community CSP gateway strips double quotes from POST/PUT bodies,
corrupting application/json payloads. The API therefore transports JSON as
base64 in a body64 query parameter (/api/mp/...?body64=<encoded>) with an
empty HTTP body. The SPA handles this transparently in api.service.ts.

The six sections, powered by which IRIS management API

SysAdmin API client

src/mp/impl/admin.cls is the only outbound HTTP client in the package. It
targets the InterSystems SysAdmin API as published in
mainspec_v2.json
(base path /api/admin), speaks GET/POST/PUT/DELETE, and unwraps the
BaseResponse envelope — failures are read from status.Errors / status.summary
and surfaced as a %Status with the API’s own message.

Calls are made against 127.0.0.1 on the request’s own port, replaying the
caller’s HTTP Basic credentials, so a SysAdmin call is only permitted when the
caller already holds the matching %Admin_* privilege. Set MP_ADMIN_API to
point at a different base path.

The one exception is the OpenAPI spec proxy behind /api/mp/webapps/spec:
the SysAdmin API exposes no endpoint for a REST application’s OpenAPI
document, so that proxy still reads the native spec path through
mp.impl.admin.Raw().

Version requirement

The console requires InterSystems IRIS 2026.2 or newer. The SysAdmin API
reports its version at /api/admin (apiVersion), and every SysAdmin route the
console uses lives under /v2. On IRIS 2026.1 the same base path answers with
apiVersion: 1 and all /v2/* paths return 404, so the Web Apps, namespaces
and processes panels have nothing to talk to. tests/UnitTest/Admin/Integration.cls
asserts apiVersion >= 2 and fails loudly rather than passing on empty results.

Request shape

Two details of the API are not what the published spec suggests, and both are
covered by the integration tests:

• Type is not accepted in a PUT /v2/web-app body. The application type is
  derived from DispatchClass; sending the field is rejected with #40307.
• ServeFiles is validated against the numeric value list of
  Security.Applications (,0,1,2,3), not against the enum names the spec
  documents. Writing "Always" is rejected with #7205; write 1/0. Reading
  the field back still yields the name, where the disabled value is spelled
  "No".

ServeFiles is therefore translated in both directions by
mp.impl.webapps.ServingMode() (write) and mp.impl.webapps.Serving() (read).

Requirements

Only Docker is required (Docker Desktop or Docker Engine + Compose). All other
tooling runs inside the container. Port 52773 must be free.

The base image is pinned to intersystemsdc/iris-community:2026.2, the first
community release that serves the SysAdmin v2 API. An older IRIS_IMAGE builds,
but the Web Apps, namespaces and processes panels will not work against it.

IRIS Community Edition license & high-core hosts

The InterSystems IRIS Community Edition license limits the runtime to a maximum number
of visible CPU cores (up to 20 for current community releases). On hosts that expose
more cores than the license allows, IRIS aborts at startup with “Invalid Community
Edition license, may have exceeded core limit”. Because this image boots IRIS during
docker compose build too, the build can hit the same failure.

This stack ships a self-contained fix — no license key, no Docker VM changes:

• The base image is pinned to the vendor-maintained intersystemsdc/iris-community
latest stream (valid, non-expired community license; overridable via the
  IRIS_IMAGE build argument, e.g. docker compose build --build-arg IRIS_IMAGE=...).
• scripts/iris-entrypoint.sh heads off /iris-main at build and runtime, wrapping
  the process in a taskset CPU-affinity mask via scripts/limit-cores.sh so IRIS never
  observes more than MP_MAX_CORES cores (default 19, i.e. under the 20-core ceiling).
• On hosts already at or below MP_MAX_CORES cores the wrapper is a no-op, so low-core
  machines behave exactly as before.

To override the visible-core bound (must stay below the license ceiling for the fix to
hold):

MP_MAX_CORES=4 docker compose up -d

Quickstart

docker compose up -d --build

• IRIS becomes healthy: docker compose ps shows the iris service healthy.
• IRIS Atrium: http://localhost:52773/csp/iris-atrium/index.html
• Demo login: SuperUser / SYS

Base image notes: the latest community stream runs a full CSP subsystem, so
class-dispatch web apps (including /api/mp) work over HTTP exactly as on a
licensed instance. The intersystemsdc/iris-community:latest-em-zpm stream boots
with a limited CSP subsystem: static pages serve normally, but no web
application that dispatches to a class (DispatchClass) accepts requests — every
such endpoint answers 401/403/404 regardless of credentials. When that image
is selected via IRIS_IMAGE, the portal’s HTTP API cannot be demonstrated over
HTTP; the %UnitTest.Manager suites still run in the terminal inside the image.

Demo walkthrough (six sections)

1. Web Apps & REST API Explorer — open Web Apps; verify the list shows
   /csp/... applications with name, path, namespace and authentication. Open
   API Explorer, pick an installed REST app (e.g. /api/mp), confirm the
   OpenAPI spec renders and fire a sample GET returning HTTP 200.
2. Permissions — open Permissions, pick a user, edit a role assignment and
   confirm it persists.
3. Security & Secrets — open Security; verify the SSL/x509/wallet/OAuth
   dashboard renders (entries may be few on a fresh instance).
4. Tasks — open Tasks; click Run Now on a harmless task (e.g.
   Purge Audit) and confirm a new Finished history entry.
5. Operating System — open OS Management; confirm the CPU/memory/disk
   dashboard loads within 5 seconds; the process list loads from the SysAdmin
   /v2/processes endpoint. Terminating a process requires %Admin_Operate
   and a confirmation dialog.
6. Logs — open Logs; apply a source=Console filter, then Export the
   filtered entries as a CSV download.

REST API

All endpoints live under /api/mp and require HTTP Basic
credentials (Authorization: Basic <base64(user:password)>). The SPA obtains those
credentials from its login screen and sends them on every request.

Response envelope: 200 {...} on success; errors are { "error": "...", "message": "..." } with HTTP 4xx/5xx.

Note on request bodies. The 2026.1 community CSP gateway strips double quotes
from POST/PUT bodies, corrupting application/json payloads. The API therefore
transports JSON as base64 in a body64 query parameter (/api/mp/login?body64=<...>)
with an empty body; the SPA adds this automatically in api.service.ts.

Automated tests

ObjectScript unit tests run inside the container (mirrors CI):

docker compose exec -T iris bash -lc 'iris session IRIS -U %SYS < /opt/mgmt/dev/scripts/run-tests.script'

scripts/run-tests.script runs the whole UnitTest tree. Most suites are pure
shape tests, but UnitTest.Admin.Integration issues real HTTP requests against
the live SysAdmin API — it creates, reads, edits and deletes a
/csp/mp-selftest web application and asserts apiVersion >= 2. It needs an IRIS
identity with %Admin_Secure, supplied through:

docker compose exec -T -e MP_SELFTEST_USER=SuperUser -e MP_SELFTEST_PASSWORD=SYS \
  iris bash -lc 'iris session IRIS -U %SYS < /opt/mgmt/dev/scripts/run-tests.script'

Without those variables the live tests report a single skip and the rest of the
tree still runs. This split is deliberate: the shape tests stay fast and hermetic,
while the integration suite is what catches a wrong base path, a missing verb, a
dropped Content-Type or a payload the API rejects — none of which the shape
tests can see.

Angular unit tests run locally in web/:

cd web && npm ci && npm test -- --watch=false --browsers=ChromeHeadless

Local Angular development

cd web
npm ci
npm run build    # outputs to web/dist (not required for the Docker path)

The container bakes the SPA at build time; a local build is only needed to iterate.

Project layout

src/mp/                  ObjectScript backend (package mp)
  disp.cls               %CSP.REST router
  Installer.cls          USER-namespace + web-app bootstrap
  impl/                  Endpoint implementations (six areas + session)
  util/                  json + security helpers
web/                     Angular SPA
tests/UnitTest/          %UnitTest.Manager suites (per portal section)
docker-compose.yml       IRIS service, port 52773
Dockerfile               node build stage + IRIS community stage
scripts/                 Core-cap wrapper (limit-cores.sh) + entrypoint override
iris.script              Container bootstrap
module.xml               ZPM module metadata

Troubleshooting

License

MIT — see https://github.com/guilhermendes1/iris-atrium/blob/main/LICENSE.