# Registry quick start

A **Zaroz Registry** stores your container images next to the place your Workloads run. You push an image with Docker, and a Workload of the same organization pulls it with no extra setup. This page takes you from nothing to a running image. To push from a pipeline instead of your laptop, see [Push from CI](/guides/registry/ci).

## 1. Create the registry

1. In the console, open your project and choose **Registry**.
2. Buy a registry. It is one subscription per registry, and the price is shown before you pay.
3. Open it. A new registry has no storage in use yet and the page offers **Create registry**. Confirm.

The registry page shows its **login host**: the address you give to `docker login`. Images live under your registry's namespace, so a full image name looks like this:

```text
<login host>/<namespace>/<repository>:<tag>
```

The console prints the exact prefix (`<login host>/<namespace>`) on the Repositories tab; copy it from there.

## 2. Create a credential

A registry has no passwords of its own. You create **credentials**, one per person or pipeline, so that revoking one never affects the others.

1. Open the **Access** tab and choose **New credential**.
2. Give it a name such as `laptop` or `ci`, and pick a scope:

| Scope | What it can do |
|---|---|
| Pull only | `docker pull` |
| Pull and push | `docker pull` and `docker push` |
| Pull, push and delete | the above, and delete tags and repositories |

3. Copy the **username** and the **secret**. The secret is shown **once**. Zaroz keeps only a hash and cannot show it again; if you lose it, revoke the credential and create another.

A registry can have up to twenty active credentials. Use the narrowest scope that works: a laptop that only deploys needs pull and push, a server that only runs the image needs pull.

## 3. Log in, push and pull

```bash
# the secret comes from your password manager or an environment variable,
# never from a command-line argument that other users could read with ps
echo "$REGISTRY_SECRET" | docker login <login host> --username <credential username> --password-stdin

docker tag my-app:latest <login host>/<namespace>/my-app:1.0.0
docker push <login host>/<namespace>/my-app:1.0.0

docker pull <login host>/<namespace>/my-app:1.0.0
```

Creating a repository needs no step of its own: the first push to `my-app` creates it. Repository names can have several parts (`web/api`), lowercase letters, digits, `.`, `_` and `-`.

If `docker login` says `Invalid registry credentials`, the secret is wrong or the credential was revoked. A token Docker already holds keeps working for a few minutes after you revoke a credential.

## 4. Tags and clean-up

Open the **Tags** tab and pick a repository. Each tag shows its digest, its size and when the image was built. The registry does not record the moment of the push, so the date is the build time stored in the image.

- **Copy pull command** puts `docker pull <image>` on your clipboard.
- **Delete** removes one tag after a confirmation. Anyone pulling that tag gets an error from then on. The image stays available under any other tag that points at it.

:::note
Deleting a tag does not free space at once. The registry removes layers that no tag uses in a clean-up run (garbage collection), so the stored size falls some time after you delete. The same applies to deleting a whole repository from the Repositories tab.
:::

Old tags still count towards your stored size. A good habit is one immutable tag per build (the commit hash) plus a moving tag such as `latest`, and a periodic clean-up of old build tags.

From the API, the same two operations are `GET` and `DELETE` on `/subscriptions/{id}/registry/repositories/tags` with the `path` of the repository (for example `my-app`) and, for the delete, the `tag`. A repository with very many tags lists only the first ones and says so.

## 5. Use the image in a Workload

In the Workload's source, set the image to `<login host>/<namespace>/my-app:1.0.0` and deploy, as in [Deploy a Workload from a public image](/guides/containers-deploy).

You do **not** add a registry login to the Workload. When the image comes from a Zaroz Registry that belongs to the same organization as the Workload, Zaroz gives the cluster a pull-only credential of its own and keeps it up to date. It does not use up one of your twenty credentials and it never appears in your list.

That only works for your own registry. An image from another organization's registry, or from any other private registry, needs a pull login in the Workload's source as usual.

## Limits and billing

| | |
|---|---|
| Storage cap | 100 GiB by default; you can set it from 1 GiB up to 100 TiB |
| Credentials | up to 20 active per registry |
| Registries | one per subscription |

**Storage** is billed per GB-month, averaged over the month, like object storage. It is measured in **logical bytes**: what you pushed, counted once per layer inside your registry, as if nothing were shared with anyone else. A layer that two of your images share counts once; the same layer in another customer's registry never changes your bill.

**Egress** is billed per GB that leaves the Zaroz network, not per pull. Your own Workloads on Zaroz pulling your images are **free** and are not metered at all. Storage is billed from the start; check the price on the checkout page to see whether the egress line is active for your region.

When stored size passes the cap the registry becomes **read only**: pulls keep working, pushes are refused until you delete tags or raise the cap. If the subscription ends, the registry is scheduled for deletion and its images stay recoverable for seven days.