Digital Ocean

Deploy Convox on Digital Ocean using Digital Ocean Kubernetes Service (DOKS) for a developer-friendly, cost-effective Kubernetes platform.

The easiest way to install a Rack is with the Convox Web Console. These instructions are for command-line installation.

Prerequisites

Before installing Convox on Digital Ocean, ensure you have the following tools installed:

Install Terraform

Convox uses Terraform to provision Digital Ocean infrastructure.

# macOS
brew tap hashicorp/tap
brew install hashicorp/tap/terraform

# Linux
wget https://releases.hashicorp.com/terraform/1.6.0/terraform_1.6.0_linux_amd64.zip
unzip terraform_1.6.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/

# Verify installation
terraform --version

Terraform Installation Guide

Install Convox CLI

Install the Convox CLI to manage your racks and applications.

# macOS
curl -L https://github.com/convox/convox/releases/latest/download/convox-macos -o /tmp/convox

# Linux
curl -L https://github.com/convox/convox/releases/latest/download/convox-linux -o /tmp/convox

sudo mv /tmp/convox /usr/local/bin/convox
sudo chmod 755 /usr/local/bin/convox

# Verify installation
convox --version

Convox CLI Documentation

Digital Ocean API Configuration

Convox requires Digital Ocean API credentials to provision infrastructure.

Required Environment Variables

DIGITALOCEAN_TOKEN

string

required

Personal Access Token for Digital Ocean API

DIGITALOCEAN_ACCESS_ID

string

required

Spaces Access Key ID for object storage

DIGITALOCEAN_SECRET_KEY

string

required

Spaces Secret Key for object storage

Create Digital Ocean Tokens

Create Personal Access Token

Log into Digital Ocean Control Panel
Navigate to API Tokens
Click Generate New Token
Name: convox
Scopes: Select Read and Write
Click Generate Token

Copy the token immediately - it won’t be shown again!

export DIGITALOCEAN_TOKEN="dop_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Create Spaces Access Key

Digital Ocean Spaces (S3-compatible storage) is used for build artifacts.

Navigate to API → Spaces Keys
Scroll to Spaces access keys section
Click Generate New Key
Name: convox
Click Create

You’ll receive:

Key → Use as DIGITALOCEAN_ACCESS_ID
Secret → Use as DIGITALOCEAN_SECRET_KEY

export DIGITALOCEAN_ACCESS_ID="your-spaces-access-key"
export DIGITALOCEAN_SECRET_KEY="your-spaces-secret-key"

Verify Credentials

echo "Token: $DIGITALOCEAN_TOKEN"
echo "Access ID: $DIGITALOCEAN_ACCESS_ID"
echo "Secret Key: $DIGITALOCEAN_SECRET_KEY"

Ensure all three variables are set before proceeding.

Store your credentials securely. Never commit them to version control.

Installation

Install a Convox Rack on Digital Ocean using the CLI:

convox rack install do <rack-name> [param1=value1] [param2=value2]...

Basic Installation

# Install with default settings
convox rack install do production

# Install in specific region
convox rack install do production region=sfo3

# Install with custom node type
convox rack install do production region=nyc3 node_type=s-2vcpu-4gb

Installation Examples

# Cost-optimized development rack
convox rack install do dev \
  region=nyc3 \
  node_type=s-2vcpu-2gb

Configuration Parameters

Convox on Digital Ocean supports the following configuration parameters:

Region Configuration

region

string

default:"nyc3"

Digital Ocean region where the rack will be deployedAvailable Regions:North America:

nyc1 - New York City 1
nyc3 - New York City 3 (default)
sfo3 - San Francisco 3
tor1 - Toronto 1

Europe:

lon1 - London 1
fra1 - Frankfurt 1
ams3 - Amsterdam 3

Asia:

sgp1 - Singapore 1
blr1 - Bangalore 1

convox rack install do mystack region=sfo3

Choose a region close to your users for lower latency.

View all Digital Ocean regions

Node Configuration

node_type

string

default:"s-2vcpu-4gb"

Digital Ocean droplet size for Kubernetes nodesStandard Droplets (General Purpose):

s-1vcpu-1gb - 1 vCPU, 1 GB RAM, 25 GB SSD
s-1vcpu-2gb - 1 vCPU, 2 GB RAM, 50 GB SSD
s-2vcpu-2gb - 2 vCPU, 2 GB RAM, 60 GB SSD
s-2vcpu-4gb - 2 vCPU, 4 GB RAM, 80 GB SSD (default)
s-4vcpu-8gb - 4 vCPU, 8 GB RAM, 160 GB SSD
s-8vcpu-16gb - 8 vCPU, 16 GB RAM, 320 GB SSD

CPU-Optimized Droplets:

c-2 - 2 vCPU, 4 GB RAM
c-4 - 4 vCPU, 8 GB RAM
c-8 - 8 vCPU, 16 GB RAM
c-16 - 16 vCPU, 32 GB RAM

