This guide walks you through how you can get started with the Depot Registry, a high-performance container image registry that is included with every Depot project. Here we will show how you can use it to push arbitrary images into it, save your image builds to it, and pull your images from anywhere.
depot CLIFor Mac, you can install the CLI with Homebrew:
brew install depot/tap/depotFor Linux, you can install the CLI with our installation script:
# Install the latest version
curl -L https://depot.dev/install-cli.sh | sh
# Install a specific version
curl -L https://depot.dev/install-cli.sh | sh -s 2.96.2For all other platforms, you can download the binary directly from the latest release.
To authenticate to the Depot Registry, you can use the docker login command with your Depot access token of choice if you'd like to docker push and docker pull. The registry supports authenticating with user, project, trust relationships and organization access tokens, as well as pull tokens. See the authentication methods for more details on generating these tokens.
When authenticating to the registry, set the username to x-token and the password to your chosen token:
docker login registry.depot.dev -u x-token -p <depot-token>Note: For depot pull and depot push, the Depot CLI uses your CLI credentials to authenticate to the registry and docker login is not required.
A container registry is enabled on a per-project basis. To create a new project, you can use the Depot CLI:
depot projects create container-registry-testOr you can login to your Depot account and create a new project in your organization.
You can push any image to the Depot Registry using the docker push command. First, tag the image with your project ID and the desired tag (e.g., latest):
docker tag <local-image> registry.depot.dev/<your-project-id>:my-image
docker push registry.depot.dev/<your-project-id>:my-imageIf you are using Depot to build your container images, you can save the build directly to the Depot Registry using the --save flag with the depot build command:
depot build --save --save-tag my-image .The additional --save-tag flag is optional, but it's useful for saving custom tags for your builds. You can use these custom tags in place of a build ID when trying to pull down a specific build.
You can pull an image from the Depot Registry using either the docker pull command or the depot pull command.
docker pullTo make use of docker pull, make sure you have authenticated your local Docker daemon to the registry with docker login as shown above.
Then you can pull the image using the following command:
docker pull registry.depot.dev/<your-project-id>:my-imagedepot pullWhen using the depot pull command, you do not need to authenticate with docker login first, as the CLI uses your existing Depot CLI credentials to authenticate to the registry.
You can specify either a Depot build ID or a custom tag that you saved when pulling the image:
depot pull --project <your-project-id> <build-id>
depot pull --project <your-project-id> my-imageNote: You can omit the <build-id> and <tag> arguments to display an interactive list of builds to choose from.
To pull a build from the Depot Registry in a Kubernetes cluster, you can use the kubectl command to create a secret with the Docker registry credentials, then create a Kubernetes deployment that uses the secret to pull the image.
kubectl create secret depot-registry regcred \
--docker-server=registry.depot.dev \
--docker-username=x-token \
--docker-password=<any project, org, or user access token>You can copy an image that was built with depot build --save from the Depot Registry to another registry using the depot push command to push the saved image build in the registry to another registry of your choosing.
You will need to make sure you have authenticated to the target registry with docker login first.
depot push --project <your-project-id> -t <your-image-registry>:<tag> <build-id>