Your own catalogue
So far guestbook installs from a directory on home01. A repository makes it an
app anyone on the cluster installs by name, from any node. An HTTP repository
is an index.yaml and one .app archive per app, served by any web server.
First give guestbook what a catalogue shows: a home page, its source, an icon,
tags and the features it supports. Replace app.yaml on home01 and add the
icon.
name: guestbookversion: "1.2.0"title: Guestbookdescription: A page, an API under its path and a countercategory: demohomepage: https://example.com/guestbooksource: https://example.com/guestbook.giticon: icon.svgtags: [demo, redis, nginx]features: [api]hidden: falselicense: id: MITvars: greeting@string!: the line the page answers at /greeting maxSigners@int: how many people may sign open@bool: whether signing is open apiPort@port: the port the API listens on dataPath@path: where the counter keeps its data theme@json: colours the page uses owner: email@email: who runs the guestbook homepage@url:endpoint: the owner's page password@secret: the owner's password<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><rect width="16" height="16" rx="3" fill="#2563eb"/><path d="M4 4h8v8H4z" fill="#fff"/></svg>tags are free words for search. features come from a fixed list of what an
application supports, and a word outside it is ignored. hidden: false keeps
the app on the catalogue’s listing. See
App definition.
The repository is a directory served by nginx. Write the app that serves it, then pack guestbook into the directory as its first archive. An archive holds the app directory’s files at its root.
services: shelf: image: nginx:1.27-alpine expose: [80] volumes: - source: ./files path: /usr/share/nginx/html read_only: truename: shelfversion: "1.0.0"title: Shelfdescription: The learn catalogue's web servercategory: demolicense: id: MITapi_version: v2apps: - name: guestbook description: A page, an API under its path and a counter category: demo tags: [demo, redis, nginx] homepage: https://example.com/guestbook versions: - version: "1.2.0" archive: guestbook-1.2.0.app$ tar -czf ~/learn/shelf/files/guestbook-1.2.0.app -C ~/learn/guestbook app.yaml vars.yaml shc.yaml web.env icon.svg site seed.job.yaml$ shc install ~/learn/shelf -s shelf --expose 18090=shelf:80installing deployment "shelf"[shelf] Healthy 1/1✔ shelf healthy✔ installed deployment "shelf"exposure: lan$ curl -s http://localhost:18090/index.yaml...SHC never fetches a repository from loopback or a link-local address, so a
repository’s URL cannot point the daemon at its own vault or at a cloud’s
metadata service. A private-network address is allowed for the operator’s
repositories, which repo add writes when no tenant is named. The URL reads
home01’s underlay_address, the address the other nodes reach it at, with
shc node info itself; on a cluster whose nodes have only private addresses it is
one of those. Every node reaches port 18090 on it, so every node can fetch an
archive.
$ shc node info home01 --fields underlay_address -o yamlunderlay_address: 203.0.113.10$ shc repo add mine "http://$(shc node info home01 --fields underlay_address -o text):18090/index.yaml"...$ shc repo sync mine...$ shc repo ls...The catalogue is what the repositories publish. catalog ls lists it,
catalog search and search find by name, description, category or tag,
and catalog show and show print an app with the command that installs
it. catalog compile prints only those commands.
$ shc catalog ls --kind app...$ shc catalog search redis...$ shc search guest --repo mine...$ shc catalog show mine/guestbook...$ shc show guestbook --repo mine...$ shc catalog compile guestbook --repo mine...--include-hidden lists the items the catalogue keeps off its listing too, and
says why each is hidden. --kind narrows a search to apps, vApps, add-ons or
vApp add-ons, and --repo on catalog show names the repository when two
publish the same app. search filters by --category, --installable keeps
what this cluster can install now, and --verbose prints every field.
$ shc catalog ls --include-hidden...$ shc catalog search guest --kind app --include-hidden...$ shc catalog show guestbook --repo mine...$ shc search guest --category demo --installable --include-hidden --verbose...Install a second guestbook by name. The archive came from the repository, not
from ~/learn/guestbook.
$ shc install mine/guestbook -s signbook --expose signbook.learn.test --var greeting="Sign here."...$ curl -sk --resolve signbook.learn.test:443:127.0.0.1 https://signbook.learn.test/greetingSign here.Publish 1.2.1: change the version in app.yaml, pack it next to 1.2.0 and
point the index at it. A version is never published twice under the same
archive name.
$ sed -i 's/^version: "1.2.0"/version: "1.2.1"/' ~/learn/guestbook/app.yaml$ tar -czf ~/learn/shelf/files/guestbook-1.2.1.app -C ~/learn/guestbook app.yaml vars.yaml shc.yaml web.env icon.svg site seed.job.yamlapi_version: v2apps: - name: guestbook description: A page, an API under its path and a counter category: demo tags: [demo, redis, nginx] homepage: https://example.com/guestbook versions: - version: "1.2.1" archive: guestbook-1.2.1.app - version: "1.2.0" archive: guestbook-1.2.0.appshc update reads shelf’s directory again, so nginx serves the new files.
$ shc update shelf...$ shc repo sync mine...$ shc catalog updates...catalog updates prints the shc update command that takes signbook to
1.2.1. Run it.
$ shc update signbook 1.2.1 --repo mine...$ shc ls...--repo resolves the app from the repository you name, over the one the
deployment was pinned to. With another repository’s app of the same name it
swaps the source and carries the deployment’s values over; --reset-vars
takes the new app’s defaults instead. An app from git is installed with
--ref and --path into the repository, and --token or --auth reach a
private one; update --from points a deployment at another git URL or path.
$ shc update signbook --repo other --reset-vars$ shc install https://git.example.com/acme/guestbook.git -s fromgit --ref v1.2.1 --path app --token P@ssw0rd$ shc install https://downloads.example.com/guestbook-1.2.1.app -s fromarchive --auth reader:P@ssw0rd$ shc update fromgit --from https://git.example.com/acme/guestbook.git --ref v1.3.0 --path app --token P@ssw0rdguestbook itself is not in that list: it was installed from a directory,
and its recorded source stays that path. repoint moves the record onto the
catalogue app without rendering anything, and --back returns it. --diff
reports what the next update would change and writes nothing.
$ shc repoint guestbook guestbook -r mine --diff...$ shc repoint guestbook guestbook -r mine...$ shc catalog updates...$ shc repoint guestbook --back...The next pages keep changing ~/learn/guestbook, so it goes back to its path.
A publisher also pins each archive’s bytes: digest: sha256:<hex> on the
entry, from sha256sum, makes every node check the archive it fetched.
repo update changes how often a repository syncs and its priority against
the others; repo rm removes it, and the apps installed from it keep
running.
$ shc repo update mine --sync-interval 1h --priority 60...$ shc uninstall signbook --no-backup --yes...The apps the catalogue ships carry more of app.yaml than guestbook needs:
what their storefront page shows, where the launcher sends a browser, what a
node must run, and a classic line kept beside a maintained one. Read them on
two apps you validate and never install or publish.
name: storefrontversion: "1.0.0"title: Storefrontdescription: An app read for its catalogue keys and never installedcategory: demokind: appflagship: uptimeicon_source: https://example.com/storefront/logo.svgimageVersions: web: "1.27"launcher: autopath: /host_roles: api: apilanding: - type: hero accent: blue headline: A storefront for the learning cluster subhead: One page the catalogue reads and nobody installs.gallery: - source: none caption: An app nobody installs has no screenshots to show.requires: runtimes: [docker] architectures: [amd64] platforms: [linux]connections: llm: type: llm required: falseprivileges: waivers: - service: web security_opt: - no-new-privileges:true reason: >- The page runs nginx with no new privileges, written here to show where a waiver and its reason go.seed_once: - key: site_url kind: self_origin role: endpoint store: "file:/usr/share/nginx/html/origin.txt" rewrite: none probe_path: /origin.txt probe_service: web note: >- The page copies its own address into a file on first start and never reads the render again.license: id: MITservices: web: image: nginx:1.27-alpine expose: [80] api: image: traefik/whoami:v1.10 expose: [80]name: storefront-classicversion: "0.9.0"title: Storefront classicdescription: The old line of storefront, read and never installedcategory: democlassic_of: storefrontclassic_keeps: []classic_drops: []launcher_placed: falselicense: id: MITservices: web: image: nginx:1.26-alpine expose: [80]$ shc validate ~/learn/storefront...$ shc validate ~/learn/storefront-classic...kindsays what the item is,apphere.icon_sourcerecords where the icon came from andimageVersionsthe upstream version each image is.flagshipnames the one function the catalogue’s owner picked an app as best at. The owner assigns it, so an app you publish leaves it out; storefront carries one only to show where it goes.launcherandpathsay whether the app gets a launcher tile and the page it opens on;host_rolesmarks a service a browser is never sent to, andlauncher_placed: falsetakes the tile away altogether.landingandgalleryare the storefront page: its sections and its screenshots, each screenshot saying where it came from.requiresnames the runtimes, architectures and platforms a node must have;connectionsthe admin-owned credential types the app binds;privileges.waiverseach privilege a service needs and why; it admits nothing, the operator’s grant does.seed_oncedeclares a value the app copied into its own state on first start, so a move rewrites it.classic_ofmarks the old line of an app, pinned to an older image.classic_keepsnames the integrations it still delivers that the maintained line dropped, andclassic_dropsthe variables it lacks.
Keep shelf and the repository mine for the add-on page.