# Container Images

This document is an inventory of the container images published from
this repository.

## Overview

This repo publishes **1 container image** to GitHub Container Registry
(ghcr.io):

- **semiont-frontend** — Vite + React SPA, served as a static container.

The image supports `linux/amd64` and `linux/arm64` and follows the
unified versioning scheme managed through [`version.json`](../../../version.json).

---

## semiont-frontend

[![ghcr](https://img.shields.io/badge/ghcr-latest-blue)](https://github.com/The-AI-Alliance/semiont/pkgs/container/semiont-frontend)

**Description:** Vite + React single-page app (the Semiont Browser),
served from a Node static-file server. Multi-platform: `linux/amd64`,
`linux/arm64`.

**Pull image:**
```bash
docker pull ghcr.io/the-ai-alliance/semiont-frontend:dev
```

**Required environment variables:**
- `SERVER_API_URL` — Backend API URL
- `NEXTAUTH_URL` — Frontend URL for NextAuth callbacks
- `NEXTAUTH_SECRET` — Secret for NextAuth session encryption (min 32 characters)

**Optional environment variables:**
- `NEXT_PUBLIC_SITE_NAME` — Site name displayed in UI (default: `Semiont`)
- `NEXT_PUBLIC_OAUTH_ALLOWED_DOMAINS` — Comma-separated list of allowed OAuth domains

**Documentation:** [apps/frontend/README.md](../../../apps/frontend/README.md)

**Source:** [apps/frontend/](../../../apps/frontend/)

**Dockerfile:** [apps/frontend/Dockerfile](../../../apps/frontend/Dockerfile)

**Workflow:** [.github/workflows/publish-frontend.yml](../../../.github/workflows/publish-frontend.yml)

---

## Backend distribution model

The backend is **not** published as a container image from this repo.
It ships as the `@semiont/backend` npm package via
[`publish-npm-packages.yml`](../../../.github/workflows/publish-npm-packages.yml).
Knowledge-base repositories that need a runtime backend container
build their own from the npm package — see
[`semiont-template-kb/.semiont/containers/Dockerfile.backend`](https://github.com/The-AI-Alliance/semiont-template-kb)
for the canonical example.

This split keeps the upstream repo's container surface minimal (one
image, one workflow) while letting each KB repo pin its own backend
runtime, base image, and configuration.

---

## Versioning

The image follows the unified versioning system managed through
[`version.json`](../../../version.json). Every published image gets one
or more of the following tags:

- **Version tag** — the `version` input to the workflow, e.g. `0.4.22`
  for stable releases or `0.4.22-build.42` for dev builds.
- **Commit tag** — `sha-{COMMIT}`, where `{COMMIT}` is the short SHA
  of the commit that triggered the workflow.
- **Latest tag** — `latest`, applied only when the workflow is run
  with `tag_latest=true`. Operators pinning to `:latest` get whatever
  the most recent stable promotion was.

### Publishing Process

The image is published via the
[`publish-frontend.yml`](../../../.github/workflows/publish-frontend.yml)
workflow, triggered manually with the desired version. Each run:

1. Verifies the matching `@semiont/frontend` npm package version exists.
2. Builds the multi-platform image from `apps/frontend/Dockerfile`.
3. Trivy-scans the amd64 build for `HIGH`/`CRITICAL` CVEs and fails
   the run if any unfixed findings are present.
4. Pushes the image to GHCR with three tags: the version, a
   `sha-{COMMIT}` tag, and (optionally) `latest`.
5. Generates an SPDX SBOM and publishes both build-provenance and
   SBOM attestations as OCI artifacts alongside the image.

### Manual publishing

```bash
gh workflow run publish-frontend.yml --field version=0.4.22
gh workflow run publish-frontend.yml --field version=0.4.22 --field dry_run=true
gh workflow run publish-frontend.yml --field version=0.4.22 --field tag_latest=true
```

---

## Supply-Chain Verification

Each `semiont-frontend` image published to GHCR carries two
cryptographic attestations stored as OCI artifacts alongside the
image:

- **Build provenance** — SLSA-style attestation tying the image
  digest to the GitHub Actions workflow run, commit SHA, and
  workflow inputs. Signed via Sigstore using a short-lived
  certificate issued by Fulcio against the workflow's OIDC token.
- **SBOM** (Software Bill of Materials) — SPDX 2.3 listing of all
  OS packages and language libraries in the image, generated by
  Trivy at build time and signed the same way.

The image itself is also Trivy-scanned for `HIGH`/`CRITICAL`
vulnerabilities before push; an image with unfixed HIGH/CRITICAL
findings will fail the publish workflow rather than reach the
registry.

### Verify the image you pulled

Requires the [GitHub CLI](https://cli.github.com/). No keys to
manage — verification uses Sigstore's transparency log.

```bash
gh attestation verify \
  oci://ghcr.io/the-ai-alliance/semiont-frontend:VERSION \
  --owner The-AI-Alliance
```

A successful verification confirms:

1. The image digest you pulled matches the digest the workflow
   built and pushed.
2. The image was built from `The-AI-Alliance/semiont` at a specific
   commit, by `publish-frontend.yml`, with the inputs recorded in
   the attestation.
3. The signing certificate was issued by Sigstore's Fulcio CA to
   that workflow's OIDC identity.

If verification fails, **do not run the image** — it has been
tampered with, was published outside the official workflow, or the
attestations were stripped.

### Inspecting the SBOM

The SBOM attestation is itself an OCI artifact. To download and
inspect:

```bash
gh attestation download \
  oci://ghcr.io/the-ai-alliance/semiont-frontend:VERSION \
  --owner The-AI-Alliance \
  --predicate-type https://spdx.dev/Document
```

The downloaded JSON lists every package in the image with version,
license, and supplier — useful for vulnerability triage when a CVE
lands and you need to know whether your running image contains the
affected package.

---

## Registry Links

- **Container images:** https://github.com/orgs/The-AI-Alliance/packages?repo_name=semiont
- **GitHub Releases:** https://github.com/The-AI-Alliance/semiont/releases

---

## Support

For issues related to container images:
- **Bug reports:** https://github.com/The-AI-Alliance/semiont/issues
- **Security issues:** See [SECURITY.md](./SECURITY.md)
- **General questions:** https://github.com/The-AI-Alliance/semiont/discussions