How to Integrate DigitalOcean with Astro: Complete Guide

DigitalOcean provides cloud infrastructure for deploying web applications, with options ranging from managed app hosting to custom servers. For Astro projects, DigitalOcean offers two main deployment paths: App Platform for managed deployments with automatic builds, and Droplets for full control over your server environment. Both support static Astro sites and server-rendered applications.

This guide covers deploying Astro to DigitalOcean App Platform (the managed approach) and setting up a Droplet with Node.js for SSR Astro projects.

Prerequisites

Before starting, you will need:

• Node.js 18+ installed locally
• An existing Astro project in a Git repository (GitHub, GitLab, or Bitbucket)
• A DigitalOcean account (new accounts get $200 free credit)
• doctl CLI installed (optional but helpful): brew install doctl

Installation

For Static Sites

No additional packages needed. Astro builds static sites by default.

For SSR Sites

Install the Node.js adapter:

npx astro add node

Configure your astro.config.mjs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

Configuration

Method 1: App Platform (Recommended)

DigitalOcean App Platform is a managed PaaS that builds and deploys your app from a Git repository. It handles SSL, CDN, and scaling automatically.

Step 1: Create App Spec

Create an .do/app.yaml file in your project root. For a static Astro site:

# .do/app.yaml
name: my-astro-site
static_sites:
  - name: web
    github:
      repo: your-username/your-repo
      branch: main
    build_command: npm run build
    output_dir: dist
    environment_slug: node-js
    envs:
      - key: NODE_ENV
        value: production

For an SSR Astro site:

# .do/app.yaml
name: my-astro-app
services:
  - name: web
    github:
      repo: your-username/your-repo
      branch: main
    build_command: npm run build
    run_command: node dist/server/entry.mjs
    environment_slug: node-js
    http_port: 4321
    instance_size_slug: basic-xxs
    instance_count: 1
    envs:
      - key: HOST
        value: "0.0.0.0"
      - key: PORT
        value: "4321"
      - key: NODE_ENV
        value: production

Step 2: Deploy via Dashboard

1. Go to DigitalOcean Dashboard > Apps > Create App
2. Connect your GitHub/GitLab repository
3. Select the branch to deploy from
4. DigitalOcean auto-detects the framework and suggests build settings
5. Adjust the build command to npm run build and output directory to dist
6. Choose your plan and region
7. Click Deploy

Step 3: Deploy via CLI

Alternatively, deploy using the doctl CLI:

doctl auth init
doctl apps create --spec .do/app.yaml

Method 2: Droplet Deployment

For full server control, deploy Astro to a DigitalOcean Droplet.

Step 1: Create the Droplet

doctl compute droplet create astro-server \
  --image ubuntu-22-04-x64 \
  --size s-1vcpu-1gb \
  --region nyc1 \
  --ssh-keys YOUR_SSH_KEY_FINGERPRINT

Step 2: Server Setup

SSH into your Droplet and install Node.js:

ssh root@your-droplet-ip

# Install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

# Install PM2 for process management
npm install -g pm2

# Install Nginx as reverse proxy
apt update && apt install -y nginx

Step 3: Deploy Your Astro App

# Clone your repository
git clone https://github.com/your-username/your-repo.git /var/www/astro-app
cd /var/www/astro-app

# Install dependencies and build
npm install
npm run build

# Start with PM2
pm2 start dist/server/entry.mjs --name astro-app
pm2 save
pm2 startup

Step 4: Configure Nginx

# /etc/nginx/sites-available/astro-app
server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    location / {
        proxy_pass http://localhost:4321;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the site and add SSL:

ln -s /etc/nginx/sites-available/astro-app /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

# Add SSL with Let's Encrypt
apt install -y certbot python3-certbot-nginx
certbot --nginx -d yourdomain.com -d www.yourdomain.com

Common Patterns

Environment Variables on App Platform

Add environment variables through the DigitalOcean dashboard or the app spec:

envs:
  - key: DATABASE_URL
    value: "postgresql://user:pass@host:5432/db"
    type: SECRET
  - key: PUBLIC_SITE_URL
    value: "https://yourdomain.com"

Variables marked as SECRET are encrypted and hidden in the dashboard.

Connecting to Managed Database

DigitalOcean offers managed PostgreSQL, MySQL, and Redis. Connect your Astro app to a managed database:

# In app.yaml
databases:
  - name: db
    engine: PG
    version: "16"
    size: db-s-1vcpu-1gb
    num_nodes: 1

Reference the database connection string with ${db.DATABASE_URL} in your app's environment variables.

Auto-Deploy on Push

App Platform automatically deploys when you push to the configured branch. For more control, disable auto-deploy and use the CLI or API:

# Trigger manual deployment
doctl apps create-deployment YOUR_APP_ID

Custom Domain Setup

In the DigitalOcean dashboard, go to your app's Settings > Domains. Add your custom domain and point your DNS to DigitalOcean's nameservers or add the provided CNAME record.

# If using DigitalOcean DNS
doctl compute domain create yourdomain.com
doctl compute domain records create yourdomain.com \
  --record-type CNAME \
  --record-name www \
  --record-data your-app.ondigitalocean.app.

Troubleshooting

Build fails on App Platform: Check the build logs in the DigitalOcean dashboard. Common issues include missing environment variables during build time, Node.js version mismatches, or memory limits on the smallest instance size. Upgrade to a larger instance if builds run out of memory.

"Cannot find module" error on SSR deployment: Make sure your package.json lists all runtime dependencies under dependencies, not devDependencies. App Platform runs npm install --production by default, which skips dev dependencies.

Port binding error: App Platform expects your app to listen on the port specified in the http_port config. Make sure your Astro Node adapter uses HOST=0.0.0.0 and the correct port. The standalone mode defaults to localhost:4321.

Static site returning 404 on routes: For static sites with client-side routing, add a catch-all route configuration. In App Platform, create a catchall_document in your spec pointing to index.html, or configure your Astro project to generate all routes at build time.

SSL certificate not working on Droplet: Certbot may fail if your DNS has not propagated yet. Verify your domain points to the Droplet's IP address with dig yourdomain.com. Also make sure ports 80 and 443 are open in your firewall: ufw allow 80 && ufw allow 443.

High memory usage on Droplet: Node.js can consume significant memory for SSR. Set a memory limit with PM2: pm2 start dist/server/entry.mjs --max-memory-restart 512M. For static sites, serve the dist directory directly with Nginx instead of running Node.js.

Conclusion

DigitalOcean gives you flexibility in how you deploy Astro. App Platform provides the simplest path with managed builds, auto-deploy, and SSL included. Droplets offer full control when you need custom server configurations, additional services, or tighter cost management. For most Astro projects, start with App Platform for simplicity. Move to a Droplet when you need more control over the server environment or want to run multiple services alongside your Astro application. Static sites can use the free tier on App Platform, making it a cost-effective choice for blogs and marketing sites.