Memory-Optimized Droplets:

m-2vcpu-16gb - 2 vCPU, 16 GB RAM
m-4vcpu-32gb - 4 vCPU, 32 GB RAM
m-8vcpu-64gb - 8 vCPU, 64 GB RAM

General Purpose Droplets:

g-2vcpu-8gb - 2 vCPU, 8 GB RAM
g-4vcpu-16gb - 4 vCPU, 16 GB RAM
g-8vcpu-32gb - 8 vCPU, 32 GB RAM

convox rack install do mystack node_type=s-4vcpu-8gb

View all droplet sizes

Registry Configuration

registry_disk

string

default:"50Gi"

Persistent disk size for the Docker registryDigital Ocean uses an in-cluster registry for Docker images. This parameter sets the volume size for image storage.Recommended Sizes:

50Gi - Small projects, few applications (default)
100Gi - Medium projects, multiple applications
250Gi - Large projects, many images
500Gi - Very large deployments

convox rack install do mystack registry_disk=100Gi

The registry stores all Docker images for your applications. Size appropriately based on the number and size of your container images.

SSL/TLS Configuration

cert_duration

string

default:"2160h"

Certificate renewal period (90 days by default)Convox automatically manages TLS certificates using Let’s Encrypt.Duration Format:

720h - 30 days
2160h - 90 days (recommended, default)
4320h - 180 days

convox rack install do mystack cert_duration=2160h

Logging Configuration

syslog

string

Forward logs to an external syslog endpointSupported Protocols:

tcp+tls://hostname:port - TLS-encrypted TCP (recommended)
tcp://hostname:port - Unencrypted TCP
udp://hostname:port - UDP

Popular Services:

Papertrail: tcp+tls://logsN.papertrailapp.com:XXXXX
Loggly: tcp+tls://logs-01.loggly.com:6514
Splunk: tcp+tls://input.splunk.com:514

convox rack install do mystack syslog=tcp+tls://logs.papertrailapp.com:12345

Infrastructure Components

When you install Convox on Digital Ocean, Terraform provisions:

Compute

DOKS Cluster (Kubernetes control plane)
Node Pool with auto-scaling droplets
Load Balancer for ingress traffic

Storage

Spaces Bucket (S3-compatible) for build artifacts
Volume for Docker registry
Block Storage for persistent volumes

Networking

VPC for cluster isolation
Firewall Rules for security
Load Balancer with automatic SSL

Registry

In-cluster Docker Registry for container images
Persistent Volume for image storage

Cost Optimization

Start Small

convox rack install do dev \
  node_type=s-2vcpu-2gb

Begin with smaller droplets ($18/month) and scale up as needed

Right-Size Registry

convox rack install do production \
  registry_disk=50Gi

Start with default 50Gi and increase only when needed

Regional Pricing

All Digital Ocean regions have the same pricing, so choose based on proximity to users rather than cost

Kubernetes Auto-Scaling

DOKS automatically scales your node pool based on demand, so you only pay for what you use

Pricing Examples

Development Rack:

2x s-2vcpu-2gb nodes: $18/month each =$ 36/month
Load Balancer: $12/month
Registry Volume (50Gi): ~$5/month
Total: ~$53/month

Production Rack:

3x s-4vcpu-8gb nodes: $72/month each =$ 216/month
Load Balancer: $12/month
Registry Volume (100Gi): ~$10/month
Total: ~$238/month

Production Best Practices

Use Appropriate Node Sizes

convox rack install do production \
  node_type=s-4vcpu-8gb

For production workloads:

General apps: s-4vcpu-8gb or g-4vcpu-16gb
CPU-intensive: c-4 or c-8
Memory-intensive: m-4vcpu-32gb

Size Registry Appropriately

convox rack install do production \
  registry_disk=100Gi

Allocate sufficient storage for your Docker images. Monitor usage and expand as needed.

Enable Log Forwarding

convox rack install do production \
  syslog=tcp+tls://logs.papertrailapp.com:12345

Forward logs to external services for long-term retention and analysis.

Select Optimal Region

convox rack install do production \
  region=nyc3

Choose region based on:

Proximity to your users (latency)
Your team’s location
Compliance requirements

Configure Monitoring

After installation, set up monitoring:

Digital Ocean Monitoring (built-in)
External APM tools (Datadog, New Relic)
Application-level metrics

Updating Rack Parameters

After installation, you can update rack parameters:

# View current parameters
convox rack params -r production

# Update node type (requires node recreation)
convox rack params set node_type=s-4vcpu-8gb -r production

# Update registry disk size
convox rack params set registry_disk=100Gi -r production

# Update multiple parameters
convox rack params set node_type=s-4vcpu-8gb registry_disk=100Gi -r production

Changing node types requires recreating the node pool, which may cause temporary service disruption. Plan accordingly.

Troubleshooting

Installation Issues

Invalid API token

Error: Authentication failed or 401 UnauthorizedSolution:

