DigitalOcean

Deploy Hyperterse on DigitalOcean using App Platform (recommended for simplicity) or Droplets (for more control). App Platform provides automatic scaling, SSL, and zero-downtime deployments.

These instructions are a work in progress. Please report any issues or suggestions to the GitHub repository.

App Platform Recommended

DigitalOcean App Platform is the simplest way to deploy Hyperterse. It handles container orchestration, SSL certificates, and scaling automatically.

1. Export your Hyperterse bundle

   Create a deployment-ready bundle from your configuration:

   hyperterse export -f config.terse -o dist

   This creates a self-contained script in the dist/ directory. The script name matches your config file name (without the .terse extension).

2. Create a Dockerfile

   Create a Dockerfile in your project root:

   Dockerfile

   FROM alpine:3.19
   
   # Install bash and ca-certificates for HTTPS database connections
   RUN apk --no-cache add bash ca-certificates
   
   WORKDIR /app
   
   # Copy the exported script (replace 'config' with your actual script name)
   COPY dist/config /app/config
   
   # Make script executable
   RUN chmod +x /app/config
   
   EXPOSE 8080
   
   # Run the script
   CMD ["/app/config"]

   Note: Replace config with the actual name of your exported script (it matches your config filename without the .terse extension).

3. Push to GitHub

   Commit and push your code to a GitHub repository:

   git add Dockerfile dist/
   git commit -m "Add Hyperterse deployment"
   git push origin main

   Ensure your repository is public or connected to DigitalOcean.

4. Create App Platform app

   • Go to DigitalOcean Apps
   • Click “Create App”
   • Select “GitHub” as the source
   • Authorize DigitalOcean to access your GitHub account if needed
   • Select your repository and branch

5. Configure the app

   DigitalOcean will auto-detect your Dockerfile. Configure:

   • Component name: hyperterse (or your preferred name)
   • HTTP Port: 8080
   • HTTP Request Routes: / (default)

6. Add environment variables

   In the app configuration:

   • Go to “Environment Variables” section
   • Add DATABASE_URL with your database connection string
   • Mark it as “Encrypted” for security

   Security best practice: Never commit credentials to Git. Always use environment variables.

7. Deploy

   Click “Create Resources” to deploy your app. DigitalOcean will:

   • Build your Docker image
   • Deploy containers
   • Provision SSL certificates automatically
   • Provide a public URL

   Your Hyperterse API will be available at:

   https://<app-name>.ondigitalocean.app

Managed Database integration

Connect Hyperterse to DigitalOcean Managed Databases:

1. Create managed database

   • Go to Databases → Create Database
   • Choose PostgreSQL or MySQL
   • Select a region close to your App Platform app
   • Choose a plan (Basic is fine for development)

2. Get connection string

   Once the database is created:

   • Go to the database dashboard
   • Copy the connection string from “Connection Details”
   • Format: postgresql://user:password@host:port/database

3. Configure database firewall

   • Go to database settings → “Trusted Sources”
   • Add your App Platform app as a trusted source
   • Or add your Droplet’s IP if using Droplets

4. Update environment variable

   Update the DATABASE_URL environment variable in your App Platform app with the managed database connection string.

Droplet deployment

For more control, deploy Hyperterse directly on a DigitalOcean Droplet:

1. Create a Droplet

   • Go to Droplets → Create Droplet
   • Choose Ubuntu 22.04 LTS or your preferred OS
   • Select a size (Basic plan with 1GB RAM is sufficient for small deployments)
   • Add your SSH key for secure access

2. Export bundle

   hyperterse export -f config.terse -o dist

3. Transfer to Droplet

   scp -r dist/ root@your-droplet-ip:/opt/hyperterse/

4. SSH into Droplet

   ssh root@your-droplet-ip

5. Set up the service

   Follow the bare metal deployment guide to set up a systemd service or use PM2.

Container Registry

Use DigitalOcean Container Registry to store your Docker images:

1. Create registry

   • Go to Container Registry → Create Registry
   • Choose a name and region

2. Authenticate Docker

   doctl registry login

   Or manually:

   docker login registry.digitalocean.com -u <token> -p <token>

3. Build and push image

   # Build image
   docker build -t registry.digitalocean.com/your-registry/hyperterse:latest .
   
   # Push to registry
   docker push registry.digitalocean.com/your-registry/hyperterse:latest

4. Use in App Platform

   When creating an App Platform app, select “Container Registry” as the source and choose your image.

Load balancer

App Platform includes automatic load balancing. For Droplet deployments:

1. Create Load Balancer

   • Go to Networking → Load Balancers → Create Load Balancer
   • Choose HTTP/HTTPS forwarding
   • Select your Droplets as backend servers

2. Configure health checks

   • Health check path: /heartbeat
   • Health check protocol: HTTP
   • Health check port: 8080

3. Add SSL certificate

   • Use Let’s Encrypt (free) or upload your own certificate
   • Configure HTTPS redirect

Scaling

App Platform scaling:

• Go to your app → Settings → Components
• Adjust instance count (horizontal scaling)
• Configure auto-scaling rules based on CPU/memory usage
• Set minimum and maximum instances

Droplet scaling:

• Create multiple Droplets with the same configuration
• Add all Droplets to a Load Balancer
• Use DigitalOcean’s monitoring to determine when to scale

Monitoring and logs

App Platform:

• View logs in real-time: App → Runtime Logs
• Set up alerts: App → Alerts
• Monitor metrics: App → Insights

Droplets:

• Use DigitalOcean Monitoring (enabled by default)
• View logs via SSH: journalctl -u hyperterse -f
• Set up alerts in the dashboard

Troubleshooting

App won’t deploy: Check build logs in App Platform. Common issues include incorrect Dockerfile paths or missing files.

Can’t connect to database: Verify firewall rules allow App Platform IPs, and that the connection string is correct.

High costs: Review your resource usage and consider downsizing or using Droplets for predictable workloads.