# 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>