Combining both registries

Keep the macOS base template in the Anka Registry and each tool as a thin tag in an OCI registry

You can use the Anka Registry and an OCI registry together:

  • The Anka Registry stores the macOS base template as a full tag. The Build Cloud Controller can use it.
  • The OCI registry stores each tool as a small thin tag. You can pull the same tool tag onto templates for other macOS versions.

Rules

  • Pull the full tag from the Anka Registry first. Then pull the thin tags. A pull of a full tag removes the thin tags that you pulled before it.
  • --thin and push_mode apply only to the pushes to the OCI registry. Use --thin for tool tags. A push to the Anka Registry always stores the full tag.
  • The Anka Registry does not store thin tags.

For all differences, see Full tags and thin tags.

Example

Push the macOS base tag to the Anka Registry

Create a new VM. anka create installs macOS only. This push uploads the macOS disk as a full tag to the Anka Registry in ANKA_REGISTRY. The Anka Registry always stores the full tag, so push_mode does not apply.

❯ anka create 27.0.1 27.0.1
❯ anka push 27.0.1 -t vanilla http://anka.registry:8089

http://anka.registry:8089 is the Anka Registry. An OCI registry URL has a /v2/ path. This push creates template 27.0.1 and tag vanilla on the Anka Registry. A new 27.0.1 VM reports about 29.82GiB uploaded to tag vanilla. Pull this tag when a host needs the macOS disk:

❯ anka pull 27.0.1 -t vanilla http://anka.registry:8089

Push the tool tags to the OCI registry

Install one tool, stop the VM, and push the next tag with --thin. Leave push_mode at 1. Leave the repository name off the URL. Anka uses the VM name.

❯ anka start 27.0.1
# install Xcode in the VM, then stop it
❯ anka stop 27.0.1
❯ anka push --thin 27.0.1 -t xcode-27.1 oci://registry.example.com/v2/

The xcode-27.1 tag is a thin tag. It holds only the last layer: the files that changed after vanilla.

Install CMake and stop the VM.

❯ anka start 27.0.1
# install CMake in the VM, then stop it
❯ anka stop 27.0.1

The tag chain on this VM is now the vanilla tag, then the xcode-27.1 tag, then the CMake changes. Push cmake with --thin so that tag holds only the CMake layer. push_mode 2 is another way to store only the file changes. See Push modes.

For the two forms of the cmake push, see Without --thin and With --thin.

Publish a template for Anka Build Cloud

The Build Cloud Controller cannot pull OCI tags, full or thin. Build the template on a producer host instead:

  1. Pull the macOS base tag (a full tag) from the Anka Registry.
  2. Pull each thin tag onto that VM, in order.
  3. Push the finished VM to the Anka Registry. The Anka Registry stores it as a full tag.

That rebuilds the thin-tag stack for the final template. You do not start the VM to install the tools again.

The Controller can then start VMs from that template, the same as from any other template. For the commands, see Preparing a build VM.