How to Deploy from Container Images

You can deploy containerized apps to App Platform from supported container registries. App Platform currently supports deploying public and private images from DigitalOcean Container Registry, Docker Hub, and GitHub Container Registry.

Apps include two types of deployable resources: app resources for running code, and database resources for managed databases.

App resources are made up of components, which define how code is built, deployed, and run. Supported component types include web services, static sites, workers, and jobs. Web services, workers, and jobs run in containers from a repository or container image, while static sites are hosted from a directory of static files on DigitalOcean’s CDN.

App Platform only supports Linux-based container images built for the AMD64 architecture. If you push an image with a different OS or architecture, the build fails.

Deploy from a Container Image Using the Control Panel

To deploy an app from a container registry using the DigitalOcean Control Panel, click Create, then select App Platform from the dropdown menu.

On the Create an app screen:

• Select the Container image tab, then choose your container registry, either DigitalOcean Container Registry, Docker Hub, or GitHub Container Registry.
• Select or enter the repository that hosts your app’s image.
• Enter an image tag or digest of the image to deploy.
• If you choose Docker Hub or GitHub Container Registry, you can enter credentials to access private images using the syntax username:token or username:password. Public images do not require credentials.
• If you are using DigitalOcean Container Registry, select the Autodeploy option to have App Platform automatically redeploy your app whenever a new image with the specified tag is pushed.
• Click Next.

Configure Resource Settings

The Resource settings table displays configuration settings, some of which the detection system auto-fills. Click Edit beside settings you want to change.

You can configure the following settings:

• Name: A unique name for the component.

• Resource type: The type of component to deploy (web service, static site, worker, or job).

  Note

  The selected Resource type determines which fields in the following list are displayed in the Resource settings table.

• Instance size: The amount of memory (RAM), CPUs, and bandwidth allocated to the component. You can choose shared or dedicated CPUs. Shared CPUs share their processing power with other DigitalOcean users. Dedicated CPUs are dedicated solely to your app. We recommend dedicated CPUs for more resource-intensive applications that require consistent high performance and autoscaling.

• Containers: The component's scaling settings. The instance size you select determines the scaling options available. For more details, see How to Scale Apps in App Platform.

• Build command: A custom build command to run before the app is deployed. This is useful for compiling assets, installing dependencies, or running tests before deployment.

• Run command: A custom run command for the application to run after deployment. If no run command is specified, the default run command for your app's language is used, such as npm start for a Node.js app. For Dockerfile-based builds, entering a run command overrides the Dockerfile's entrypoint.

• Output Directory: For static sites only. An optional path to where the build assets are located, relative to the build context. If not set, App Platform automatically scans for these directory names: _static, dist, public, build.

• Public HTTP port: For web services only. The port that the app receives HTTP requests on. The default port is 8080.

• Internal ports: For web services only. The port that the app receives internal requests on.

• HTTP request routes: For web services and static sites only. The URL path where the app can be accessed, such as your-app-v3cl4.ondigitalocean.app/api. If not specified, the app is accessible from the provided hostname's root.

  Note

  The service must bind to and expose the HTTP port on the network interface 0.0.0.0, rather than on the localhost (localhost) or loopback interface (127.0.0.1).

  Full HTTP request path preservation for services is not available in the Control Panel. Instead, set the preserve_path_prefix annotation in the App Spec to true.

• Environment variables: Key-value pairs available to your app at runtime that let you keep configuration separate from application code. Use them to provide secrets, API keys, and other external settings, such as connection details for an external database.

App Platform uses cloud-native buildpacks to build components and applies the buildpack's default build and run commands. See the cloud-native buildpack reference for details about supported buildpacks.

Add a Database

In the Add a Database section, you can connect a database to your app:

• To provision a new dev database directly within your app, click Create dev database.
• To connect an existing DigitalOcean Managed Database, click Attach DigitalOcean database.
• If your database is hosted outside of DigitalOcean, add environment variables in the Resource settings table to provide the connection details.

See How to Manage Databases in App Platform for details on connecting databases.

After connecting a dev or managed database, App Platform automatically injects the necessary connection information into the relevant component’s environment variables.

Set App-Level Environment Variables

App-level environment variables are available to all components in your app. Use them for shared configuration, secrets, API keys, or other values your app needs at build time or runtime.

To set app-level environment variables:

• Click Edit in the App-level environment variables section.
• Click Add environment variable, type a key and value, then select a scope.
• Select Encrypt to obscure the value in build, deployment, and application logs.

For dynamic, app-specific variables that your app can reference, see Use Bindable Variables.

Choose Datacenter Region

In the Datacenter region section, click the Choose a datacenter region dropdown menu, then select the region to deploy your app into. To minimize latency, choose the region geographically closest to your users.

Region selection is not available for static sites. Static resources are served through DigitalOcean’s global CDN.

Finalize

In the Finalize section, you can update the app's name and project:

• In the Choose a unique app name field, type a name for the app.
• In the Select a project dropdown menu, select an existing project and environment or click Create new project.
• If you create a new project, enter a name, then select a purpose and environment for the new project.

When finished, review your configuration settings and pricing details in the Summary section, then click Create App.

App Platform creates the app using the selected settings and deploys it automatically. After deployment, you can view it using the URL at the top of the app's Overview page.

Change the Container Image Tag After Deployment

You can change the tag and autodeploy settings for an existing deployment.

Go to the Apps page, click your app, and then click the Settings tab.

Choose the resource that uses a container image.

In the Source section click Edit, select a new value from the Tag dropdown menu, and adjust the Autodeploy setting as needed.

Click Save to apply the changes and redeploy the app.

Deploy a Container Image Using the App Spec

You can deploy an image from a container registry by adding an image object to your app spec.

To do this, edit your app spec and include an image object with the appropriate fields.

We recommend using SHA digests instead of tags to ensure consistency and avoid caching issues. Tags like latest can change over time, but digests always reference the same image.

The image object can contain the following fields:

• registry_type: The container registry service. Valid values:
  • DOCR for DigitalOcean Container Registry
  • DOCKER_HUB for Docker Hub
  • GHCR for GitHub Container Registry
• registry: The registry name. For DOCKER_HUB and GHCR, this is the organization that owns the image.
• repository: The image repository name.
• registry_credentials: Credentials for accessing a private Docker Hub or GitHub registry, in the format "$username:$token". We recommend using a non-expiring token with read-only scope. See GitHub and Docker Hub documentation for details.
• digest: The image’s SHA digest. Cannot be used with tag.
• tag: The image tag. Cannot be used with digest.
• deploy_on_push: Enables automatic redeployment when a new image is pushed. Available only for DigitalOcean Container Registry.

deploy_on_push:
  enabled: true

The following example deploys an image from a private Docker Hub registry using a digest:

name: front-end
services:
- name: web
  image:
    registry_type: DOCKER_HUB
    registry: example-registry
    repository: example-repo
    registry_credentials: "your_username:2YotnFZFEjr1zCsicMWpAA"
    digest: sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

When you first submit the spec, registry_credentials must be provided in plain text. App Platform then encrypts and stores them similarly to secret environment variables. After submission, App Platform updates the spec with encrypted values, making it safe to store in the app’s repo.

After adding the image object, you can upload the spec in the Control Panel, apply it using doctl, or push the spec to your repo to trigger a deployment.

If you deploy using doctl, the command you choose affects whether a new image is deployed:

• doctl apps create-deployment always pulls and deploys a new image, even if the tag or digest is unchanged.
• doctl apps update and doctl apps create --upsert only apply spec changes. They reuse the existing image tag or digest and do not deploy a new image by default. To trigger the deployment of a new image consistently, use SHA digests.