th registry: Container Registry | ThailandHosting CLI

About

Every Project has a default registry, where Container and Function builds land: <host>/<project>/<image>. Create more for staging and production, or for images you ship to others; their images are <host>/<project>/<registry>/<image>. th names a repository by its path in the Project: api in the default registry, prod/api in the registry prod, followed by :TAG or @DIGEST (the first 7 hex characters of a digest are enough).

Access tokens sign docker, CI or a server elsewhere into one registry, read-only (pull) or read-write (push and pull), with an optional expiry. On your own computer, th auth configure-docker signs docker into every registry of your Projects.
Public registries let anyone pull without signing in; the Project pays the transfer like any download.
Immutable tags: a tag, once pushed, never moves to another image (latest excepted), so v1.2.3 always means the same image.
Cleanup policy: keep the newest N images of each repository, remove untagged images after N days (default 7), remove images nobody pulled for N days, and always keep tags that match patterns such as v*. It runs by itself every 10 minutes. Images a Container runs or keeps for rolling back are never removed.

Storage is billed per Project, each layer once however many registries hold it, so copying an image into another registry adds nothing to the bill. All registries of a Project share its registry quota.

How-to guides

Promote an image from staging to production

Shell

th registry create staging
th registry create prod --immutable-tags --keep-tags "v*"
th container deploy api-staging --source . --repository staging/api --tag v1.4.0
th registry images copy staging/api:v1.4.0 prod/api
th container deploy api --image registry.thailandhosting.com/<project>/prod/api:v1.4.0

The build lands in the staging registry and runs as api-staging. Once it is tested, the copy puts the same image, by the same digest, in prod, and api deploys it from there. With immutable tags, v1.4.0 in prod can never be pushed over.

Push from CI with an access token

Create a write token for the registry: th registry tokens create prod --name github-actions --permission write. The token is printed once; save it as a secret in your CI.
In CI, sign docker in with it as user th, then push.
Revoke it when it is no longer needed: th registry tokens revoke prod github-actions.

Shell

echo "$TH_REGISTRY_TOKEN" | docker login registry.thailandhosting.com -u th --password-stdin
docker push registry.thailandhosting.com/<project>/prod/api:v1.4.0

Keep storage down with a cleanup policy

Shell

th registry cleanup default --preview --keep-latest 10 --unpulled-days 30
th registry update default --keep-latest 10 --unpulled-days 30 --keep-tags "v*,prod"
th registry cleanup default --run

--preview with policy parameters shows what that policy would remove, without saving it. --run applies the saved policy now instead of waiting for the next pass.

Commands

Command	Description
`th registry list`	Lists the Project's registries and how much of the registry storage quota (shared by all of them) they use.
`th registry create`	Creates a registry in the Project.
`th registry describe`	Shows a registry's settings and cleanup policy, and its repositories.
`th registry update`	Changes a registry's settings; settings left out stay as they are.
`th registry images list`	Lists a repository's images, newest first.
`th registry images tag`	Points TAG at an image of the same repository, e.g.
`th registry images copy`	Copies an image into another repository or registry of the Project, e.g.
`th registry images delete`	IMAGE is REPOSITORY:TAG (removes only the tag), REPOSITORY@sha256:DIGEST or REPOSITORY@<first 7+ hex of the digest> (removes the image and all its tags), or the full <host>/<project>/REPOSITORY[:TAG\|@DIGEST].
`th registry tokens create`	Creates an access token that signs docker, CI or a server elsewhere into this registry alone: read pulls, write pushes and pulls.
`th registry tokens list`	Lists a registry's access tokens.
`th registry tokens revoke`	Revokes an access token, by ID or name (see th registry tokens list); it stops working at once.
`th registry cleanup`	Every registry's cleanup policy runs by itself every 10 minutes.
`th registry delete`	Deletes a registry with all its repositories, images and access tokens.

`th registry list`

Lists the Project's registries and how much of the registry storage quota (shared by all of them) they use.

Syntax

Shell

th registry list

"default" is where builds land.

Examples

The Project’s registries and storage used

Shell

