Creating Luet repositories

How to create Luet repositories

After a set of packages has been built, a repository must be created in order to make them accessible by Luet clients. A Repository can be served either local files or via http(s) (at the moment of writing). Luet, by default, supports multiple-repositories with priorities.

Repository fields

name: "..."
description: "..."
type: "docker"
cached: true
enabled: true
arch: "amd64"
priority: 3
  - "..."

Repositories have the following fields, notably:

  • name: Repository name
  • description: Repository description
  • cached: Enable/disable repository cache
  • enable: Enable/disables the repository
  • urls: A List of urls where the repository is hosted from
  • type: Repository type ( docker, disk, http are currently supported )
  • arch: (optional) Denotes the arch repository. If present, it will enable the repository automatically if the corresponding arch is matching with the host running luet. enable: true would override this behavior
  • reference: (optional) A reference to a repository index file to use to retrieve the repository metadata instead of latest. This can be used to point to a different or an older repository index to act as a “wayback machine”. The client will consume the repository state from that snapshot instead of latest.

Create a repository

After issuing a luet build, the built packages are present in the output build directory. The create-repo step is needed to generate a portable tree, which is read by the clients, and a repository.yaml which contains the repository metadata.

Note that the output of create-repo is additive so it integrates with the current build content. The repository is composed by the packages generated by the build command (or pack) and the create-repo generated metadata.


Some of the relevant flags for create-repo are:

  • –descr: Repository description
  • –name: Repository name
  • –output: Metadata output folder (while a different path can be specified, it’s prefered to output the metadata files directly to the package directory).This most of the time matches the packages path for convenience.
  • –packages: Directory where built packages are stored. This most of the time is also the output path.
  • –reset-revision: Reset the repository revision number
  • –tree-path: Specify a custom name for the tree path. (Defaults to tree.tar)
  • –tree-compression: Specify a compression algorithm for the tree. (Available: gzip, Defaults: none)
  • –tree: Path of the tree which was used to generate the packages and holds package metadatas
  • –type: Repository type (http/local). It is just descriptive, the clients will be able to consume the repo in whatsoever way it is served.
  • –urls: List of URIS where the repository is available

See luet create-repo --help for a full description.


Build a package and generate the repository metadata:

$> mkdir package

$> cat <<EOF > package/build.yaml
image: busybox
- echo "foo" > /foo

$> cat <<EOF > package/definition.yaml
name: "foo"
version: "0.1"
category: "bar" # optional!

$> luet build --all --destination $PWD/out/ --tree $PWD/package

📦  Selecting  foo 0.1
📦  Compiling foo version 0.1 .... ☕
🐋  Downloading image luet/cache-foo-bar-0.1-builder
🐋  Downloading image luet/cache-foo-bar-0.1
📦   foo Generating 🐋  definition for builder image from busybox
🐋  Building image luet/cache-foo-bar-0.1-builder
🐋  Building image luet/cache-foo-bar-0.1-builder done
 Sending build context to Docker daemon  4.096kB

$> luet create-repo --name "test" --output $PWD/out --packages $PWD/out --tree $PWD/package
 For repository test creating revision 1 and last update 1580641614...

$> ls out
foo-bar-0.1-builder.image.tar  foo-bar-0.1.image.tar  foo-bar-0.1.metadata.yaml  foo-bar-0.1.package.tar  repository.yaml  tree.tar

Repositories type

There are 3 types of repositories supported by luet: disk, http, docker.


It is a repository which is merely a local folder in your system. When creating a repository and specifying --output, luet expects a local path to the system where to store the generated metadata.


It is a repository type which is hosted behind a webserver. When creating a repository and specifying --output, luet expects a local path to the system where to store the generated metadata, similarly to the disk repository type. Luet is not handling any file upload. The http repository type gains meaning when being used from the client, where the repository source must be specified


When specifying the docker repository type, luet will generate final images from the build results and upload them to the docker reference specified with --output. The images contains the artifact output from the build result, and they are tagged accordingly to their package name. A single image reference needs to be passed, all the packages will be pushed in a single image but with different tags.

The login to the container registry is not handled, the daemon needs to have already proper permissions to push the image to the destination.

Repositories snapshots

Luet automatically will create repository index snapshots. This allows clients to point to specific references of repositories besides the latest package set published.

luet create-repo optionally takes a --snapshot-id argument to define the snapshot name, otherwise it defaults to the unix date timestamp.

Combined with --push-images with a container repository type, it automatically tags and pushes snapshots images too.

Consuming repository snapshots

A client can define a repository, with an optional reference keyword:

name: "..."
description: "..."
type: "docker"
priority: 3
reference: 20220204175357-repository.yaml
  - "..."


  • The tree of definition being used to build the repository, and the package directories must not be symlinks.
  • To build a repository is not required to hold the packages artifacts, only the respective metadata.yaml file is required.

Last modified June 24, 2024: Update goreleaser command (1712988)