Kheeper

Pushing and Pulling Images

Kheeper is an OCI-compatible container registry. You can push and pull images using kheeper push and standard container tools like Podman.

Image references

Images in Kheeper follow the standard OCI naming convention:

kheeper.com/<org>/<repo>:<tag>

For example: kheeper.com/myorg/webapp:v1

Pushing images

With kheeper push

The kheeper push command handles authentication and uploads the image from your local container storage:

# Build the image with the registry prefix
podman build -t kheeper.com/myorg/webapp:v1 .

# Push to the registry
kheeper push myorg/webapp:v1

kheeper push streams layers to the registry and skips layers that already exist, making repeat pushes fast.

With Podman

You can also push directly with Podman if the credential helper is configured (this happens by default during kheeper auth login):

podman push kheeper.com/myorg/webapp:v1

Note that podman does not chunk large blob uploads. Use kheeper push if you encounter any errors.

Pushing configurable images

To push a configurable image, add the kheeper.configurable=1 annotation at build time:

podman build --annotation kheeper.configurable=1 -t kheeper.com/myorg/webapp:v1 .
kheeper push myorg/webapp:v1

The registry detects this annotation and extracts the templates and schema from the image so they can be used when creating releases.

Pulling images

Pull images with Podman or any OCI-compatible tool:

podman pull kheeper.com/myorg/webapp:v1

This requires read access to the repository. Org owners have read access to all repos in their org. Other users need to be granted access via kheeper authorizations create.

Inspecting images

Use kheeper images get to view metadata about a pushed image:

kheeper images get myorg/webapp:v1

If the image is configurable, the output includes a ConfigImage field showing the associated template image.

Image format

Kheeper requires OCI image manifests. Docker v2 schema manifests are not supported. When building with Podman, images are OCI format by default. If you're migrating from Docker, make sure to build with --format oci.

Repository permissions

Each repository belongs to an org. The permission model:

  • Org owners can read and write all repos in their org
  • Readers can pull images from a specific repo
  • Writers can push images to a specific repo

Grant access with:

kheeper authorizations create myorg/webapp --email user@example.com --permission reader

Public repositories

Images in the public org (e.g. kheeper.com/public/autoregister) are readable by any authenticated user.

Next: Configuring Images