archy/app-catalog

Archipelago App Catalog

Dynamic app catalog for the Archipelago marketplace. Nodes fetch this catalog to discover available apps.

How it works

1. The Archipelago frontend fetches catalog.json from this repo
2. Apps listed here appear in every node's app store automatically
3. When a user installs an app, the backend pulls the Docker image and creates the container

Adding a new app

Add an entry to catalog.json:

{
  "id": "my-app",
  "title": "My App",
  "version": "1.0.0",
  "description": "What it does",
  "icon": "/assets/img/app-icons/my-app.svg",
  "author": "Author",
  "category": "data",
  "dockerImage": "source.archipelago-foundation.org/lfg2025/my-app:1.0.0",
  "repoUrl": "https://github.com/...",
  "containerConfig": {
    "ports": ["8080:8080"],
    "volumes": ["/var/lib/archipelago/my-app:/data"],
    "env": ["NODE_ENV=production"]
  }
}

For apps with hardcoded backend configs (Bitcoin, LND, etc.), containerConfig is optional. For new apps, include containerConfig so the backend knows how to create the container.

Storefront layout

Discovery merchandising is app-registry data, not node-OS layout. The optional top-level storefront block defines the ordered Popular Apps rows and the promotional banners placed before the remaining All Apps grid:

{
  "storefront": {
    "popular": ["bitcoin-knots", "lnd", "btcpay-server"],
    "promotions": [{
      "id": "my-app",
      "banner": "/assets/img/featured/my-app.webp",
      "eyebrow": "open source",
      "headline": "Build together.",
      "description": "Catalog-controlled promotional copy.",
      "tag": "NOSTR // SOURCE",
      "path": "/npub1maintainer/project",
      "launchLabel": "Open",
      "installLabel": "Install",
      "detailsLabel": "Learn more →"
    }]
  }
}

Only IDs present in apps render. An optional promotion path deep-links into the installed app; Archipelago uses this to open the canonical signed Nostr repository rather than GitWorkshop's generic dashboard. New dashboards prefer storefront from the daemon-verified signed catalog and use the bundled community copy as a local fallback. scripts/generate-app-catalog.sh carries this block into the signed release artifact; changing it does not require a node OS release once that artifact is published.

Categories

money, commerce, data, home, nostr, networking, community, development, l484

App screenshots

catalog.json owns each app's ordered screenshots: [{ "src": "https://…", "alt": "…" }]. The release generator embeds this list into manifest.app.metadata.screenshots (including manifest variants), so the verified /api/app-catalog response supplies screenshots independently of dashboard builds. The UI reads that manifest field.

Optimized images live under app-catalog/screenshots/<app-id>/, with a SHA-256 suffix in each filename. URLs point to the registry's raw-file server; retain old files when adding replacements so older signed catalogues remain usable. Publish the assets before generating, signing and publishing a catalogue that references them. These changes prepare that publication; they do not publish it.

The local UX mock reads this canonical directory and serves images through /api/app-catalog/screenshots/…, rewriting only these registry URLs in its mock catalogue response. Images are not bundled into the frontend or hotlinked from upstream project websites. neode-ui/public/catalog.json remains the generated community presentation fallback, not the authority for screenshot selection.

screenshot-sources.json records originals, source URLs, hashes, and review notes. Only reviewed full desktop screenshots in the app's native dark theme are included. Use official public demo data or isolated sample libraries; never private accounts, node addresses, credentials, wallets, or user files. Wait for content and animations to settle. Reject light screens, cropped panels and promotional composites.

Originals, source provenance and the per-app gaps report are in /home/yaya/Pictures/archy-app-store-dark-desktop-2026-11-10/. The previous collection is withdrawn and must not be published. Missing shots are recorded as gaps rather than filled with unsuitable images. Official reference screens can depict older app versions; their source versions remain documented.