digitalocean

name	digitalocean
description	[Applies to: **/*] Definitive guidelines for building, deploying, and managing cloud-native applications on DigitalOcean, focusing on secure, scalable, and cost-efficient practices.
source	cursor_mdc

digitalocean Best Practices

This guide outlines the definitive best practices for developing and deploying applications on DigitalOcean. Adhering to these rules ensures your projects are secure, performant, scalable, and maintainable, leveraging DigitalOcean's managed services and cloud-native patterns.

1. VPC-Centric Networking (Security & Simplicity)

ALWAYS isolate your infrastructure within Virtual Private Clouds (VPCs). This is the cornerstone of secure and efficient communication between your services. Connect all compute resources (Droplets, Kubernetes nodes, Functions) and managed services (Databases) within the same VPC.

• Connect Managed Databases via VPC: Use the private connection string and add the VPC's CIDR block as the only trusted source. This drastically reduces the attack surface and simplifies IP management.

  ❌ BAD: Public database connections, individual IP trusted sources.

  -- Public connection string, exposed to the internet
  psql "postgresql://doadmin:[e-mail]:25060/defaultdb?sslmode=require"
  

  ✅ GOOD: Private VPC connection, CIDR block trusted source.

  -- Private connection string, only accessible within the VPC
  psql "postgresql://doadmin:[e-mail]:25060/defaultdb?sslmode=require"
  

  Configuration: In DigitalOcean Control Panel, for your database, add your VPC's CIDR (e.g., 10.108.0.0/20) to Trusted Sources.

• All Compute in VPC: Ensure all Droplets, Kubernetes nodes, and Functions are launched within the same VPC as your managed services.

2. Microservices-First Architecture

Embrace a microservices architecture for agility, scalability, and resilience. DigitalOcean provides excellent platforms for this.

• Managed Kubernetes (DOKS) for Orchestration: For complex, containerized applications requiring fine-grained control and high availability.

• App Platform for Rapid CI/CD: For web apps, APIs, and static sites needing fast, automated deployments with integrated CI/CD. Ideal for AI-assisted development workflows (e.g., with Claude Code).

• Premium CPU-Optimized Droplets: For high-performance, resource-intensive workloads that benefit from dedicated CPU.

  ❌ BAD: Monolithic application on a single Droplet.

  # Dockerfile for a large, multi-service monolith
  FROM node:18-alpine
  WORKDIR /app
  COPY . .
  RUN npm install
  EXPOSE 8080 5432 # Exposing database directly from app container
  CMD ["npm", "start"]
  

  ✅ GOOD: Decoupled services, deployed to appropriate platforms.

  # Dockerfile for a single microservice (e.g., API)
  FROM node:20-alpine AS builder
  WORKDIR /app
  COPY package*.json ./
  RUN npm install --production
  COPY . .
  RUN npm run build # If applicable
  
  FROM node:20-alpine
  WORKDIR /app
  COPY --from=builder /app/node_modules ./node_modules
  COPY --from=builder /app/dist ./dist # Or similar for compiled assets
  EXPOSE 8080
  CMD ["node", "dist/index.js"] # Or your main entry point
  

  Deployment: Deploy the API to App Platform or DOKS, use a Managed PostgreSQL database.

3. Leverage Managed Services

ALWAYS prefer DigitalOcean's managed services over self-hosting when available. They provide automated backups, failover, scaling, and security patching, reducing operational overhead.

• Managed Databases: Use PostgreSQL, MySQL, Redis, or MongoDB.

• Spaces (Object Storage): For static assets, backups, and media files. Integrate with CDN for performance.

• Container Registry: Store private Docker images securely.

• Load Balancers: Distribute traffic and provide SSL termination.

  ❌ BAD: Self-hosting PostgreSQL on a Droplet.

  # Manual setup, no automated failover or backups
  sudo apt update && sudo apt install postgresql postgresql-contrib
  # ... manual configuration, backup scripts, monitoring, etc.
  

  ✅ GOOD: Provision a Managed PostgreSQL Database.

  resource "digitalocean_database_cluster" "primary_db" {
    name       = "my-app-db"
    engine     = "pg"
    version    = "15"
    size       = "db-s-2vcpu-4gb"
    region     = "nyc3"
    node_count = 1 # Start with 1, add standby nodes for HA
    vpc_uuid   = digitalocean_vpc.main.id # Ensure VPC is defined
  }
  

4. Disciplined Container Builds

Follow Docker's best practices to create small, secure, and efficient container images.

• Multi-stage Builds: Separate build-time dependencies from runtime dependencies.

• Minimal Base Images: Use alpine variants or other minimal images.

• Trusted Base Images: Prefer Docker Official Images or Verified Publisher images.

• .dockerignore: Exclude unnecessary files from the build context.

• Rebuild Images Often: Ensure dependencies are up-to-date with security patches.

  ❌ BAD: Single-stage build with development tools, no .dockerignore.

  FROM node:18 # Large base image
  WORKDIR /app
  COPY . . # Copies everything, including .git, node_modules (if present)
  RUN npm install # Installs dev dependencies too
  CMD ["npm", "start"]
  

  ✅ GOOD: Multi-stage build, minimal base, .dockerignore in place.

  # .dockerignore example:
  # node_modules
  # .git
  # .env
  # Dockerfile
  # README.md
  
  # Build stage
  FROM node:20-alpine AS builder
  WORKDIR /app
  COPY package*.json ./
  RUN npm install --omit=dev # Only install production dependencies
  COPY . .
  RUN npm run build # Compile application if needed
  
  # Production stage
  FROM node:20-alpine
  WORKDIR /app
  COPY --from=builder /app/node_modules ./node_modules
  COPY --from=builder /app/dist ./dist # Copy compiled app
  EXPOSE 8080
  CMD ["node", "dist/index.js"]
  

5. Automated Workflows (CI/CD & IaC)

Automate everything possible. This reduces human error, increases deployment speed, and ensures consistency.

• CI/CD Pipelines: Use DigitalOcean App Platform's built-in CI/CD or integrate with GitHub Actions for DOKS deployments.

• Infrastructure as Code (IaC): Manage all DigitalOcean resources with Terraform. This ensures your infrastructure is version-controlled, reproducible, and auditable.

  ❌ BAD: Manual resource creation via Control Panel.

  # Click-ops in the UI
  # Create Droplet -> Add Database -> Configure Load Balancer...
  

  ✅ GOOD: Define infrastructure with Terraform.

  # main.tf
  resource "digitalocean_project" "my_project" {
    name        = "My Awesome Project"
    description = "Infrastructure for my awesome app."
    purpose     = "Web Application"
  }
  
  resource "digitalocean_vpc" "main" {
    name     = "my-app-vpc"
    region   = "nyc3"
    ip_range = "10.10.0.0/20"
  }
  
  resource "digitalocean_kubernetes_cluster" "main_cluster" {
    name    = "my-app-cluster"
    region  = "nyc3"
    version = "1.28.2-do.0"
    vpc_uuid = digitalocean_vpc.main.id
    node_pool {
      name       = "worker-pool"
      size       = "s-2vcpu-4gb"
      node_count = 2
    }
  }
  

6. Performance & Cost Optimization

Continuously monitor and optimize your resources.

• Autoscaling: Implement autoscaling for Droplet pools and Kubernetes node pools to match demand and save costs.

• Load Balancers: Use DigitalOcean Load Balancers to distribute traffic and handle SSL.

• Regular Architecture Reviews: Leverage DigitalOcean's free Solutions Engineer reviews to identify inefficiencies and security gaps.

• Monitor Usage & Set Alerts: Track CPU, memory, disk I/O, network traffic, and billing.

  ❌ BAD: Over-provisioned Droplets running at low utilization.

  # Manually scaled up to a large Droplet "just in case"
  digitalocean droplet create --size s-8vcpu-16gb --image ubuntu-22-04 --region nyc3 --name my-server
  

  ✅ GOOD: Use autoscaling groups or right-sized resources.

  resource "digitalocean_kubernetes_node_pool" "autoscaling_pool" {
    cluster_id = digitalocean_kubernetes_cluster.main_cluster.id
    name       = "autoscaled-workers"
    size       = "s-2vcpu-4gb"
    min_nodes  = 1
    max_nodes  = 5
    auto_scale = true
  }
  

7. Testing & Observability

Integrate testing into your CI/CD and ensure robust monitoring.

• Automated Testing: Include unit, integration, and end-to-end tests in your CI pipeline.

• Staging Environments: Deploy to dedicated staging environments (e.g., via App Platform's branch deployments) before production.

• Logging & Monitoring: Centralize logs and use DigitalOcean Monitoring for metrics and alerts.

  ❌ BAD: Manual testing only, no dedicated staging environment.

  # Deploy directly to production after local testing
  git push origin main # Triggers production deploy
  

  ✅ GOOD: Automated tests, staging environment, and feature branches.

  # .github/workflows/ci-cd.yml (simplified)
  name: CI/CD Pipeline
  
  on:
    push:
      branches:
        - main
        - feature/*
  
  jobs:
    build-and-test:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v3
        - name: Build Docker Image
          run: docker build -t my-app:${{ github.sha }} .
        - name: Run Unit Tests
          run: docker run