Skip to content
Start free
Documentation menu

Container images

Quayline implements the OCI Distribution Specification 1.1 and the OCI Image Specification 1.1. Any client that talks to a conforming registry works without plugins.

Naming

Image names are fi4.enotcloud.com/<organisation>/<repository>[:tag|@digest]. Repository names may contain lowercase letters, digits, hyphens, dots and up to three slash-separated path segments, for example tidewater/payments/ledger. Repositories are created on first push with the default visibility of your organisation, which is private.

Login

login
# interactive, stores a credential helper entry
$ qln docker-login

# non-interactive, from CI
$ echo "$QLN_TOKEN" | docker login fi4.enotcloud.com -u tidewater --password-stdin
$ echo "$QLN_TOKEN" | podman login fi4.enotcloud.com -u tidewater --password-stdin

Multi-architecture builds

Push a manifest list built by buildx. Each platform is stored as its own image manifest and shares layers with the others where the content matches.

buildx
$ docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --tag fi4.enotcloud.com/tidewater/api:1.9.1 \
    --tag fi4.enotcloud.com/tidewater/api:latest \
    --push .
#14 pushing manifest for fi4.enotcloud.com/tidewater/api:1.9.1@sha256:7c41d0e9a5b2...e09
#14 DONE 1.2s

Layers compressed with zstd are accepted and stored as-is. Clients that do not support zstd are served a gzip rendition, created on first request and cached for 30 days.

Signing and referrers

Signatures, SBOMs and attestations are stored as referrers of the image they describe. The referrers API makes them discoverable without tag conventions.

terminal
$ cosign sign --key cosign.key fi4.enotcloud.com/tidewater/api@sha256:7c41d0e9a5b2...e09
$ syft fi4.enotcloud.com/tidewater/api:1.9.1 -o spdx-json > sbom.json
$ cosign attach sbom --sbom sbom.json fi4.enotcloud.com/tidewater/api@sha256:7c41d0e9a5b2...e09

$ qln referrers fi4.enotcloud.com/tidewater/api:1.9.1
TYPE                          DIGEST          SIZE
application/vnd.dev.cosign    sha256:b02e19   1.1 kB
application/spdx+json         sha256:46fd7a   284 kB
Deleting an image also deletes its referrers. Retention rules treat them as part of the subject, so a retained image never loses its signature.

Pull-through mirrors

A mirror caches images from an upstream registry (use --preset for well-known public registries or --upstream-url for your own) the first time they are pulled, which avoids upstream rate limits and keeps builds working when the upstream is slow or down.

terminal
$ qln mirror create dockerhub --preset docker-hub --org tidewater
mirror ready: fi4.enotcloud.com/tidewater/_mirror/dockerhub

$ docker pull fi4.enotcloud.com/tidewater/_mirror/dockerhub/library/alpine:3.20
3.20: Pulling from tidewater/_mirror/dockerhub/library/alpine
Status: Downloaded newer image (cached from upstream, 3.4 MB)

Mirrors revalidate tags against the upstream every 6 hours and never serve a digest they have not verified. Upstream credentials are stored encrypted and are scoped to the mirror.

Common errors

ResponseCauseFix
401 unauthorizedMissing or expired tokenRun qln docker-login again, or check the token expiry with qln token inspect.
403 denied: scopeToken lacks push for this pathCreate a token with --scope "push:tidewater/api".
403 denied: policySignature or vulnerability policy blocked the pullRead the reason line; sign the image or fix the finding.
404 name unknownOrganisation slug or repository path is wrongList repositories with qln repos ls.
413 blob too largeA single layer exceeds your plan's object limitSplit the layer, or see limits.
429 egress allowanceStarter pool exhaustedWait for the reset date in the body, or upgrade.