Skip to content
SHC Docs

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.

~/learn/guestbook/app.yaml
name: guestbook
version: "1.2.0"
title: Guestbook
description: A page, an API under its path and a counter
category: demo
homepage: https://example.com/guestbook
source: https://example.com/guestbook.git
icon: icon.svg
tags: [demo, redis, nginx]
features: [api]
hidden: false
license:
id: MIT
vars:
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
~/learn/guestbook/icon.svg
<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.

~/learn/shelf/shc.yaml
services:
shelf:
image: nginx:1.27-alpine
expose: [80]
volumes:
- source: ./files
path: /usr/share/nginx/html
read_only: true
~/learn/shelf/app.yaml
name: shelf
version: "1.0.0"
title: Shelf
description: The learn catalogue's web server
category: demo
license:
id: MIT
~/learn/shelf/files/index.yaml
api_version: v2
apps:
- 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
home01
$ 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:80
installing deployment "shelf"
[shelf] Healthy 1/1
✔ shelf healthy
✔ installed deployment "shelf"
exposure: lan
home01
$ 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.

home01
$ shc node info home01 --fields underlay_address -o yaml
underlay_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.

home01
$ 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.

home01
$ 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.

home01
$ shc install mine/guestbook -s signbook --expose signbook.learn.test --var greeting="Sign here."
...
home01
$ curl -sk --resolve signbook.learn.test:443:127.0.0.1 https://signbook.learn.test/greeting
Sign 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.

home01
$ 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.yaml
~/learn/shelf/files/index.yaml
api_version: v2
apps:
- 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.app

shc update reads shelf’s directory again, so nginx serves the new files.

home01
$ 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.

home01
$ 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.

explained, not walked: the learning cluster has one repository and no git host
$ 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@ssw0rd

guestbook 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.

home01
$ 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.

home01
$ 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.

~/learn/storefront/app.yaml
name: storefront
version: "1.0.0"
title: Storefront
description: An app read for its catalogue keys and never installed
category: demo
kind: app
flagship: uptime
icon_source: https://example.com/storefront/logo.svg
imageVersions:
web: "1.27"
launcher: auto
path: /
host_roles:
api: api
landing:
- 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: false
privileges:
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: MIT
~/learn/storefront/shc.yaml
services:
web:
image: nginx:1.27-alpine
expose: [80]
api:
image: traefik/whoami:v1.10
expose: [80]
~/learn/storefront-classic/app.yaml
name: storefront-classic
version: "0.9.0"
title: Storefront classic
description: The old line of storefront, read and never installed
category: demo
classic_of: storefront
classic_keeps: []
classic_drops: []
launcher_placed: false
license:
id: MIT
~/learn/storefront-classic/shc.yaml
services:
web:
image: nginx:1.26-alpine
expose: [80]
home01
$ shc validate ~/learn/storefront
...
$ shc validate ~/learn/storefront-classic
...
  • kind says what the item is, app here. icon_source records where the icon came from and imageVersions the upstream version each image is.
  • flagship names 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.
  • launcher and path say whether the app gets a launcher tile and the page it opens on; host_roles marks a service a browser is never sent to, and launcher_placed: false takes the tile away altogether.
  • landing and gallery are the storefront page: its sections and its screenshots, each screenshot saying where it came from.
  • requires names the runtimes, architectures and platforms a node must have; connections the admin-owned credential types the app binds; privileges.waivers each privilege a service needs and why; it admits nothing, the operator’s grant does.
  • seed_once declares a value the app copied into its own state on first start, so a move rewrites it.
  • classic_of marks the old line of an app, pinned to an older image. classic_keeps names the integrations it still delivers that the maintained line dropped, and classic_drops the variables it lacks.

Keep shelf and the repository mine for the add-on page.

Next: Stop, start, protect and rename.