Getting Started with zot Administration¶
This document helps you to deploy an appropriate zot image or to build zot if desired.
After deploying zot, proceed to Configuring zot to choose and configure the features you need.
Installing zot¶
How to get zot¶
The zot project is hosted on GitHub at project-zot. From GitHub, you can download zot executable binary images or full source code.
Supported platforms¶
zot is officially supported on Linux and Apple MacOS platforms, using Intel or ARM processors. However, development should be possible on any platform that supports the golang
toolchain.
OS | ARCH | Platform |
---|---|---|
linux | amd64 | Intel-based Linux servers |
linux | arm64 | ARM-based servers and Raspberry Pi4 |
darwin | amd64 | Intel-based MacOS |
darwin | arm64 | ARM-based MacOS |
freebsd | amd64 | Intel-based FreeBSD* |
freebsd | arm64 | ARM-based FreeBSD* |
* NOTE: While binary images are available for FreeBSD, building container images is not supported at this time.
About binary images¶
Executable binary zot images are available for multiple platforms and architectures and with full or minimal implementations.
Refer to Released Images for zot for information about available zot images along with information about image variations, image locations, and image naming formats.
Deployment methods¶
Several options exist for deploying zot:
-
You can launch a zot binary as a container service using a container management tool such as Podman, Docker, or Helm.
-
You can launch zot as a host-level service by downloading a binary image and running it as a systemd service.
-
You can copy or clone the full zot source code and build an image with custom build flags.
Deploying a zot binary image¶
Executable binary images for supported server platforms and architectures are available from the zot package repository in GitHub.
You can download the appropriate binary image and run it directly on your server, or you can use a container management tool such as Podman, runc, Helm, or Docker to fetch and deploy the image in a container on your server.
For convenience, you can rename the binary image file to simply
zot
.
Example: Deploying with a container manager¶
Using a container manager such as Podman, runc, Helm, or Docker, you can install a zot binary image, as in the following examples.
Using podman
podman run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64:latest
podman run -p 5000:5000 ghcr.io/project-zot/zot-minimal-linux-amd64:latest
Click here to view an example of deploying using podman.
Using docker
docker run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64:latest
Each of these example commands pulls a zot binary image from the GitHub Container Registry (ghcr.io) and launches a zot image registry at http://localhost:5000
.
Click here to view an example of deploying using docker.
Building zot from source¶
Prerequisites¶
Install golang¶
Follow the golang instructions to install the golang
toolchain. After installation, make sure that the path
environment variable or your IDE can find the toolchain.
You must use a golang version of at least the minimum specified in go.mod or the build will fail.
Building an executable binary from source¶
Download or clone the full zot project from GitHub at project-zot. To clone the zot project from GitHub, use this command:
git clone https://github.com/project-zot/zot.git
To build zot, execute the make
command in the zot
directory using the following general syntax:
make OS=os ARCH=architecture {binary | binary-minimal}
The operating system and architecture options are listed in the Supported platforms and architectures table. If an option is not specified, the defaults are
linux
andamd64
.The
binary
option builds the full zot binary image with all extensions.The
binary-minimal
option builds the minimal distribution-spec conformant zot binary image without extensions, reducing the attack surface.
For example, to build a zot image with extensions for an Intel-based linux server, use the following command:
make OS=linux ARCH=amd64 binary
The make
command builds an executable image in the zot/bin
directory. The original filename of the zot executable image will indicate the build options. For example, the filename of an Intel-based linux minimal image is zot-linux-amd64-minimal
.
For convenience, you can rename the binary image file to simply
zot
.
Building a zot container image from source¶
with Stacker
Using the settings in stacker.yaml, you can build a container image that runs the latest zot by running the following command:
make binary-stacker
with Docker
A sample Dockerfile is provided on the zot project page in GitHub. You can edit the sample file with your specific values, such as the desired operating system, hardware architecture, and full or minimal build, as in this example:
ARG OS=linux
ARG ARCH=amd64
RUN make COMMIT=$COMMIT OS=$OS ARCH=$ARCH clean binary-minimal
Using your edited Dockerfile, you can build a container image that runs the latest zot by running the following command:
make image
Deploying the container image¶
Deploy the image using your container manager, such as Podman, runc, Helm, or Docker, as in these examples:
with Podman
podman run --rm -it -p 5000:5000 -v $(pwd)/registry:/var/lib/registry zot:latest
with Docker
docker run --rm -it -p 5000:5000 -v $(pwd)/registry:/var/lib/registry zot:latest
A container image built with the sample Dockerfile and deployed with the example command results in a running registry at http://localhost:5000
. Registry content is stored at .registry
, which is bind mounted to /var/lib/registry
in the container. By default, auth is disabled. As part of the build, a YAML configuration file is created at /etc/zot/config.yml
in the container.
You can override the configuration file with custom configuration settings in the deployment command and in a local configuration file as shown in this example:
podman run --rm -p 8080:8080 \
-v $(pwd)/custom-config.yml:/etc/zot/config.yml \
-v $(pwd)/registry:/tmp/zot \
zot:latest
This command causes the registry to listen on port 8080 and to use /tmp/zot
for content storage.
Additional recommended steps¶
We recommend that, when deploying zot, you also install the command line (zli) and benchmarking (zb) packages.
Launching zot¶
The zot service is initiated with the zot serve
command followed by the name of a configuration file, as in this example:
zot serve config.yml
For convenience, you can rename the binary image file to simply
zot
.The instructions and examples in this guide usezot
as the name of the zot executable file and do not include the path to the executable file.
Next Steps¶
Configuring zot¶
You configure zot primarily through adding and modifying settings in the zot configuration file. The configuration file is a JSON or YAML file that contains all configuration settings for zot functions.
When you first build zot or deploy an image or container from the distribution, a basic configuration file config.json
is created. You can modify the initial file or you can create a new file.
Follow the instructions in Configuring zot, to compose a configuration file with the settings and features you require for your zot registry server.