Skip to content

DigitalOcean Setup

Jump to bottom
Eric Mann edited this page Dec 13, 2025 · 1 revision

DigitalOcean Setup Guide

This step-by-step guide walks you through setting up DigitalOcean to work with Displace. No prior cloud experience required.

Subscription Required: DigitalOcean provider access requires a paid Displace subscription. Local development is always free.

Why DigitalOcean?

DigitalOcean is the simplest cloud provider to set up. Here's how it compares:

Setup Task DigitalOcean AWS GCP
Authentication 1 API token IAM user + policy + access keys Service account + JSON key + IAM roles
APIs to enable None None 3 APIs
Permissions Full Access scope 50+ IAM permissions 4 IAM roles
Setup time ~5 minutes ~20 minutes ~15 minutes
Control plane Free $0.10/hour (~$72/mo) Free (1 zonal)

If you're new to cloud infrastructure, start here.

What You'll Need

Before starting, you'll need:

  • An email address for your DigitalOcean account
  • A credit card or PayPal for account verification
  • About 5-10 minutes to complete setup

What We're Setting Up

To use Displace with DigitalOcean, you only need:

  1. DigitalOcean Account - Your cloud account
  2. API Token - A single token that authorizes Displace to manage your resources

That's it! No complex IAM policies, no service accounts, no APIs to enable.

Step 1: Create a DigitalOcean Account

If you already have a DigitalOcean account, skip to Step 2.

  1. Go to digitalocean.com

  2. Click Sign Up (top right)

  3. Sign up using:

    • Email and password, or
    • Google account, or
    • GitHub account

  4. Verify your email address

  5. Add a payment method:

    • Credit card, or
    • PayPal

  6. (Optional) Enter a promo code if you have one

What you should see: The DigitalOcean dashboard/control panel

Free Credits: DigitalOcean often provides $200 in free credits for new accounts (valid for 60 days). Check their website for current offers.

Step 2: Generate an API Token

This is the only credential you need. One token does everything.

  1. Log into the DigitalOcean Control Panel

  2. Click API in the left sidebar

  3. In the "Personal access tokens" section, click Generate New Token

  4. Configure your token:

    • Token name: displace-cli (or any descriptive name)
    • Expiration: Choose based on your needs:
      • No expiry - Convenient for personal projects
      • 90 days or 1 year - More secure, requires renewal
    • Scopes: Select Full Access (both Read and Write)

  5. Click Generate Token

  6. IMPORTANT: Copy the token immediately!

    • The token is only shown once
    • It looks like: dop_v1_abc123def456... (64 characters)
    • Store it somewhere secure

What you should see: Your new token listed under "Personal access tokens"

Security Warning: This token can manage all your DigitalOcean resources.

  • Never share it publicly
  • Never commit it to git
  • Store it securely (password manager recommended)
  • You can revoke it anytime if compromised

Step 3: Configure Displace

Now connect Displace to your DigitalOcean account.

  1. Open your terminal

  2. Run the configuration command:

    displace provider digitalocean configure

    Or use the shorter alias:

    displace provider do configure

  3. When prompted:

    • API Token: Paste your token from Step 2
    • Default Region: Enter a region code (see region table below)

What you should see:

✅ DigitalOcean provider configured successfully
   Region: nyc3

Recommended Regions

Choose a region close to your users:

Region Code Location Recommended For
nyc3 New York US East Coast
sfo3 San Francisco US West Coast
tor1 Toronto Canada
lon1 London UK/Western Europe
ams3 Amsterdam Europe
fra1 Frankfurt Central Europe
sgp1 Singapore Southeast Asia
blr1 Bangalore India
syd1 Sydney Australia/Oceania

Tip: nyc3 and sfo3 are the most reliable regions with full Kubernetes support.

Step 4: Test Your Configuration

Verify everything is working:

# Test the provider connection
displace provider test digitalocean

What you should see:

✅ DigitalOcean provider test successful
   - Token valid
   - API accessible
   - Region available

Step 5: Create Your First Cluster

You're ready to create a Kubernetes cluster!

# Create a cluster named "my-cluster"
displace cluster create my-cluster --provider digitalocean

Or using the short alias:

displace cluster create my-cluster --provider do

This will:

  1. Create a DOKS (DigitalOcean Kubernetes) cluster
  2. Provision worker nodes
  3. Configure kubectl to connect
  4. Install monitoring and ingress components

Wait time: DOKS cluster creation takes 4-8 minutes.

What you should see:

Creating cluster 'my-cluster' on DigitalOcean...
✅ DOKS cluster created
✅ Node pool ready (1 node)
✅ Kubectl configured
✅ Monitoring installed
✅ Ingress controller installed

Cluster 'my-cluster' is ready!

Understanding DigitalOcean Costs

DigitalOcean has simple, predictable pricing.

The Good News

DOKS control plane is FREE! You only pay for worker nodes.

Compare to other providers:

Provider Control Plane Cost
DigitalOcean Free
AWS EKS $0.10/hour (~$72/month)
GCP GKE Free (1 zonal cluster)

Worker Node Pricing

Node Size vCPUs RAM Monthly Cost
s-1vcpu-2gb 1 2GB $12
s-2vcpu-4gb 2 4GB $24
s-4vcpu-8gb 4 8GB $48
s-8vcpu-16gb 8 16GB $96

Minimum Viable Cluster

For development and testing:

  • 1 node (s-2vcpu-4gb): $24/month
  • Add load balancer if needed: +$12/month

Additional Costs

