Hyphen

DigitalOcean

Learn how to connect a DigitalOcean team to Hyphen to build and deploy containerized apps to DigitalOcean App Platform using the Hyphen CLI.

Connect a DigitalOcean team to Hyphen to deploy Docker apps to App Platform. The Hyphen CLI uploads images to DigitalOcean Container Registry. Hyphen Deploy releases the image by digest.

Table of Contents

Prepare DigitalOcean

  1. Open the DigitalOcean Control Panel.
  2. In the profile menu, select Switch Teams.
  3. Select the team that will host your apps and images.
  4. If the team has no registry, create a container registry.
  5. Open Applications & API → Tokens.
  6. Select Generate New Token.
  7. Enter a name for the token.
  8. Select an expiration that follows your organization's token policy.
  9. Select Custom Scopes.
  10. Set the permissions in the table below.
Resource Permissions When to select
account Read Required
actions Read Required
app Read, Create, Update, Delete Required
project Read, Create, Update, Delete, Assign Resource Required
regions Read Required
registry Read, Update Required
sizes Read Required
domain Read, Create, Update, Delete Only for DigitalOcean DNS

If a permission is unavailable, ask the team owner for access. See the DigitalOcean token scope reference.

Connect the Team

  1. Select Generate Token in DigitalOcean.
  2. Copy the token. DigitalOcean shows its value once.
  3. Open Integrations in your Hyphen organization.
  4. Select DigitalOcean.
  5. Paste the token into API token.
  6. Select Test.
  7. Select Connect after the test succeeds.

The test checks access to the account and registry list. A test deployment verifies that Hyphen can push an image and deploy it to App Platform.

Set Up Project Connections

The project needs a Cloud Workspace and a Container Registry for DigitalOcean. The workspace maps to a DigitalOcean project. The registry connection uses an existing registry in the team.

  1. Open your project and select an environment.
  2. Open the deployment settings.
  3. Include your app with App Type set to Container.
  4. Select DigitalOcean under Deploy to.
  5. Select or create the required project connections.
  6. Save the deployment configuration.

If the team has one registry, Hyphen selects it automatically. If the team has several, the registry connection shows Needs input. Open Details, then open the setup run and select a registry. Wait for both connections to reach Ready before you build.

Hyphen puts images under the project and app alternate IDs. Registry credentials have team-wide access.

Build and Deploy

Use Hyphen CLI v0.33.0 or later. Run hx update to update an existing installation. App Platform requires Linux AMD64 images, which the CLI builds by default.

  1. Open your app folder.
  2. Run hx init to link the folder to your Hyphen app.
  3. Run the deployment command:
hx deploy --env production

Replace production with your environment ID or alternate ID. Open the CLI link to check the deployment run. After the run succeeds, open the app URL from the deployment resources.

If your Dockerfile sets EXPOSE, specify a single HTTP port. App Platform uses one region per deployment. Additional traffic regions do not provide regional failover.

Use a Custom Hostname

Without a custom hostname, App Platform supplies an ondigitalocean.app URL. To use your own hostname, connect the DNS zone in Settings → DNS → Add Zone. Set the hostname in the app's deployment settings.

Hyphen points the hostname to the App Platform URL with a CNAME record. If you use the zone apex, use a DNS provider that supports CNAME flattening at the apex.

Troubleshoot

  • If Test fails, check the token expiration and the account and registry read permissions.
  • If registry setup finds no registries, create one in the connected team and retry the connection.
  • If the run cannot find a matching image, publish a new build after the DigitalOcean registry connection reaches Ready.
  • If the custom domain stays pending, check that its CNAME points to the App Platform URL.