Introduction

In the previous chapters, you’ve established a robust local container development environment on your Apple Silicon Mac, built a Linux container machine using Colima, efficiently mounted project volumes, and successfully built ARM64 OCI images for your sample application. Now, it’s time to share these images with the world, or at least with your team and deployment pipelines.

This chapter focuses on the critical step of authenticating your local container environment with a remote OCI (Open Container Initiative) registry and pushing your custom-built images. Whether you’re deploying to a Kubernetes cluster, sharing with collaborators, or simply archiving your work, a container registry is the central hub for image management.

By the end of this chapter, you will be able to:

  • Understand the role of OCI registries in a development workflow.
  • Authenticate your Colima/nerdctl or Podman environment to common registries like Docker Hub or GitHub Container Registry.
  • Tag your locally built ARM64 images with the correct registry and repository format.
  • Push your tagged images to a remote registry, making them accessible for pulls.

Planning & Design: Image Distribution Workflow

Pushing an OCI image to a registry is a fundamental step in any containerized workflow. It transforms a local artifact into a shareable, versioned asset. The process involves three main logical steps:

  1. Authentication: Proving your identity and authorization to the registry. This typically involves a username and password (or token).
  2. Tagging: Giving your image a name and version that includes the registry’s address, making it unique and discoverable within the registry.
  3. Pushing: Uploading the image layers and manifest to the registry.

We will focus on popular public registries like Docker Hub or GitHub Container Registry, but the principles apply equally to private registries (e.g., AWS ECR, Google Container Registry, GitLab Container Registry).

Choosing an OCI Runtime and Registry

For this guide, we’ll continue using Colima with containerd and its client nerdctl, as established in previous chapters. If you opted for Podman Desktop in Chapter 1, the commands will be similar, but we’ll provide specific podman equivalents where useful.

For the registry, Docker Hub is a widely used and accessible option for demonstration. You’ll need a Docker ID and an account.

Workflow Overview

flowchart TD A[Local Container Machine] --> B{Authenticate to Registry} B -->|Credentials| C[OCI Registry] C -->|Success| D[Image Built Locally] D --> E[Tag Image] E --> F[Push Image] F --> C C -->|Image Stored| G[Remote Consumers] subgraph UserActions["User Actions"] A B D E F end

Step-by-Step Implementation

We’ll use the sample-api image built in Chapter 4. Ensure your colima instance is running.

colima start

1. Authenticate to the OCI Registry

First, you need to log in to the chosen container registry. We’ll demonstrate with Docker Hub.

Using nerdctl (with Colima)

If you’re using nerdctl, it can leverage the standard ~/.docker/config.json file. This means if you’ve ever logged in via docker login (e.g., from Docker Desktop), nerdctl might pick up those credentials. However, it’s good practice to log in explicitly with nerdctl.

  1. Open your terminal and ensure you’re connected to colima.

  2. Execute the login command: Replace YOUR_DOCKER_USERNAME with your actual Docker Hub username.

    nerdctl login docker.io

    You will be prompted to enter your Docker ID and password. For better security, especially in automated scripts, consider using a Personal Access Token (PAT) instead of your main password. Docker Hub allows you to create PATs with specific permissions.

    Expected Output (similar to):

    Username: YOUR_DOCKER_USERNAME
Password:
Login Succeeded

    📌 Key Idea: docker.io is the default registry for Docker Hub. Explicitly stating it is good practice, but often optional for Docker Hub.

Using podman

If you are using Podman Desktop or podman directly, the command is similar:

  1. Open your terminal.

  2. Execute the login command:

    podman login docker.io

    You’ll be prompted for your username and password.

    Expected Output (similar to):

    Authenticating with existing credentials...
Login Succeeded!

2. Tagging the Image for the Registry

After successful authentication, you need to tag your local image so it includes the full path to its destination in the registry. The standard format is [registry-hostname]/[username]/[repository-name]:[tag].

For Docker Hub, registry-hostname is docker.io (or often omitted as it’s the default), and username is your Docker ID.

  1. List your local images to confirm the sample-api image exists.

    nerdctl images

    Expected Output (truncated):

    REPOSITORY          TAG         IMAGE ID        CREATED          PLATFORM    SIZE        BLOB SIZE
sample-api          latest      a1b2c3d4e5f6    2 minutes ago    linux/arm64 120.5 MB    120.5 MB
...

  2. Tag the sample-api image: Replace YOUR_DOCKER_USERNAME with your Docker ID. We’ll tag it as v1.0.0.

    nerdctl tag sample-api:latest docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0

    Now, if you list images again, you’ll see the new tag:

    nerdctl images

    Expected Output (truncated, showing new tag):

    REPOSITORY                                  TAG         IMAGE ID        CREATED          PLATFORM    SIZE        BLOB SIZE
sample-api                                  latest      a1b2c3d4e5f6    5 minutes ago    linux/arm64 120.5 MB    120.5 MB
docker.io/YOUR_DOCKER_USERNAME/sample-api   v1.0.0      a1b2c3d4e5f6    5 minutes ago    linux/arm64 120.5 MB    120.5 MB
...

    🧠 Important: The IMAGE ID for both tags (sample-api:latest and the new registry-prefixed tag) is the same. This means they both point to the same underlying image layers locally. Tagging doesn’t duplicate the image, it just creates an alias.