th registry list

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry create`

Creates a registry in the Project.

Syntax

Shell

th registry create REGISTRY [--description TEXT] [--public]
    [--immutable-tags] [--keep-latest N] [--untagged-days N]
    [--unpulled-days N] [--keep-tags PATTERNS]

Names are 1-40 lowercase letters, digits and -, starting and ending with a letter or digit ("default" is taken). Its images are <host>/<project>/REGISTRY/<image>: push with docker after th auth configure-docker, or build into it with th container deploy --repository REGISTRY/<image>.

Images a Container runs, or keeps for rolling back, are never removed by cleanup. Removing images frees storage once no other image uses their layers.

Examples

A production registry whose tags never move

Shell

th registry create prod --immutable-tags --keep-tags "v*"

Anyone can pull from it

Shell

th registry create public-images --public --description "Images we ship"

Keep 10 images per repository; drop what nobody pulls

Shell

th registry create staging --keep-latest 10 --unpulled-days 30

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.

Parameters

Name	Type	Description
`--description`	string	What the registry is for (up to 200 characters)
`--public`	flag	Let anyone pull without signing in (`--no-public`: sign-in or a token)
`--immutable-tags`	flag	A pushed tag never moves to another image, except latest
`--keep-latest`	number	Keep the newest N images of each repository (0 = no limit)
`--untagged-days`	number	Remove untagged images after N days (1-365, default 7)
`--unpulled-days`	number	Remove images nobody pulled for N days (7-730, 0 = off)
`--keep-tags`	list	Tag patterns always kept, comma-separated, e.g. v*,prod ("none" clears)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry describe`

Shows a registry's settings and cleanup policy, and its repositories.

Syntax

Shell

th registry describe REGISTRY

Examples

Settings, cleanup policy and repositories

Shell

th registry describe prod

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry update`

Changes a registry's settings; settings left out stay as they are.

Syntax

Shell

th registry update REGISTRY [--description TEXT] [--public|--no-public]
    [--immutable-tags|--no-immutable-tags] [--keep-latest N]
    [--untagged-days N] [--unpulled-days N] [--keep-tags PATTERNS|none]

To see what a new cleanup policy would remove before saving it: th registry cleanup REGISTRY --preview with the same flags.

Images a Container runs, or keeps for rolling back, are never removed by cleanup. Removing images frees storage once no other image uses their layers.

Examples

Lock tags

Shell

th registry update prod --immutable-tags

Change the default registry’s cleanup policy

Shell

th registry update default --keep-latest 20 --keep-tags "v*,prod"

Private again, no tag patterns kept

Shell

th registry update staging --no-public --keep-tags none

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.

Parameters

Name	Type	Description
`--description`	string	What the registry is for (up to 200 characters)
`--public`	flag	Let anyone pull without signing in (`--no-public`: sign-in or a token)
`--immutable-tags`	flag	A pushed tag never moves to another image, except latest
`--keep-latest`	number	Keep the newest N images of each repository (0 = no limit)
`--untagged-days`	number	Remove untagged images after N days (1-365, default 7)
`--unpulled-days`	number	Remove images nobody pulled for N days (7-730, 0 = off)
`--keep-tags`	list	Tag patterns always kept, comma-separated, e.g. v*,prod ("none" clears)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry images list`

Lists a repository's images, newest first.

Syntax

Shell

th registry images list REPOSITORY

REPOSITORY is IMAGE for the default registry (where builds land) or REGISTRY/IMAGE for another one, e.g. api or prod/api. USED BY names the Containers running an image; KEPT=yes means a Container runs it or a revision keeps it for rolling back, so cleanup leaves it. To list a registry's repositories: th registry describe REGISTRY.

Examples

Images of api in the default registry

Shell

th registry images list api

Images of api in the registry prod

Shell

th registry images list prod/api

Positional arguments

Name	Description
`REPOSITORY`Required	`IMAGE` in the default registry or `REGISTRY/IMAGE` in another, e.g. `api` or `prod/api`.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry images tag`

Points TAG at an image of the same repository, e.g.

Syntax

Shell

th registry images tag IMAGE TAG

to promote a build to prod or name it v1.4.0. IMAGE is REPOSITORY:TAG or REPOSITORY@DIGEST (7+ hex characters are enough). REPOSITORY is IMAGE for the default registry (where builds land) or REGISTRY/IMAGE for another one, e.g. api or prod/api. In a registry with immutable tags an existing tag cannot move (latest excepted); a tag a Container runs by name cannot move either.

Examples

Name the latest build v1.4.0

Shell

th registry images tag api:latest v1.4.0

Point stable at an image by digest

Shell

th registry images tag prod/api@3f2a9c1 stable

Positional arguments

Name	Description
`IMAGE`Required	`REPOSITORY:TAG` or `REPOSITORY@DIGEST` (the first 7 or more hex characters of the digest are enough), or the full `<host>/<project>/REPOSITORY…`.
`TAG`Required	A tag: letters, digits, `_`, `.` and `-`, up to 128 characters, not starting with `.` or `-`.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry images copy`

Copies an image into another repository or registry of the Project, e.g.

Syntax

Shell

th registry images copy SRC DST

to promote it from staging to prod. SRC is REPOSITORY:TAG or REPOSITORY@DIGEST; DST is REPOSITORY[:TAG]. REPOSITORY is IMAGE for the default registry (where builds land) or REGISTRY/IMAGE for another one, e.g. api or prod/api. Without a tag in DST the copy takes SRC's tag, or only its digest when SRC is given by digest. Layers are shared, not stored again, so a copy adds nothing to the storage bill.

