Skip to content
SHC Docs

HTTP app repositories

Layer 11. Lifecycle. Lifecycle

An http(s) repo is an index manifest plus one .app archive (tar.gz of the app directory) per app, the SHC equivalent of a helm chart repository. Any host that serves bytes over http works: S3, nginx, a static site, or GitLab’s generic registry. The shc repo’s own CI publishes the full apps/ catalog on every default-branch push and release tag (apps/index job): the archives and the index both land in that registry, which is anonymously readable.

Terminal window
shc repo add shc https://selfhostedcloud.org/apps/0.1/index.yaml
shc repo sync shc
shc install shc/plane

0.0.0-latest is a moving channel: the path is fixed and the content advances with each publish. Archive URLs inside the index are absolute and content-addressed, so a stale index can only ever resolve to bytes that still verify, or to a 404, never to different bytes than the digest it was published with.

Private hosts work too: shc repo add … --token <t> sends Authorization: Bearer <t> on both the index fetch and every archive download (terraform: the shc_repo resource’s token attribute).

Sync parses the index and replaces the repo’s catalog rows; each row’s source is the resolved archive URL with the digest pinned as a #sha256=<hex> fragment. On install, the daemon downloads the archive node-locally, verifies the digest (mismatch fails closed with X500902REPMAT), and extracts it into the repo’s cache dir, so unlike git+file:// repos, http repos install from any node.

index.yaml (JSON also parses, since YAML is a superset):

api_version: v2
apps:
- name: plane
description: Project management
category: productivity
tags: [projects]
versions:
- version: "1.0.0"
archive: plane-1.0.0.app # relative to the index URL, or absolute
digest: sha256:<hex> # over the archive bytes

An index whose api_version isn’t v2, an app missing name or versions, and a version missing version or archive fail the sync loudly. homepage / icon carry through to the catalog like the git crawl does. parent_app and vapp are retired and refused.

shc catalog build --apps <tree> --out <dir> --archive-base <url> writes one archive per subdirectory (app.yaml required), byte-reproducible archives (sorted walk, zeroed times, fixed ownership), so digests only change when app content changes. It lays each one out at <dir>/<name>/<version>/<name>-<sha12>.app and writes <dir>/index.yaml naming them under <url>; --prior <index> carries forward the versions the index you served last names (the shc catalog’s own publisher, scripts/publish-apps-site.sh, does exactly that). Serve the archives and the index anywhere; register the index.yaml URL.

Versions are immutable. Consumers pin digests at sync time; never republish different bytes under the same archive name; bump the app’s version instead (the archive name embeds it).

built_from_commit, and why an index needs provenance

Section titled “built_from_commit, and why an index needs provenance”

shc catalog build --commit <sha> stamps an optional top-level built_from_commit on the document. It is ignored by every consumer (ParseHTTPIndex decodes with a plain yaml.Unmarshal and no KnownFields) and exists for the PUBLISHER.

The index is a whole-document replacement of one URL, so concurrent publishing pipelines race for it and the last writer wins regardless of which source revision it was built from. On 2026-08-16 an apps/index job for an ancestor commit finished 74 seconds after one for a descendant and put the previous revision of an app back into the catalogue. Nothing in the schema could see it: the app version had gone UP over the channel’s life while the content went BACKWARD, so the flat head, channels.stable and published_at all read as an ordinary publish.

Ancestry is the predicate the version numbers cannot express. Before replacing the index, .gitlab-ci.yml’s apps/index job fetches the SERVED copy, reads this field, and refuses unless the commit already published is an ancestor of the one publishing (equal counts: a retried job). Anything else (a descendant, a diverged commit, a commit the checkout cannot resolve) refuses and leaves the catalogue alone; SHC_APPS_INDEX_ALLOW_REWIND='<reason>' forces a deliberate rollback through. A publisher of your own that replaces an index in place wants the same guard: verify by CONTENT and provenance, never by version.

An archive is the app dir’s contents at the tar root (app.yaml, compose.yaml, …). Extraction rejects path traversal, absolute names, and link entries.