DigitalOcean Container Registry (DOCR) Setup Guide

This guide explains how to set up and use DigitalOcean Container Registry (DOCR) for your container images.

Benefits of DOCR

Lower Latency: Images are stored closer to your DigitalOcean droplets
Better Integration: Native integration with DigitalOcean infrastructure
Cost Effective: Often cheaper than other container registries
Private by Default: All images are private unless explicitly made public
Simple Authentication: Uses DigitalOcean API tokens

Prerequisites

DigitalOcean account
DigitalOcean API token with read/write permissions
Docker installed on your local machine and deployment server

Step 1: Create a Container Registry

Log in to your DigitalOcean account
Navigate to Container Registry in the sidebar
Click Create Registry
Choose a registry name (e.g., oter-registry)
Select a subscription plan (Starter is free for 500MB storage)
Click Create Registry

Step 2: Generate API Token

Go to API → Tokens/Keys in DigitalOcean
Click Generate New Token
Give it a name (e.g., DOCR-Access-Token)
Select Write scope (includes read permissions)
Click Generate Token
Copy the token immediately - you won’t be able to see it again!

Step 3: Configure GitHub Secrets

Add the following secrets to your GitHub repository:

Go to your repository → Settings → Secrets and variables → Actions
Add the following secrets:
- DOCR_REGISTRY_NAME: Your registry name (e.g., oter-registry)
- DOCR_TOKEN: Your DigitalOcean API token

Step 4: Configure Docker on Deployment Server

On your DigitalOcean droplet, authenticate Docker with DOCR:


# Login to DOCR (use your API token as both username and password)
echo "YOUR_DOCR_TOKEN" | docker login registry.digitalocean.com -u "YOUR_DOCR_TOKEN" --password-stdin

Or add it to your deployment script’s environment variables.

Step 5: Image Naming Convention

DOCR uses the following format:


registry.digitalocean.com/<registry-name>/<image-name>:<tag>

Examples:

registry.digitalocean.com/oter-registry/oter-server:latest
registry.digitalocean.com/oter-registry/oter-server:v1.0.0
registry.digitalocean.com/oter-registry/oter-web-app:sha-abc1234

Step 6: Verify Setup

Test pulling an image:


docker pull registry.digitalocean.com/oter-registry/oter-server:latest

Migration from GHCR

If you’re migrating from GitHub Container Registry:

Push existing images to DOCR:


# Tag existing image
docker tag ghcr.io/your-org/oter-server:latest \
  registry.digitalocean.com/oter-registry/oter-server:latest
 
# Login to DOCR
echo "YOUR_DOCR_TOKEN" | docker login registry.digitalocean.com -u "YOUR_DOCR_TOKEN" --password-stdin
 
# Push to DOCR
docker push registry.digitalocean.com/oter-registry/oter-server:latest

Update your docker-compose.yml files - They already use environment variables, so just update the IMAGE_REPO value
Update deployment scripts - Already done! The scripts now support DOCR with fallback to GHCR

Security Best Practices

Rotate tokens regularly: Generate new tokens every 90 days
Use read-only tokens for pull operations: Create separate tokens with read-only scope
Never commit tokens: Always use secrets management
Enable registry vulnerability scanning: Available in DOCR settings

Troubleshooting

Authentication Errors

If you get authentication errors:


# Verify token is correct
doctl registry login
 
# Or manually login
echo "YOUR_TOKEN" | docker login registry.digitalocean.com -u "YOUR_TOKEN" --password-stdin

Image Not Found

Verify the registry name matches exactly
Check image name and tag are correct
Ensure the image was pushed successfully

Rate Limiting

DOCR has rate limits based on your plan. If you hit limits:

Upgrade your DOCR subscription
Implement image caching on your deployment server
Use image tags instead of rebuilding every time

Cost Optimization

Clean up old images: Regularly remove unused image tags
Use specific tags: Avoid using latest tag in production
Monitor storage usage: DOCR charges based on storage used
Enable garbage collection: Automatically remove untagged images