# Docker Hub registry mirror

Instruqt provides a Docker Hub mirror available at <https://docker.registry.instruqt.io/>. This can be useful if a track needs to pull a number of images and error messages are being received related to Docker hub rate limits outlined in the [docker docs](https://docs.docker.com/docker-hub/usage/).

{% hint style="info" %}
Docker Hub's rate limits apply when your workload that is running inside the sandbox environment, pulls images directly from Docker Hub. This happens, for example, when you run a `docker pull` command or a Kubernetes deployment that fetches an image.
{% endhint %}

{% hint style="success" %}
It is generally recommended to pre-pull docker images on VM hosts where possible. This improves the learner experience by having a local cache of the docker images, and reduces the amount of API calls from the sandbox.
{% endhint %}

There are two ways to use the Docker Hub registry mirror:

1. Use a [pre-configured k3s/docker image](https://docs.instruqt.com/sandboxes/hosts/using-custom-public-images#instruqt-images) supplied by Instruqt
2. Setting up the container runtime to use the registry mirror - setup varies by client, transparent to most learners
3. Directly pulling from the mirror - stricter guarantees of image pull location, visible to users

## Usage

### Use a pre-configured image

The Docker and Kubernetes images in the Add Host page both come pre-configured with the Docker Hub registry mirror.

<figure><img src="https://2094212015-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MGJDYBXyftBAZb1Wq0e%2Fuploads%2Faw5kyoLEyJa72KqNWkYY%2FScreenshot%202025-09-02%20at%2010-50-00%20K3s%20v1.33.4%20-%20Instruqt.png?alt=media&#x26;token=d8fb6570-52d1-4c77-b4ea-1477bcd716b1" alt="" width="375"><figcaption></figcaption></figure>

### Setting up the container runtime to use the mirror

The instructions vary depending on the operating system and the container runtime.

General instructions for common runtimes:

* Docker \[Community Edition] and `dockerd`: <https://docs.docker.com/docker-hub/image-library/mirror/#configure-the-docker-daemon>\
  e.g. adding the mirror to `/etc/docker/daemon.json`
* `containerd` - specifically `crictl` and `nerdctl`: <https://github.com/containerd/containerd/blob/main/docs/hosts.md#registry-configuration---examples>\
  e.g. adding an appropriate `/etc/containerd/certs.d/docker.io/hosts.toml`. \
  :warning:`ctr` does not respect the `containerd` `hosts.toml` configuration
* k3s - specifically rancher: <https://docs.k3s.io/installation/private-registry#mirrors>\
  e.g. adding an appropriate `/etc/rancher/k3s/registries.yaml` with the mirror config.

When editing the configuration settings above, ensure that the relevant service has been restarted.

Testing the mirror varies per tool. A fairly consistent test is as follows:

1. Ensure an image is removed from the runtime: e.g. `docker image rm nginx:latest`
2. Pull the again: e.g. `docker pull nginx:latest`

The container mirror is hosted on Google Cloud, so the pull of the container should be very fast (< 1ms when using `nginx:latest`).

### Directly pulling images from the mirror

Pulling images directly from the mirror can be done by prefixing (or replacing docker.io) with the mirror address as follows:

```sh
docker pull docker.registry.instruqt.io/library/nginx:latest
```

It is generally not recommended to create tracks with this substitution, however it might help in pinpointing registry mirror setup issues.

Notes:

* `library/` can be omitted, but is generally recommended to be used. This value is generally implied when using Docker CLI.
* The first pull may take slightly longer when added to the cache

## FAQ

<details>

<summary>Are there any usage restrictions?</summary>

The container mirror is open for anyone developing tracks on Instruqt.&#x20;

Instruqt reserves the right to block access to the container mirror if it is being used for purposes not related to Instruqt tracks and/or content creation.

</details>

<details>

<summary>Can I use the container mirror in my Custom VM image?</summary>

Yes absolutely! We encourage the usage of this mirror in [create-a-custom-vm-image](https://docs.instruqt.com/sandboxes/hosts/create-a-custom-vm-image "mention").&#x20;

</details>

<details>

<summary>I am getting an unauthorized message when pulling containers</summary>

This is likely due to your docker client attempting to authenticate to docker hub. This is not needed when using the container mirror.

</details>

<details>

<summary>Can I use private container images on my own docker hub account?</summary>

Not at this time.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/reference/platform/docker-hub-registry-mirror.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.