Resource Cost
Load Balancer $12/month
Block Storage $0.10/GB/month
Snapshots $0.06/GB/month
Bandwidth 1TB free, then $0.01/GB

Cost-Saving Tips

  1. Destroy clusters when not in use:

    displace cluster destroy my-cluster

  2. Use smaller nodes for development:

    displace cluster create dev --provider do --node-type s-1vcpu-2gb

  3. Start with one node:

    displace cluster create dev --provider do --node-count 1

  4. Monitor your spending: DigitalOcean dashboard shows real-time billing

Common Workflows

Deploy a WordPress Site

# Create cluster
displace cluster create blog-cluster --provider do

# Initialize WordPress project
mkdir my-blog && cd my-blog
displace project init wordpress

# Deploy
displace project deploy --cluster blog-cluster

# Get site URL
displace project info

Deploy a Static Site

# Create cluster
displace cluster create web-cluster --provider do

# Initialize static site project
mkdir my-site && cd my-site
displace project init static

# Deploy
displace project deploy --cluster web-cluster

Scale Your Cluster

# Check current status
displace cluster status my-cluster --provider do

# Autoscaling is enabled by default (1-3 nodes)
# Kubernetes will automatically scale based on demand

Troubleshooting

"Unable to authenticate" or "401 Unauthorized"

Cause: Invalid or expired API token.

Solution:

  1. Verify you copied the full token (no spaces)
  2. Check the token hasn't expired in DO console
  3. Generate a new token if needed: 
    displace provider do configure  # Enter new token

"Region not available for Kubernetes"

Cause: Some older regions don't support DOKS.

Solution: Use one of these confirmed DOKS regions:

  • nyc3, sfo3, ams3, sgp1, lon1, fra1, tor1, blr1, syd1

"Droplet limit exceeded"

Cause: New accounts have resource limits.

Solution:

  1. Go to DigitalOcean Console > Settings > Team
  2. Click "Request Limit Increase"
  3. Or add a valid payment method to increase limits

"Insufficient balance"

Cause: Account needs payment method or has exhausted credits.

Solution:

  1. Add a credit card or PayPal to your account
  2. Check if free trial credits have expired

Cluster creation taking too long

Cause: DOKS provisioning can take 4-8 minutes (this is normal).

Solution:

  1. Wait up to 10 minutes
  2. Check status in DigitalOcean Console > Kubernetes
  3. Check for any error notifications

"Token doesn't have required scopes"

Cause: Token created with Read-only access.

Solution:

  1. Go to API > Tokens in DO Console
  2. Generate a new token with Full Access
  3. Reconfigure: 
    displace provider do configure

Security Best Practices

  1. Use descriptive token names

    • Name tokens by purpose: displace-production, displace-testing
    • Makes it easy to identify and revoke if needed

  2. Set token expiration for production

    • Use 90-day or 1-year expiration
    • Set calendar reminders to rotate tokens

  3. One token per environment

    • Different tokens for dev, staging, production
    • Limits blast radius if compromised

  4. Revoke unused tokens

    • Regularly audit tokens in DO Console
    • Delete any you're not using

  5. Never commit tokens

    • Add .credentials to .gitignore
    • Use environment variables in CI/CD

Managing Your Token

View Active Tokens

  1. Go to DigitalOcean API Tokens
  2. See all your active tokens

Revoke a Token

  1. Go to API > Tokens
  2. Click the ... menu next to the token
  3. Click Revoke
  4. Confirm revocation

Note: Revoking a token immediately invalidates it. Displace will stop working until you configure a new token.

Rotate a Token

  1. Generate a new token (Step 2 above)
  2. Configure Displace with the new token: 
    displace provider do configure
  3. Revoke the old token

Cleaning Up

When you're done testing or want to remove resources:

Delete a Cluster

displace cluster destroy my-cluster --provider do

This removes:

  • The DOKS cluster
  • All worker nodes
  • Associated load balancers
  • Network resources

View Resources in Console

Check what's running:

  1. Go to DigitalOcean Kubernetes
  2. See all clusters and their status
  3. View nodes, workloads, and costs

Delete Everything

To remove all Displace-managed resources:

# List all clusters
displace cluster list

# Destroy each cluster
displace cluster destroy cluster-name --provider do

Quick Reference

Commands

# Configure DigitalOcean provider
displace provider digitalocean configure
displace provider do configure  # Short alias

# Test configuration
displace provider test digitalocean
displace provider test do

# Create cluster
displace cluster create my-cluster --provider digitalocean
displace cluster create my-cluster --provider do

# Check cluster status
displace cluster status my-cluster --provider do

# List all clusters
displace cluster list

# Destroy cluster
displace cluster destroy my-cluster --provider do

Common Node Types

Size Slug Specs Best For
s-1vcpu-2gb 1 vCPU, 2GB Testing, small apps
s-2vcpu-4gb 2 vCPU, 4GB Development, WordPress
s-4vcpu-8gb 4 vCPU, 8GB Production workloads

Region Codes

  • Americas: nyc3, sfo3, tor1
  • Europe: lon1, ams3, fra1
  • Asia-Pacific: sgp1, blr1, syd1

Comparison: DigitalOcean vs Other Providers

Feature DigitalOcean AWS GCP
Setup complexity Very Easy Complex Medium
Control plane cost Free $72/month Free
Min. node cost $12/month ~$50/month ~$25/month
Best for Beginners, small teams Enterprise, complex needs Data/ML workloads
Learning curve Low High Medium

Recommendation: Start with DigitalOcean to learn, then consider AWS/GCP for specific enterprise needs.

Useful Links

Related Documentation:

Home

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally