[Feature]: Server-level default Docker registry and credentials

[jvstme]

Problem

There is currently no way to configure the following settings globally for all runs within an organization:

• Custom Docker Hub credentials (to avoid rate limits and enable access to private images).
• A pull-through registry to replace Docker Hub (to avoid rate limits, enable access to private images, improve pull performance, and ensure availability during Docker Hub outages).

Solution

Allow configuring a server-level default Docker registry and/or default registry authentication credentials.

Proposed server environment variables:

• DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY — the registry to use when the run-level image property does not specify one.
• DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY_USERNAME and DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY_PASSWORD — credentials to use when the run-level image property does not specify a registry and no run-level registry_auth is provided.

Example

Server environment

DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY=docker.mycompany.example
DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY_USERNAME=docker-user
DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY_PASSWORD=docker-password

Run configurations

image: python:3.14  # actually pulled from docker.mycompany.example/python:3.14

Notes

• The values of DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY_USERNAME and DSTACK_SERVER_DEFAULT_DOCKER_REGISTRY_PASSWORD must not be exposed via the API. They should only be resolved at runtime on the server.

Workaround

• Duplicate the registry and its credentials in all run configurations.

  image: docker.mycompany.example/python:3.12
  registry_auth:
    username: ${{ secrets.DOCKER_USER }}
    password: ${{ secrets.DOCKER_TOKEN }}

• Write a plugin to patch the registry and credentials in all submitted runs.

Discussion

• Docker appears to deliberately avoid introducing a setting for overriding the default registry. Since one of the main advantages of Docker is reproducibility across environments, it guarantees that every image from the default namespace (no registry specified) is always pulled from the same place (Docker Hub). It is questionable whether we want to break that guarantee in dstack.
• Project-level registry credential configuration could be achieved through something similar to the previously proposed registry providers. Providing project-level configuration sharable through exports could be an alternative to server-level variables.

Would you like to help us implement this feature by sending a PR?

Yes