Skip to main content

​
Prerequisites

  • Phala Cloud account
  • Credentials for one of the supported registries:
    • Docker Hub
    • GitHub Container Registry (GHCR)
    • AWS

​
Overview

Phala Cloud supports private image pulls during CVM startup. Registry credentials are passed as encrypted environment variables and only used at runtime inside the trusted boot flow.

​
Method 1: Configure in Cloud UI

  1. Open CVM creation and go to Advanced Features.
  2. Open Private Container Registry.
  3. Select one provider:
    • No private registry
    • Docker Hub
    • AWS
  4. Fill in credentials for the selected provider.
  5. Submit deployment.
Private container registry provider selection
All registry credentials are encrypted before submission and consumed only at runtime.

​
Method 2: Configure with Encrypted Secrets

Set the following environment variables for CLI or API workflows.

​
Docker Hub

Use your Docker Hub username and password (or access token). Image paths follow the format username/image:tag or docker.io/username/image:tag. See Docker Hub documentation for account and repository setup.
VariableRequiredDescription
DSTACK_DOCKER_USERNAMEYesDocker Hub username
DSTACK_DOCKER_PASSWORDYesDocker Hub password or access token
Docker Hub is the default registry — you do not need to set DSTACK_DOCKER_REGISTRY.

​
GHCR

GHCR credential fields
Use your GitHub username and a with read:packages scope. Image paths follow the format ghcr.io/OWNER/IMAGE:TAG. With GitHub CLI, check your token scopes, add read:packages if missing, and print the token: 
gh auth status                      # check current scopes
gh auth refresh -s read:packages    # add read:packages if missing
gh auth token                       # print token for DSTACK_DOCKER_PASSWORD
You can also create a PAT manually at GitHub Settings → Personal access tokens. See GHCR documentation for package visibility and permission details.
VariableRequiredDescription
DSTACK_DOCKER_USERNAMEYesGitHub username
DSTACK_DOCKER_PASSWORDYesGitHub
DSTACK_DOCKER_REGISTRYYesMust be ghcr.io

​
AWS ECR

AWS ECR credential fields
Use an IAM access key with ecr:GetAuthorizationToken and ecr:BatchGetImage permissions. Image paths follow the format ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/REPO:TAG. With AWS CLI: 
aws sts get-caller-identity                          # verify current identity
aws ecr describe-repositories --region <region>      # list repos to confirm access
aws iam create-access-key --user-name <username>     # create a new access key
Verify registry login: 
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account_id>.dkr.ecr.<region>.amazonaws.com
See Amazon ECR documentation for repository creation and IAM policy setup.
VariableRequiredDescription
DSTACK_AWS_ACCESS_KEY_IDYesAWS access key ID
DSTACK_AWS_SECRET_ACCESS_KEYYesAWS secret access key
DSTACK_AWS_REGIONYesECR region
DSTACK_AWS_ECR_REGISTRYYesFull ECR registry URL

​
Deploy with Phala Cloud CLI

You can deploy with phala CLI and pass secrets via -e .env.

​
GHCR example

.env: 
DSTACK_DOCKER_USERNAME=your_github_username
DSTACK_DOCKER_PASSWORD=your_github_pat
DSTACK_DOCKER_REGISTRY=ghcr.io
docker-compose.yml: 
version: '3.8'

services:
  app:
    image: ghcr.io/your-org/your-image:v1.0.0
    ports:
      - "3000:3000"
    environment:
      - DSTACK_DOCKER_USERNAME=${DSTACK_DOCKER_USERNAME}
      - DSTACK_DOCKER_PASSWORD=${DSTACK_DOCKER_PASSWORD}
      - DSTACK_DOCKER_REGISTRY=${DSTACK_DOCKER_REGISTRY}
Deploy: 
phala deploy -n my-private-app -c docker-compose.yml -e .env

​
AWS ECR example

.env: 
DSTACK_AWS_ACCESS_KEY_ID=AKIA...
DSTACK_AWS_SECRET_ACCESS_KEY=...
DSTACK_AWS_REGION=us-east-1
DSTACK_AWS_ECR_REGISTRY=123456789012.dkr.ecr.us-east-1.amazonaws.com

​
Deploy with Phala Cloud API

When using the API, set the same environment variables listed above. See Phala Cloud API docs for endpoint details.

​
Pull Rate Limits

Each registry enforces pull rate limits. During frequent debugging and redeployment cycles, these limits can block image pulls and cause CVM startup failures.

​
Docker Hub

Account typeLimit
Unauthenticated100 pulls / 6 hours per IP
Docker Personal (free, authenticated)200 pulls / 6 hours
Docker Pro / Team / BusinessUnlimited
CVM instances pull images on every startup. If you are iterating quickly on a public Docker Hub image without setting DSTACK_DOCKER_USERNAME / DSTACK_DOCKER_PASSWORD, pulls are unauthenticated and share the 100-pull limit across the host IP. Always configure Docker Hub credentials during active development to get the higher authenticated limit.
See Docker Hub pull usage and limits for details.

​
GHCR

GitHub does not publish hard pull rate limits for GHCR. Public image pulls are effectively unlimited. Private image pulls are subject to your GitHub plan’s data transfer quota. See GitHub billing for Packages for details.

​
AWS ECR

Private does not impose per-image pull rate limits. API calls (e.g. GetAuthorizationToken) are throttled at ~20 TPS per region per account. See Amazon ECR service quotas for details.

​
Troubleshooting

If private image deployment fails:
  1. Verify credentials are valid and not expired.
  2. Ensure image path and tag exist.
  3. Confirm pull permissions for the account used.
  4. Check CVM serial logs for pre-launch errors.

​
GHCR-specific checks

  • DSTACK_DOCKER_REGISTRY is set to ghcr.io
  • contains at least read:packages
  • The package visibility and permission settings allow this account to pull
For additional assistance, join support groups: 🌍 Global, 🇨🇳 Chinese.