Aperture

A management portal for InterSystems IRIS, with no separate application server.

See who loses what before you save, follow every background job, read every log and find the entries worded like any of them with IRIS Vector Search.

Online demo · For judges · Why Aperture · Run it · Architecture · Bonuses · Verification

Aperture is an entry for the InterSystems Programming Contest: Build Your Own Management Portal.
It is a set of static files that IRIS serves itself. Your browser calls IRIS’s own
SysAdmin REST API (/api/admin,
273 operations) directly, signed in as you, so IRIS checks your privileges on every call and audits
you by name. The one thing that API cannot give you, the instance’s log files, comes through a small
read-only reader the IPM package adds, written in Embedded Python, with a wording index on IRIS Vector
Search beside it.

For judges: two minutes

1. In your browser, nothing to install. Open the online demo
   and press Try the demo: a simulated IRIS 2026.2 runs inside the page, so change whatever you like.
   • Press Ctrl+K (⌘K), type databases, open USER and choose
     Actions → Integrity check: the 202 Accepted lands in the Job Center with console output and progress.
   • Open Security → Users → jdoe, remove a role and press Save: the review lists old → new and
     who loses which privilege.
   • Open Logs → Messages log (the reader asks for the password, SYS), open an entry and choose
     Similar entries: IRIS Vector Search lists the entries worded like it, with how often and when.
   • Open Health check: sixteen read-only checks run with your own access, and every finding says
     what it means, what to do, shows its evidence and opens the screen that fixes it.
   • Open REST services and export an application’s routes as a Postman collection or a .http file.
   • Sign out and sign in as operator / SYS: the security area disappears, and every disabled
     action names the resource it needs.
2. On real IRIS, one command. docker run -d --name aperture -p 127.0.0.1:52773:52773 ghcr.io/mxsalata/aperture,
   then http://localhost:52773/aperture/index.html as _SYSTEM / SYS (more).
3. On your own IRIS 2026.2. zpm "install iris-aperture", then /aperture/index.html on the
   instance’s web server (more).

The demo is Aperture itself, built with a mock of the whole API that runs in the browser (Mock
Service Worker), seeded to look like a busy instance with interoperability productions, tasks,
journals, users and audit history. Writes change that in-memory instance; the same mock drives the
unit and browser tests. Every real deployment also has a Try the demo button on its sign-in page.

Why Aperture

• You sign in as yourself. No service account in the middle: POST /login gives you your own
  short-lived JWT, IRIS enforces your privileges on every call and writes your name into its audit
  log. The portal reads what you may do (GET /info) and shows exactly that.
• All 273 operations. Hand-made screens for the daily work, and the API Explorer renders every
  operation from the OpenAPI document, so nothing in the API is out of reach.
• Who loses what, before you save. Every edit is reviewed old → new against a fresh read of the
  object. A user or role change lists every account it reaches with the privileges gained and lost,
  and a change that would leave nobody able to administer security is refused.
• A health check that shows its work. Sixteen deterministic, read-only checks (disks, databases,
  journal, backups, auditing, open services and applications, %All holders, certificates, tasks,
  the licence, severe log entries) run with your own access. Each finding says what it means and what
  to do, shows the fields it read and where, and opens the Aperture screen that fixes it; a check your
  account may not read is listed as not checked, with the privilege it needs. No invented score.
• Every background job in one place. 202 Accepted answers become jobs by themselves; the Job
  Center follows them with console output, progress, pause, resume and cancel.
• Every log, and the entries worded like it. messages.log, alerts.log, SystemMonitor.log and
  every rotation (Ideas Portal DPI-I-966), read in bounded windows. Similar entries finds the
  entries worded like any of them with IRIS Vector Search: an HNSW index over hashed words, built in
  Embedded Python inside IRIS, with nothing sent anywhere else.
• Requests you do not have to type. Any REST application’s routes, and any SysAdmin operation,
  export as a Postman collection, a .http file or curl (Ideas Portal DPI-I-813).
• Disk space you can act on. The databases screen shows how much of each disk behind the database
  files is free, as a share and as a size, and says when one is running low.
• Tested on real IRIS. 139 operations verified on IRIS for Health 2026.2; CI builds IRIS Community
  2026.2 with the package on every push and checks the API contract against it; 274 unit tests and 135
  browser tests, among them an accessibility audit of every screen in five appearance modes.
• Made for long sessions. Light, Dark and Pastel themes and high contrast, a command palette, a
  navigation menu you arrange yourself, charts you choose, a colour per connection so production
  never looks like staging, and browser tabs you can make read-only.

More screenshots

The six contest areas

Run it on real IRIS

Docker

The published image, IRIS Community 2026.2 with Aperture installed through its IPM package:

docker run -d --name aperture -p 127.0.0.1:52773:52773 ghcr.io/mxsalata/aperture

Then open http://localhost:52773/aperture/index.html (the built-in web server needs the file name, a
bare /aperture/ answers 404) and sign in as _SYSTEM (or SuperUser) with SYS. That is the
image’s demonstration password; -e IRIS_PASSWORD=... makes another one the password of every
enabled account (but CSPSystem, the image’s own Web Gateway account) at every start. With Docker
Compose, https://github.com/MxSalata/aperture/blob/main/docker-compose.yml runs the same image and takes IRIS_PASSWORD
from a .env next to it (https://github.com/MxSalata/aperture/blob/main/.env.example): docker compose up -d. CI publishes the
image only after checking it against the SysAdmin API, both with a password set at start and with
the demonstration one: latest and the version from main, edge from the development branch.

From the sources, with nginx serving the portal in front of IRIS:

git clone https://github.com/MxSalata/aperture.git
cd aperture
docker compose -f https://github.com/MxSalata/aperture/blob/main/docker-compose.build.yml up --build

• http://localhost:8080 - Aperture behind nginx (proxies /api/admin, /api/monitor, /api/mgmnt and /api/aperture to IRIS: same origin, so no CORS and no Basic-auth pop-ups; sends a Content-Security-Policy). A second instance goes behind the same nginx under a path prefix (/iris-b, the pattern is documented in https://github.com/MxSalata/aperture/blob/main/docker/nginx/default.conf.template) and gets a connection profile with that prefix as its base URL
• http://localhost:52773/aperture/index.html - Aperture served by IRIS itself (the committed www/ build, refreshed with npm run build:www)
• Sign in as _SYSTEM with IRIS_PASSWORD from .env, or with SYS when none is set.
• On a host with more than 20 CPU cores, IRIS Community stops at start-up with Invalid Community Edition license, may have exceeded core limit (reported by the IRIS Atrium entry). Restrict the container’s CPUs with a docker-compose.override.yml next to the compose file: services: { iris: { cpuset: "0-19" } }.
• The ports are published on 127.0.0.1 only by default. To use it from other machines, set IRIS_PASSWORD, put TLS in front (nginx and IRIS’s web server speak plain HTTP), then start with APERTURE_BIND=0.0.0.0.

The iris service is built from https://github.com/MxSalata/aperture/blob/main/docker/iris/Dockerfile on top of
intersystems/iris-community:2026.2, pinned by digest (sha256:cd2ebcab…50bdaa, Build 221U).
IRIS for Health Community 2026.2 is tested too, against a real instance
(evidence): put
IRIS_IMAGE=containers.intersystems.com/intersystems/irishealth-community:2026.2@sha256:7c06b6b3d950bc25f3e353b0a65db0c4045f251fb9103eade63514302b662cf3
in a .env file next to the compose file. The portal image pins node:22-alpine and
nginx:1.30-alpine by digest, and CI pins every GitHub Action to a commit. At build time
https://github.com/MxSalata/aperture/blob/main/docker/iris/init.script fetches the InterSystems Package Manager from the
community registry (installer 0.10.9, checked against its SHA-256) and installs Aperture through its own IPM package (zpm "load" of https://github.com/MxSalata/aperture/blob/main/module.xml): the built portal is copied into the instance’s manager
directory (mgr/aperture/), the /aperture web application is created, the /api/aperture log reader
(Aperture.API over Aperture.Logs, Embedded Python)
is created, and Aperture.Installer, also Embedded Python, enables
/api/admin with password + JWT authentication. The build log ends with the installer’s readiness
report; you can print it again at any time:

docker exec aperture iris session IRIS -U USER "##class(Aperture.Installer).Doctor()"   # aperture-iris when built from the sources

IPM

zpm "install iris-aperture"

copies the pre-built portal (www/) into the instance’s manager directory (mgr/aperture/, which
durable %SYS keeps across container updates), creates the /aperture
web application and the /api/aperture log reader (a read-only %CSP.REST class over an Embedded
Python file reader, needs %Admin_Operate:USE) with its wording index (Aperture.LogLine, a
%Library.Vector column under an HNSW index, the package’s only tables), and runs Aperture.Installer,
an Embedded Python class that enables /api/admin with password and JWT authentication and prints a
readiness report (IRIS version, JWT availability, the API’s authentication settings, the portal’s
files, the log reader and the log files it can read). Then open
http://<host>:52773/aperture/index.html. From a checkout, zpm "load /path/to/aperture"
installs the same package; ##class(Aperture.Installer).Doctor() prints the report again.

Requirements on the IRIS side

• IRIS or IRIS for Health 2026.2+ with the /api/admin web application. Aperture speaks SysAdmin API v2, which ships with 2026.2; IRIS 2026.1 serves only v1 (every /v2 path answers 404) and older releases have no SysAdmin API, so sign-in there stops with an explanation. Sign-in uses JWT and falls back to HTTP Basic when /login is unavailable (for example with JWT authentication switched off on /api/admin).
• The account needs at least one %Admin_* privilege (GET /info refuses everyone else).
• Logs → Messages log reads the log files through the package’s own /api/aperture web application (created by zpm "install", zpm "load" and the Docker image; password authentication, %Admin_Operate:USE). On an instance without the package that screen says so and everything else works.
• The portal must be served from the same origin as the API it talks to: /api/admin/v2 sends no CORS headers, by design (InterSystems, in the contest announcement thread, 22 September 2026), so a browser cannot call it across origins whatever the web application’s allow-list says. The three supported topologies are all same-origin: nginx in front of IRIS (compose), the /aperture web application served by IRIS itself (IPM), and the Vite dev server’s proxy. Further instances go behind the same nginx under a path prefix.

Development

npm install
cp https://github.com/MxSalata/aperture/blob/main/.env.example .env           # VITE_IRIS_URL=http://localhost:52773
npm run dev                    # http://localhost:5173, /api/admin proxied to IRIS

Other scripts:

Architecture

The portal and the APIs share an origin (the SysAdmin API sends no CORS headers, by design), so the
same build is served by IRIS itself, behind nginx, or by the Vite dev server’s proxy; the demo swaps
the network for the in-browser mock. More in https://github.com/MxSalata/aperture/blob/main/docs/ARCHITECTURE.md.

Contest technology bonuses

Ideas Portal ideas Aperture implements

Two ideas with the “Community Opportunity” status on the InterSystems Ideas Portal are implemented here; each is one screen away in the demo.

Verified against real IRIS

• On IRIS for Health 2026.2 (Build 221U), https://github.com/MxSalata/aperture/blob/main/docs/COVERAGE.md accounts for every
  one of the 273 operations: 139 verified on that instance (every read that had an object to read,
  and each write with its evidence, undone after its check), 139 called by a hand-made screen, 173
  answered by the online demo. Every screen was walked as an administrator and as an operator, from
  a browser in another time zone (evidence).
• On IRIS Community 2026.2, in CI, on every push: the verify-iris job builds the image
  (Aperture installed by zpm "load" of its https://github.com/MxSalata/aperture/blob/main/module.xml, the Embedded Python installer), starts it
  and runs https://github.com/MxSalata/aperture/blob/main/scripts/live-check.mjs: JWT sign-in and refresh, /info, list
  shapes, the error envelope, a full 202 round trip, the portal served at /aperture/index.html, the
  log reader and a similar-entries query on the wording index. It checks the image with a password
  set at start and with the demonstration one before publishing it.
• Everywhere else: npm run verify:live runs the same check against your instance
  (https://github.com/MxSalata/aperture/blob/main/docs/VERIFICATION.md); the answers of real instances are also the second
  oracle of the mock’s contract test.

What it does not do yet

• Mirroring, ECP, LDAP, MFT, encryption, external language servers and file-system access are
  reachable through the API Explorer rather than hand-made screens.
• SQL, globals and classes are outside the SysAdmin API, and outside Aperture; ^ERRORS and SQL
  diagnostics stay in the classic Management Portal.
• Interoperability productions show as charts of messages and queues, not as a production editor.
• Similar entries match wording, not meaning: two messages that describe one fault in different
  words are not paired.
• The log reader and the wording index need the IPM package (or the Docker image); without them the
  Messages log says so and everything else works.

Documentation

Tech stack

React 19 · TypeScript 5.9 · Vite 7 · Mantine 8 (+ charts, spotlight, notifications, modals) · TanStack Query 5 · TanStack Table 8 · React Router 7 · zustand · openapi-typescript / openapi-fetch · Mock Service Worker 2 · Vitest 4 · Playwright · nginx · IPM · ObjectScript (%CSP.REST, %Persistent) · Embedded Python (installer, log reader, wording index) · IRIS Vector Search (%Library.Vector, %SQL.Index.HNSW, VECTOR_COSINE)

License

MIT, see https://github.com/MxSalata/aperture/blob/main/LICENSE.