Set a custom Docker registry for Qubernetes projects

You can now configure a custom Docker registry for your Qubernetes projects by adding the registry field under the docker section in your Q8Sproject file. This allows you to use alternative container registries instead of the default Docker Hub.

Q8Sproject

name: my-quantum-project
...
 
docker:
  username: myusername
  registry: ghcr.io

Image naming conventions

The image name is constructed based on the configuration provided:

With both registry and username: registry/username/q8s-projectname:target
Q8Sproject
```
name: my-quantum-project
 
docker:
  username: myusername
  registry: ghcr.io
```
Results in: ghcr.io/myusername/q8s-my-quantum-project:gpu
With username only: username/q8s-projectname:target
Q8Sproject
```
name: my-quantum-project
 
docker:
  username: myusername
```
Results in: myusername/q8s-my-quantum-project:gpu

Important

If neither username nor registry is specified, an error will be raised:

ProjectInvalidConfigurationException: Docker username and/or registry must be specified in the project configuration

Supported registries

This feature works with any Docker-compatible registry. At the moment we have tested with:

Docker Hub (default)
GitHub Container Registry (ghcr.io)

Make sure you are authenticated to your chosen registry before building and pushing images.

Example: Using GitHub Container Registry (GHCR)

Here’s a complete workflow example using GitHub Container Registry:

Step 1: Create a Personal Access Token (PAT)

Follow GitHub’s guide on creating a Personal Access Token (classic) and ensure you select the write:packages scope. This token will be used to authenticate with the GHCR.

Save your token securely as you’ll need it in the next steps.

Step 2: Configure your Q8Sproject file

Q8Sproject

name: my-quantum-project
 
docker:
  username: your-github-username
  registry: ghcr.io

Step 3: Authenticate with GHCR

Save your PAT as an environment variable and authenticate with Docker:

# On Linux/macOS
export REGISTRY_PAT=YOUR_PERSONAL_ACCESS_TOKEN
echo $REGISTRY_PAT | docker login ghcr.io -u your-github-username --password-stdin
 
# On Windows (PowerShell)
$env:REGISTRY_PAT="YOUR_PERSONAL_ACCESS_TOKEN"
echo $env:REGISTRY_PAT | docker login ghcr.io -u your-github-username --password-stdin

You should see: Login Succeeded

Step 4: Build and push the image

Use the q8sctl command to build and push your environment image to GHCR:

q8sctl build --init

This will create and push an image to: ghcr.io/your-github-username/q8s-my-quantum-project:gpu

Step 5: Execute code using the pushed image

When executing code, if the image is stored in a private registry, q8s can retireve the registry PAT from REGISTRY_PAT env variable. If you set REGISTRY_PAT env variable properly in step 3, then you can simply run below command.

q8sctl execute quantum_program.py

Alternatively, you can use --registry_pat=<your_registry_pat> command to pass registry PAT manually.