Fediversity Panel

Feature Specification: Instances Overview

Created: 2026-09-23

Status: Implemented

Input: Reconstructed from the code at 0bf4ecd36 (panel/src/panel/views.py (InstanceList), deployment_value.py, templates/instance_list.html, templates/partials/_api_unreachable.html, static/logo_fallback.js), api/specification.md (sections "What a configuration serves" and "The component catalog"), pull requests #1548, #1892 and #1900, and the design notes of the maintainers.

User Scenarios & Testing (mandatory)

User Story 1 - See all my running services (Priority: P1)

/instances/ shows the instances of each deployment of the operator. The application instances and the supporting components come from api (instances and deployed_instances). A card links to the address of an instance that is deployed, and shows the logo that api serves.

Why this priority: the operator thinks in services, not in configurations.

Independent Test: run panel-python-tests (test_instance_list.py).

Acceptance Scenarios:

  1. Given a deployed deployment, When the operator opens the overview, Then the page shows one card for each instance that api gives, with a link to its address.
  2. Given a deployment that is not deployed, When the operator opens the overview, Then the cards have no link.
  3. Given a deployment without instances, When the operator opens the overview, Then the page gives a hint and a link to the form.

User Story 2 - See which instances have changes to deploy (Priority: P2)

A card has a "changed" tag when the section that configures the instance differs between the draft and the deployed configuration. api gives the section of each instance (section) and the sections that changed (POST /configuration/sections). The cog on a card opens the form of that section.

Independent Test: run panel-python-tests (test_instance_list.py).

Acceptance Scenarios:

  1. Given a draft that changes one section, When the operator opens the overview, Then only the card of that section has the tag.
  2. Given a deployment that was never deployed, When the operator opens the overview, Then no card has the tag.
  3. Given an instance with a section, When the operator clicks its cog, Then the form of that section opens.
  4. Given an instance without a section, When the operator opens the overview, Then its card has no cog.

Edge Cases

  • api does not answer for one deployment: only the group of that deployment shows a warning.
  • A logo is missing: the card shows a fallback image.

Requirements (mandatory)

Functional Requirements

  • FR-001: The panel MUST take the instances, their names, their state and their addresses from the typed fields of api.
  • FR-002: The panel MUST call api once for each deployment, and MUST limit a failure to the group of that deployment.
  • FR-003: The panel MUST link only to instances that are deployed.

Key Entities

  • Instance: an application or a supporting component of a deployment, as api reports it.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The overview shows the correct instances without reading the configuration.

Assumptions

  • api derives the instances, their sections and the domain from the configuration.