Container registry quickstart

Registries are accessed via YOUR_SUBDOMAIN.ctr.dev and can be fully up and running almost instantly ⚡️

Creating a Docker container registry

Registries are created automatically on project creation, with no additional steps. 🎉

If you’re a new user, then just sign up (top right of the screen) and click through to create your first project. Sign up takes < 30s

If you already have an account and want to create an additional registry, then just go to the project selection page and click Create project. Every project has exactly one registry.

Pushing your first image

If a registry has no images in it, does it really exist? 🧘🏽‍♀️

To push an image, we need a token that can be used with Docker or similar tools.

The dashboard makes this easy. Under Registry > Push an image you can click to generate a token and copy the commands. We provide pre-canned code for Docker CLI & GitHub Actions.

By default, this will authenticate as the pre-defined push user. This user has access to push anywhere in your registry. You can create new users with more restrictive permissions later.

After you’ve pushed, refresh the page. You’ll see your new image listed along with options for pulling.

Important:
Images pushed to Hiphops MUST follow the format of repo/image e.g. oss/alpine

Pull your image

Pulling again requires a token, and again the dashboard has you covered. If you’ve pushed an image and refreshed you should see a new section: Registry > Pull an image.

Again you can click to generate a token and then copy the commands. For pulling we provide pre-canned code for Docker CLI and Kubernetes.

By default, this will authenticate as the pre-defined pull user. This user has access to pull all images in your registry. You can create new users with more restrictive permissions later.

Test out pulling the image you just pushed by generating a token and pasting the docker commands into a terminal.

… and that’s everything to get going 🥳

Bonus: Creating users with more restrictive permissions

So far, so fantastic. You’ve got a registry, you’ve taken it for a test drive. Your coffee isn’t even cold yet ☕️.

However, in reality you’ll want to give individual users their own access to images. If everyone is using the built-in pull user, then access management can become tricky. This is especially problematic if you ever need to revoke access.

The easiest way is via Registry > Pull an image > New pull user.

This will take you through creating a user (a.k.a identity) and granting the proper permissions.

First we name the user and (optionally) add a description.
Next we select the repos (sub-folders) and images the user should have access to. This step creates a pull role under the hood.

Make sure the role name is unique - we’ll generate one for you based on the access it grants, but you can edit this if needed.

If you want to re-use roles, you can select your permissions and then click to view existing roles that grant at least that level of access

Finally, confirm the details and the selected role will be applied to the new user.

You can now choose this user from the auth drop down, then click Add token. This will update the copyable commands to use your new user instead.

Next steps

You can get quite far with registry just by clicking through the dashboard. As your needs become more sophisticated we also have the Access page to better manage users and roles.

Additionally, the Hiphops API can be used to do everything we just did above and more. It uses the same access system as registry.