Configuring Docker

Learn how to configure Docker and compatible container runtimes to authenticate against your DepAegis private container registry.

Logging In to the DepAegis Registry

Use docker login to authenticate against the hosted registry at app.depaegis.com:

docker login app.depaegis.com

When prompted, enter your DepAegis username and use a Personal Access Token as the password.

You can also authenticate non-interactively (useful for CI/CD):

echo "dap_abc123def456..." | docker login app.depaegis.com -u your-username --password-stdin

Understanding config.json

After a successful docker login, Docker writes credentials to ~/.docker/config.json (or %USERPROFILE%\.docker\config.json on Windows). This file stores authentication information for each registry you have logged in to:

{
  "auths": {
    "app.depaegis.com": {
      "auth": "dXNlci10b2tlbjpkYXBfYWJjMTIzZGVmNDU2Li4u"
    }
  }
}

The auth field contains a Base64-encoded string of username:token. Docker sends this as a Basic auth header on every request to the registry.

Credential Helpers

Credential helpers store your registry credentials in the operating system's secure credential store instead of config.json. This is the recommended approach for developer workstations.

Windows — wincred

# Install the helper (Docker Desktop includes it)
# Configure Docker to use it
"credsStore": "wincred"

Add the credsStore key to your config.json. After this change, docker login stores tokens in the Windows Credential Manager.

macOS — osxkeychain

"credsStore": "osxkeychain"

Credentials are stored in the macOS Keychain. Docker Desktop for Mac enables this by default.

Linux — pass

"credsStore": "pass"

Uses pass, the standard Unix password manager. Requires gpg and pass to be installed.

Complete config.json with credential helper

{
  "credsStore": "osxkeychain",
  "auths": {}
}

After setting credsStore, the auths object is left empty — Docker delegates all credential storage to the helper.

Podman Compatibility

Podman is fully compatible with DepAegis because it implements the same OCI Distribution Spec as Docker. Login works identically:

podman login app.depaegis.com

Podman stores credentials in its own configuration at ~/.config/containers/auth.json, which follows the same format as Docker's config.json. If you use both Docker and Podman on the same machine, you can symlink the files:

ln -s ~/.docker/config.json ~/.config/containers/auth.json

Multiple Registry Configuration

If you push to multiple registries (e.g. DepAegis for private images and Docker Hub for public ones), Docker handles multiple auth entries seamlessly. Each registry has its own entry:

{
  "auths": {
    "app.depaegis.com": {
      "auth": "dXNlci10b2tlbjpkYXBfYWJjMTIz..."
    },
    "https://index.docker.io/v1/": {
      "auth": "ZG9ja2VyaHViLXVzZXI6cGFzc3dvcmQ..."
    }
  }
}

Docker automatically selects the correct credentials based on the registry hostname in the image tag. No additional configuration is needed.

Verifying Your Login

After logging in, verify that authentication is working by pulling a small test image through your registry. If your organization has set up a pull-through cache or proxy, any public image will be served from DepAegis:

docker pull app.depaegis.com/library/hello-world:latest

Alternatively, check that your token is valid by using the Docker API directly:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Basic $(echo -n 'your-username:dap_abc123...' | base64)" \
  "https://app.depaegis.com/v2/"

A 200 response confirms authentication is working. A 401 means the credentials are invalid or expired.

Troubleshooting Certificate Errors

DepAegis serves all endpoints with certificates from a trusted CA, so Docker works out of the box. If you see an error like:

Error response from daemon: Get "https://app.depaegis.com/v2/":
  x509: certificate signed by unknown authority

...the cause is almost always a corporate proxy, VPN, or TLS-inspection appliance re-signing traffic with its own CA. Add your organization's root CA to the system trust store:

Option 1 — Add the CA certificate to the system trust store

Ubuntu / Debian:

sudo cp my-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
sudo systemctl restart docker

RHEL / CentOS:

sudo cp my-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
sudo systemctl restart docker

Windows (Docker Desktop):

# Import into the Windows trusted root store
certutil -add-store "Root" my-ca.crt

Alternative - Trust the CA in Docker directly

Place the CA certificate in Docker's certificate directory. Docker expects certificates per-hostname:

# Linux/macOS
mkdir -p /etc/docker/certs.d/app.depaegis.com
cp my-ca.crt /etc/docker/certs.d/app.depaegis.com/ca.crt

# Windows (Docker Desktop)
# Place the file in:
# %PROGRAMDATA%\docker\certs.d\app.depaegis.com\ca.crt