Using podman

For podman, the tagging command is identical:

podman tag sample-api:latest docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0

3. Pushing the Image to the Registry

With the image tagged correctly and authentication established, you can now push it.

  1. Execute the push command:

    nerdctl push docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0

    The command will output the progress as it pushes each layer of your image to the registry. This might take some time depending on your internet connection and image size.

    Expected Output (truncated, showing layer push progress):

    docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0
INFO[0000] pushing image "docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0"
INFO[0000] pushing layer "sha256:..."
INFO[0000] pushing layer "sha256:..."
...
INFO[00XX] successfully pushed "docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0"

Using podman

For podman, the push command is also identical:

podman push docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0

Testing & Verification

After the push command reports success, it’s crucial to verify that the image is indeed available in the remote registry.

  1. Check the Registry’s Web UI:
    • Navigate to https://hub.docker.com/repositories (or your chosen registry’s equivalent).
    • Log in if required.
    • You should see a new repository named sample-api under your username, containing the v1.0.0 tag (and potentially an latest tag if you pushed that too, or if the registry automatically adds one).
  2. Pull the Image to a Different Environment (Optional but Recommended): If you have another machine or even a fresh colima instance, you can attempt to pull the image to confirm its accessibility.

    • From a different terminal, or after colima stop and colima start (to clear local cache), try:

      nerdctl pull docker.io/YOUR_DOCKER_USERNAME/sample-api:v1.0.0

      This confirms that the image is correctly stored and can be retrieved.

Production Considerations

While pushing an image might seem straightforward, several production-minded practices are essential:

  • Security of Credentials:
    • Personal Access Tokens (PATs): Always prefer PATs over your main account password for programmatic access. PATs can be revoked easily and have fine-grained permissions.
    • Secrets Management: In CI/CD pipelines, never hardcode credentials. Use secure secrets management systems (e.g., Vault, Kubernetes Secrets, CI/CD platform secrets) to inject credentials at runtime.
  • Image Versioning:
    • Semantic Versioning: Adopt a clear versioning strategy (e.g., v1.0.0, v1.0.1, v2.0.0). This helps in tracking changes and ensures reproducible deployments.
    • latest Tag: While convenient for local development, relying solely on the latest tag in production can be risky due to its mutable nature. Always pin to specific versions (v1.0.0) for deployments to ensure consistency.
    • Git SHAs: For advanced workflows, automatically tagging images with Git commit SHAs can provide an immutable link between code and image.
  • Image Scanning: Before pushing to a production registry, integrate vulnerability scanning tools (e.g., Trivy, Clair, registry-provided scanners) into your workflow. This helps identify and mitigate known security vulnerabilities in your base images and application dependencies.
  • Registry Choice:
    • Public vs. Private: For proprietary applications or sensitive data, use private registries. Public registries are suitable for open-source projects or testing.
    • Geographic Proximity: Choose a registry geographically close to your deployment targets to reduce latency during image pulls.
  • Automation with CI/CD: Building and pushing images should ideally be automated as part of your Continuous Integration/Continuous Delivery (CI/CD) pipeline. Tools like GitHub Actions, GitLab CI, Jenkins, or CircleCI can trigger builds and pushes on every code commit.

Common Issues & Solutions

  1. unauthorized: authentication required or denied: requested access to the resource is denied:
    • Issue: Failed to authenticate or insufficient permissions.
    • Solution: Double-check your username and password/PAT. Ensure the PAT has write permissions to the repository. Try nerdctl logout docker.io (or podman logout) and nerdctl login docker.io again to re-authenticate. Verify your Docker Hub account is active.
  2. no such image or reference does not exist during tagging/pushing:
    • Issue: The local image name/tag you’re trying to push doesn’t exist, or you’ve made a typo.
    • Solution: Run nerdctl images (or podman images) to list all local images and verify the exact name and tag you built in Chapter 4. Correct your command accordingly.
  3. Slow push performance or timeouts:
    • Issue: Large image size or slow internet connection.
    • Solution: Optimize your Dockerfile to create smaller images (e.g., use multi-stage builds, minimal base images like Alpine, remove unnecessary files). Ensure you have a stable internet connection. Some registries have rate limits; check their documentation.
  4. name contains invalid characters during tagging:
    • Issue: You used special characters in your image name or tag that are not allowed by the OCI specification or the registry.
    • Solution: Stick to lowercase alphanumeric characters, hyphens, and dots for repository names and tags. Avoid underscores or other symbols.

Summary & Next Step

Congratulations! You’ve successfully authenticated your local container environment, tagged your custom ARM64 OCI image, and pushed it to a remote registry. This is a crucial step that transforms your local development artifact into a shareable, deployable asset, ready for consumption by other systems or team members. You now have a full end-to-end workflow for developing, building, and distributing container images directly from your Apple Silicon Mac.

In the final chapter, we’ll step back and compare this entire Apple container machine setup with other popular local development environments, such as Docker Desktop, full Linux VMs, and remote development containers. This will help you understand the trade-offs and best use cases for each, empowering you to make informed decisions for your projects.

References

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.