Included applications

Conductor has two kinds of application entries:

Applications you publish are immutable snapshots of saved Conductor projects. Administrators publish, republish and unpublish them.
Included with Skeleton Works lists applications installed on the customer VM. Their installers own their code, configuration and lifecycle.

A fresh Conductor database has no included applications. Conductor does not seed Social Scheduler or any other product. Administrators see installed applications in Publishing and on the home page; ordinary users see eligible applications in their application catalog.

Installer manifest

Each application ships a small JSON file. For example:

{
  "schemaVersion": 1,
  "id": "example-application",
  "name": "Example Application",
  "description": "A short description for customers.",
  "version": "1.0.0",
  "launchPath": "/example-application",
  "configurationPath": "/example-application?view=settings",
  "audience": "all-users"
}

The ID is a stable lowercase name with optional hyphens. Upgrades reuse it. The version describes the installed application. The optional configuration link is shown only to Conductor administrators. Audience is either all-users or admins.

Paths must be local absolute paths on the customer's Conductor origin. Full external URLs, protocol-relative URLs, traversal, API paths and credentials are rejected. No customer hostname belongs in the manifest. No secrets or social-media credentials belong in this file.

The current format rejects unknown fields and accepts manifests up to 16 KiB. A future format change must explicitly version the contract.

Register after successful installation

The installer first deploys the application and verifies its routes and backend health. Only then should it register its manifest. Use the actual Conductor container name from the successful setup-conductor result:

docker exec -i -w /app CONDUCTOR_CONTAINER \
  node dist/scripts/includedApps.js register < included-app.json

Purpose: record a successfully installed application. Expected result: JSON containing its registered ID and version. Repeating registration updates the existing entry; it does not create duplicates or affect other entries.

The command uses the same persistent SQLite database as Conductor. It runs inside the container, so Node.js is not needed on the VM host. Registration changes catalog metadata only; it does not install code, create a builder project, grant application permissions, or store credentials.

The registration command manages discovery metadata only. In Conductor v1.1.0, new integrations use the application package interface, which installs their browser assets and declared API routes independently of the core image. Legacy metadata-only entries remain supported for compatibility; use the package installer to update a packaged application.

Inspect, remove and recover

docker exec -w /app CONDUCTOR_CONTAINER node dist/scripts/includedApps.js list

Purpose: inspect installed metadata without changing it. Expected result: a JSON array, including administrator-only entries.

docker exec -w /app CONDUCTOR_CONTAINER \
  node dist/scripts/includedApps.js unregister example-application

Purpose: remove the catalog entry when uninstalling that application. Expected result: its ID and whether an entry was removed. Repeating removal is safe. It does not delete application data or uninstall packages.

Application uninstallers must unregister their own ID. Manually deleting containers or code does not automatically update the catalog. Registration is evidence of a successful installation, not a live availability monitor.

The registry is covered by Conductor's normal SQLite backups. Retain matching images, manifests and application data when restoring an installation. Restoring only one side can leave links to missing code.

Browser API and authorization

GET /api/included-apps requires a signed-in, enabled Conductor account. Administrators receive all entries. Ordinary users receive only all-users entries, without configuration links. Responses disable caching.

There is no public registration API or browser install button. Registration is a VM administration action through the container command. Catalog visibility does not replace each application's own backend authorization. An admins audience controls discovery; the application's routes must still enforce administrator access.

Verification

After building the frontend and backend, run:

node scripts/test-management.mjs

This starts an isolated SQLite-backed test server and exercises home navigation, Projects, publishing, empty catalogs, repeated registration, removal, role filtering and error recovery in Chromium. Screenshots are written to test-results/management. Backend integration tests also verify the manifest rules, authenticated API, persistence across restart and stale project edits.

Optional application icon and browser identity (SLICE10)

Conductor v1.1.0 accepts an optional iconPath in schemaVersion 1 manifests. Existing manifests remain valid and receive the Conductor default icon. This is an additive metadata field; incompatible future format changes still require a new schema version.

For example, an installer can add:

"iconPath": "/example-application/assets/icon.svg"

Serve that decorative image on the customer's Conductor origin before registering it. Supported extensions are SVG, PNG, ICO, WebP, JPG and JPEG. Paths must be local absolute paths up to 512 characters using letters, digits, underscores, hyphens, dots and slashes. External/protocol-relative URLs, traversal, API paths, encoded paths, query strings and fragments are rejected. The icon should be readable without a login so the browser can load it consistently. Never put tokens or credentials in its path.

The registration command validates the path; it does not install or copy the image. Missing or unreadable images fall back to Conductor's default. Package the image with the application and give a changed image a new filename to avoid an old browser cache. Re-register the same application ID to update its metadata, then refresh an open application tab.

The shared browser identity mechanism uses the registered name and iconPath for the launch route, its query-string views and descendant routes. The most specific registered route wins; a route such as /example-application does not match /example-application-two. Core home and /apps/... published routes retain their own identity.

Application cards use the same optional icon. Authenticated catalog responses include the icon only for entries visible to that user. The base application contains no Social Scheduler-specific title or icon. The existing Social Scheduler manifest works without modification and inherits the Conductor default.

This remains discovery and identity metadata. Independent installation is provided by the v1.1.0 package interface, implemented in SLICE11.

7.0 KiB Raw Blame History