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.
Consuming
Section titled “Consuming”shc repo add shc https://selfhostedcloud.org/apps/0.1/index.yamlshc repo sync shcshc install shc/plane0.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 format
Section titled “Index format”index.yaml (JSON also parses, since YAML is a superset):
api_version: v2apps: - 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 bytesAn 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.
Publishing
Section titled “Publishing”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.
Archive rules
Section titled “Archive rules”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.