How to Deploy from Container Images on DigitalOcean App Platform
Quick Answer
Push your container image to a supported registry like DOCR, then create a new app in DigitalOcean App Platform selecting the Container image tab, specify registry/repository/tag, configure resources, and deploy. Use unique tags and linux/amd64 platform for compatibility. Troubleshoot pull failures with cache clears and health checks for reliable scaling.
Prerequisites
- DigitalOcean account with App Platform access
- Docker installed locally for building and testing images
- Container image ready in DOCR, Docker Hub, or GitHub Container Registry
- doctl CLI for terminal deployments (optional but recommended)
- Unique image tags (avoid 'latest')
Step-by-Step Instructions
1
Set Up Prerequisites and Authenticate
Ensure you have a DigitalOcean account and
doctl authenticated via doctl auth init. Install Docker locally and verify your environment matches Linux/AMD64 by testing builds with docker build --platform=linux/amd64. Prepare credentials for private images in username:token format.[1][4]2
Create DigitalOcean Container Registry (DOCR)
Run
doctl registry create my-registry --region nyc3doctl registry repository list.[1][4] Use regions close to your users like nyc3 or fra1.
3
Build and Push Image to Registry
Build your image with
docker build --platform=linux/amd64 --no-cache -t my-image:v1.0.0 .docker tag my-image:v1.0.0 registry.digitalocean.com/my-registry/my-image:v1.0.0. Login via doctl registry login then push: docker push registry.digitalocean.com/my-registry/my-image:v1.0.0. Use unique tags like v1.0.0 instead of 'latest'.[1][4] Test locally first to avoid architecture mismatches.
4
Create App via Dashboard
Log into DigitalOcean Control Panel, go to Apps (https://cloud.digitalocean.com/apps), click Create App. Select Container image tab, choose registry (DOCR/Docker Hub/GitHub), enter repository (e.g.,
my-registry/my-image) and tag/digest (e.g., v1.0.0). Add credentials for private images.[1][4]5
Configure App Resources and Settings
Set App Name (auto-generated default), Resource Type as Web Service, expose HTTP port (default 8080). Choose Instance Size (Basic $5/mo: 0.25 vCPU, 512 MiB RAM), Region (e.g., nyc3), and scaling options. Add environment variables like
DATABASE_URL for databases.[1][4] Enable health checks (e.g., <code>/health</code> path) for reliability.
6
Review Summary and Deploy
Review configuration, pricing, and ports in the Summary section, then click Create App. App Platform pulls the image and deploys automatically. Access via the Overview page URL post-deployment.[1][4]
Monitor deployment logs for image pull status.
7
Deploy Using App Spec (app.yaml)
Create
.do/app.yaml with services defining image: {registry_type: DOCR, registry: my-registry, repository: my-image, tag: v1.0.0}, http_port: 8080, instance settings, routes, and env vars. Use doctl apps create myapp --spec .do/app.yaml.[3] Ideal for CI/CD and repeatable deployments.
8
Update and Redeploy Image
Build/push new tag:
docker build -t registry.digitalocean.com/my-registry/my-image:v2.0.0 . && docker push registry.digitalocean.com/my-registry/my-image:v2.0.0doctl apps create-deployment YOUR_APP_ID to trigger redeploy.[1][3] Use semantic versioning for tags to track changes.
9
Set Up Health Checks and Scaling
Configure
health_check: {http_path: /health, initial_delay_seconds: 10, period_seconds: 30} in app spec or dashboard. Scale via instance count/size slugs like basic-xs. Add managed databases with auto-injected DATABASE_URL.[3][7]10
Verify Deployment and Access App
Check app Overview for URL, logs, and status. Test endpoints and ensure ports match your app's CMD/ENTRYPOINT. Scale or add custom domains as needed.[1][4]
Use DO status page for platform issues.
Common Issues & Troubleshooting
Image pull fails: 'trying and failing to pull image' or no logs
Rebuild with docker build --platform=linux/amd64 --no-cache, use unique tags (not 'latest'), verify credentials, force cache clear, check DO status page.[1][2]
Stuck builds or vague errors
Contact support for stuck deploys, ensure Dockerfile COPY commands work on Linux/AMD64, clear platform caches.[1][2]
Health check failures
Verify HTTP port (8080 default), add /health endpoint, set initial_delay_seconds: 10, ensure app starts correctly.[3][7]
Database connectivity issues
Use managed DB with unrestricted connections, auto-injected DATABASE_URL env var.[7]
Architecture mismatch crashes
Always build/test with --platform=linux/amd64 locally before pushing.[1][2]
Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official DigitalOcean App Platform website before purchasing.