Verify token is correctly copied (no extra spaces)
Check token has both Read and Write scopes
Ensure token hasn’t been revoked
Generate a new token if needed

echo "Token: $DIGITALOCEAN_TOKEN"

Spaces key issues

Error: Failed to create spaces bucket or S3 errorsSolution:

Verify Spaces keys are correct:

echo "Access ID: $DIGITALOCEAN_ACCESS_ID"
echo "Secret Key: $DIGITALOCEAN_SECRET_KEY"

Generate new Spaces access keys if needed
Ensure keys have write permissions

Resource quota exceeded

Error: Droplet limit exceeded or similarSolution: Digital Ocean has default limits on resources:

Check your account limits in Digital Ocean Control Panel
Request limit increase via support ticket
Or use smaller/fewer droplets

Region not available

Error: Region [xxx] does not support KubernetesSolution: Not all DO regions support DOKS. Use one of the supported regions:

nyc1, nyc3
sfo3
sgp1
lon1
fra1
ams3
tor1
blr1

Runtime Issues

Node pool not scaling

Issue: Cluster not adding nodes under loadSolution:

Check droplet limits in your account
Verify auto-scaling is enabled in Digital Ocean Control Panel
Review DOKS cluster events for errors

Registry disk full

Issue: No space left on device errors during buildsSolution: Increase registry disk size:

convox rack params set registry_disk=100Gi -r production

Or clean up old images:

convox builds -a myapp
convox builds delete <old-build-id> -a myapp

Load balancer not responding

Issue: Cannot access applicationsSolution:

Check firewall rules in Digital Ocean Control Panel
Verify load balancer health checks are passing
Check application logs:
```
convox logs -a myapp
```
Verify DNS is pointing to load balancer IP

Digital Ocean Regions

Available DOKS regions:

North America

NYC1 - New York City 1
NYC3 - New York City 3 (popular)
SFO3 - San Francisco 3 (popular)
TOR1 - Toronto 1

Europe

LON1 - London 1
FRA1 - Frankfurt 1 (popular)
AMS3 - Amsterdam 3

Asia Pacific

SGP1 - Singapore 1
BLR1 - Bangalore 1

All regions have identical pricing. Choose based on proximity to users for best performance.

Check latest region availability

Comparison with Other Providers

Simplicity

Digital Ocean offers the simplest setup with minimal configuration options

Cost

Very competitive pricing, especially for small to medium workloads

Features

Fewer advanced features than AWS/GCP/Azure, but covers most common use cases

When to Choose Digital Ocean

✅ Good for:

Small to medium applications
Startups and development teams
Cost-conscious deployments
Simpler infrastructure needs
Quick setup and deployment

❌ Consider alternatives if you need:

Advanced networking (VPN, Direct Connect)
Extensive compliance certifications
GPU/specialized compute
Global presence (limited regions)
Advanced managed services

Next Steps

Deploy an Application

Learn how to deploy your first application to your new rack

Configure Resources

Set up databases, Redis, and other resources

Custom Domains

Configure custom domains and SSL certificates

Rack Management

Learn how to manage and update your rack

Additional Resources

Digital Ocean Kubernetes Documentation
Digital Ocean Spaces
Convox Troubleshooting - Common issues and solutions
Community Forum - Get help from the community

Getting Started

Installation

Cloud Providers

Configuration

Deployment

Management

​Digital Ocean

​Prerequisites

​Digital Ocean API Configuration

​Required Environment Variables

​Create Digital Ocean Tokens

​Installation

​Basic Installation

​Installation Examples

​Configuration Parameters

​Region Configuration

​Node Configuration

​Registry Configuration

​SSL/TLS Configuration

​Logging Configuration

​Infrastructure Components

​Compute

​Storage

​Networking

​Registry

​Cost Optimization

Start Small

Right-Size Registry

Regional Pricing

Kubernetes Auto-Scaling

​Pricing Examples

​Production Best Practices

​Updating Rack Parameters

​Troubleshooting

​Installation Issues

​Runtime Issues

​Digital Ocean Regions

​North America

​Europe

​Asia Pacific

​Comparison with Other Providers

Simplicity

Cost

Features

​When to Choose Digital Ocean

​Next Steps

Deploy an Application

Configure Resources

Custom Domains

Rack Management

​Additional Resources

Build docs developers (and LLMs) love

Digital Ocean

Prerequisites

Digital Ocean API Configuration

Required Environment Variables

Create Digital Ocean Tokens

Installation

Basic Installation

Installation Examples

Configuration Parameters

Region Configuration

Node Configuration

Registry Configuration

SSL/TLS Configuration

Logging Configuration

Infrastructure Components

Compute

Storage

Networking

Registry

Cost Optimization

Pricing Examples

Production Best Practices

Updating Rack Parameters

Troubleshooting

Installation Issues

Runtime Issues

Digital Ocean Regions

North America

Europe

Asia Pacific

Comparison with Other Providers

When to Choose Digital Ocean

Next Steps

Additional Resources