Skip to content
ROLLCALL

Register 1.2.0 part of the Wayne State app stack

Menu

Citadel's registrations export#

This page shows how Rollcall reads the runtime image of each app, and any forced upgrade date, from a file Citadel produces. Next: run the collector in Docker.

Citadel is one source among others. On OpenShift, Coolify or plain Docker, keep using the image list (ROLLCALL_IMAGES_FILE), which any platform can produce. Nothing in Rollcall needs Citadel.

1. Rollcall never calls Citadel#

Rollcall reads a saved file. It holds no Citadel account, opens no connection to Citadel, and sends nothing back. A person or a scheduled job saves the export, and rollcall scan reads it, the same way it reads PROCTOR's reports and the endoflife.date page. If Citadel offers a read-only endpoint that answers with this JSON, save its answer to the file: the shape is the same.

2. The shape#

The export uses Citadel's own field names, so the people who keep Citadel can produce it without a mapping table. The schema is contract/citadel-export.schema.json; extra fields are ignored, so an export may carry more.

{
    "applications": [
        {"repository": "group/project", "base_image": "citadel/php-apache:8.4r5"},
        {"repository": "group/old-project", "base_image": "citadel/php-apache:8.1r2"}
    ],
    "base_image_upgrades": [
        {"old_image": "citadel/php-apache:8.1r2", "new_image": "citadel/php-apache:8.4r5", "due_date": "2026-12-15", "completed": false}
    ]
}
Field What it is in Citadel What Rollcall does with it
applications[].repository The GitLab group/project an application deploys from Joins the app to the repository the scan read
applications[].base_image The base image of the application's active deployment Reads the PHP version (8.4r5 is PHP 8.4)
base_image_upgrades[].old_image The image being retired Every app on that image gets the due date
base_image_upgrades[].due_date The day Citadel forces the upgrade, YYYY-MM-DD The earliest pending date per image counts
base_image_upgrades[].completed Whether that upgrade is done Only false counts; a done upgrade is ignored

Two fields are optional: applications[].php_version (the PHP version in the running container, such as 8.3.14) and applications[].httpd_version (the Apache httpd version, such as 2.4.62). We have asked the Citadel team to send them. When they arrive, Rollcall keeps them in the snapshot and shows them per app in the internal report as "PHP (running)" and "httpd (running)", blank until Citadel sends them; an export without them changes nothing.

Entries Rollcall cannot trust are skipped, never guessed: an application with no repository, an upgrade with no real date ("soon", 2026-02-30) or without "completed": false. An app registered on Citadel but not in the scan is not invented either: the census starts from the repositories.

3. Point Rollcall at it#

macOS and Linux

export ROLLCALL_CITADEL_EXPORT=/path/to/citadel-export.json
php bin/rollcall scan
php bin/rollcall report

Windows

$env:ROLLCALL_CITADEL_EXPORT = "C:\path\to\citadel-export.json"
php bin/rollcall scan
php bin/rollcall report

Set ROLLCALL_CITADEL_EXPORT or ROLLCALL_IMAGES_FILE, not both: each is a complete image source, and the scan stops with a plain message if both are set. In Laravel, the setting is rollcall.citadel_export.

4. What the report gains#

  • Forced image upgrades: the text report prints Forced image upgrades pending: 2 (1 due today or earlier), next due 2026-12-15. and the JSON report carries forced_upgrades with pending, overdue (due today or earlier) and next_due (the next future date, or null). Counts only, so it is public. With the image list, or no image source, all three are zero.
  • Metrics and ADVISOR: the same counts reach /metrics as rollcall_forced_upgrades_pending_apps, rollcall_forced_upgrades_overdue_apps and rollcall_forced_upgrades_next_due_timestamp_seconds (see metrics), and ADVISOR's rollcall_fleet_summary tool answers with forced_upgrades (see ADVISOR).
  • Per app, internally: the internal report's per-app list carries upgrade_due, and the stored snapshot keeps it. Snapshots written before it existed load as null.
  • The dashboard: a "Forced image upgrades" section under the totals with the three counts (the due one in a red badge while any date has come), and on the internal page an "Upgrade due" column with each app's date, badged "date has come" from that day on. The public page never names an app.
  • Owner digests: a new forced upgrade date is news, and so is one that went away. See owner digests.

The export names applications, so keep it where you keep the snapshots: on the host, outside git.