Examples

Promote v1.4.0 to prod

Shell

th registry images copy staging/api:v1.4.0 prod/api

Copy a build into prod as stable

Shell

th registry images copy api@3f2a9c1 prod/api:stable

Positional arguments

Name	Description
`SRC`Required	The image to copy: `REPOSITORY:TAG` or `REPOSITORY@DIGEST`.
`DST`Required	Where to copy it: `REPOSITORY` or `REPOSITORY:TAG`.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry images delete`

IMAGE is REPOSITORY:TAG (removes only the tag), REPOSITORY@sha256:DIGEST or REPOSITORY@<first 7+ hex of the digest> (removes the image and all its tags), or the full <host>/<project>/REPOSITORY[:TAG|@DIGEST].

Syntax

Shell

th registry images delete IMAGE [--quiet]

REPOSITORY is IMAGE for the default registry (where builds land) or REGISTRY/IMAGE for another one, e.g. api or prod/api. An image a Container runs cannot be deleted. --quiet skips the prompt.

Examples

Remove a tag

Shell

th registry images delete prod/api:v1.3

Remove an image and all its tags by digest

Shell

th registry images delete api@3f2a9c1

Positional arguments

Name	Description
`IMAGE`Required	`REPOSITORY:TAG` or `REPOSITORY@DIGEST` (the first 7 or more hex characters of the digest are enough), or the full `<host>/<project>/REPOSITORY…`.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry tokens create`

Creates an access token that signs docker, CI or a server elsewhere into this registry alone: read pulls, write pushes and pulls.

Syntax

Shell

th registry tokens create REGISTRY --name NAME [--permission read|write]
    [--expires-in-days N]

The token is printed once on standard output; store it now. Sign in with it as user th:

echo "$TOKEN" | docker login <host> -u th --password-stdin

Examples

A token CI can push with

Shell

th registry tokens create prod --name github-actions --permission write

A pull-only token that ends in 90 days

Shell

th registry tokens create prod --name edge-server --expires-in-days 90

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.

Parameters

Name	Type	Default	Description
`--name`Required	string		Token name, e.g. github-actions (1-60 characters)
`--permission`	string	`read`	Token permission: read pulls, write pushes and pulls
`--expires-in-days`	number		Days until the token stops working (1-730, 0 = never)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry tokens list`

Lists a registry's access tokens.

Syntax

Shell

th registry tokens list REGISTRY

A token is shown once, when it is created; HINT is its last characters, to tell tokens apart.

Examples

The registry’s access tokens

Shell

th registry tokens list prod

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry tokens revoke`

Revokes an access token, by ID or name (see th registry tokens list); it stops working at once.

Syntax

Shell

th registry tokens revoke REGISTRY TOKEN [--quiet]

--quiet skips the prompt.

Examples

Revoke a token by name

Shell

th registry tokens revoke prod github-actions

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.
`TOKEN`Required	The access token’s ID or name, from `th registry tokens list`.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry cleanup`

Every registry's cleanup policy runs by itself every 10 minutes.

Syntax

Shell

th registry cleanup REGISTRY --preview|--run [--keep-latest N]
    [--untagged-days N] [--unpulled-days N] [--keep-tags PATTERNS|none]

--preview lists what the saved policy removes now; with policy flags it lists what that policy would remove, without saving it (save it with th registry update). --run applies the saved policy now and asks first (--quiet skips the prompt).

Images a Container runs, or keeps for rolling back, are never removed by cleanup. Removing images frees storage once no other image uses their layers.

Examples

What the saved policy removes now

Shell

th registry cleanup default --preview

Try a policy before saving it

Shell

th registry cleanup default --preview --keep-latest 5 --unpulled-days 30

Apply the saved policy now

Shell

th registry cleanup staging --run

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.

Parameters

Name	Type	Description
`--preview`	flag	List what would be removed; nothing is removed
`--run`	flag	Apply the saved policy now
`--keep-latest`	number	Keep the newest N images of each repository (0 = no limit)
`--untagged-days`	number	Remove untagged images after N days (1-365, default 7)
`--unpulled-days`	number	Remove images nobody pulled for N days (7-730, 0 = off)
`--keep-tags`	list	Tag patterns always kept, comma-separated, e.g. v*,prod ("none" clears)

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

`th registry delete`

Deletes a registry with all its repositories, images and access tokens.

Syntax

Shell

th registry delete REGISTRY [--quiet]

The default registry cannot be deleted, nor a registry a Container runs an image from. --quiet skips the prompt.

Examples

Delete after a prompt

Shell

th registry delete staging

Positional arguments

Name	Description
`REGISTRY`Required	The registry name, as `th registry list` shows it; `default` is the Project’s default registry.

Global parameters

This command also takes the global parameters: --project, --region, --endpoint, --format, --quiet.

Help centre: the th command line