WebSocket Server Deployment Strategy

This document outlines our branching strategy and deployment workflow for the WebSocket server on Digital Ocean App Platform. We use separate branches to manage each environment, allowing independent deployments decoupled from our Vercel frontend.

Branch Strategy

We maintain three parallel branches for our websocket server:

This separation allows us to:

• Deploy websocket server changes independently from the main application
• Test new websocket functionality without affecting production
• Roll back server changes without disrupting the frontend

Deployment Architecture

Each branch is configured to deploy to a separate Digital Ocean App Platform application:

GitHub                  Digital Ocean              Vercel Frontend
---------               ------------               ---------------
server-main  ------->  Production Server   <--->  Production (main)
                        imagineo-websocket-production

server-development --> Staging Server      <--->  Staging (development)
                        imagineo-websocket-staging

server-beta  -------->  Beta Server        <--->  Beta (beta)
                        imagineo-websocket-beta

Configuration Files

We use Digital Ocean App Spec files to define the deployment configuration for each environment:

• app.production.yaml - Production environment (server-main)
• app.development.yaml - Staging environment (server-development)
• app.beta.yaml - Beta environment (server-beta)

Common Configuration Pattern

Each environment follows this common pattern:

name: imagineo-websocket-[environment]
services:
- build_command: |
    curl -fsSL https://bun.sh/install | bash
    export PATH=$HOME/.bun/bin:$PATH
    cd websocket-server || exit 1
    echo "Installing dependencies..."
    bun install || exit 1
    echo "Building application..."
    bun run build || exit 1
    cd ..
  environment_slug: node-js
  github:
    branch: server-[environment]
    deploy_on_push: true
    repo: baudevs/app.imagineoai.com
  http_port: 8080
  instance_count: 1
  instance_size_slug: apps-s-1vcpu-0.5gb
  name: app-imagineoai-com
  run_command: |
    curl -fsSL https://bun.sh/install | bash
    export PATH=$HOME/.bun/bin:$PATH
    cd websocket-server || exit 1
    echo "Starting application..."
    bun src/server.ts
  source_dir: /

Environment Variables

Each environment requires these environment variables:

Deployment Workflow

Initial Setup

1. Create each branch from the corresponding main branch:

# Create server-main from main
git checkout main
git checkout -b server-main
git push -u origin server-main
 
# Create server-development from development
git checkout development
git checkout -b server-development
git push -u origin server-development
 
# Create server-beta from beta
git checkout beta
git checkout -b server-beta
git push -u origin server-beta

2. Create Digital Ocean App Platform applications:
   • Create a new app for each environment
   • Upload the corresponding app spec YAML file
   • Configure the environment variables

Ongoing Deployment Process

1. Make changes to the websocket server on the appropriate branch
2. Push changes to trigger automatic deployment:

git checkout server-development
# Make changes to websocket-server directory
git add .
git commit -m "Add new websocket feature"
git push origin server-development

3. Digital Ocean automatically deploys the changes
4. Update Vercel environment variables if needed:

NEXT_PUBLIC_WEBSOCKET_URL=https://app-imagineoai-com-xxxx.ondigitalocean.app
WEBSOCKET_URL=https://app-imagineoai-com-xxxx.ondigitalocean.app
WEBSOCKET_API_KEY=same-as-webhook-secret

Promotion Workflow

To promote changes through environments:

# Promote from development to beta
git checkout server-beta
git merge server-development
git push origin server-beta
 
# Promote from beta to production
git checkout server-main
git merge server-beta
git push origin server-main

Troubleshooting

Build Failures

Common issues and solutions:

1. Dependency version conflicts:

   • Check websocket-server/package.json for outdated dependencies
   • Update versions to match the main project’s dependencies

2. Bun installation issues:

   • Verify the Bun installation commands in app spec files
   • Check Digital Ocean logs for specific errors

3. Environment variable errors:

   • Ensure all required environment variables are set in Digital Ocean
   • Check for typos in variable names

Runtime Issues

1. Connection failures:

   • Verify CORS settings in the websocket server
   • Check that Vercel environment variables point to the correct URL
   • Ensure the websocket server is running (curl https://app-url/health)

2. Authentication errors:

   • Verify Clerk credentials are correct
   • Check that webhook secrets match between Digital Ocean and Vercel

3. Database errors:

   • Verify Turso database credentials
   • Check database connection in logs

Monitoring and Maintenance

1. Performance monitoring:

   • Use Digital Ocean’s built-in metrics
   • Set up alerts for high CPU/memory usage
   • Monitor connection counts and response times

2. Log analysis:

   • Review logs regularly for errors or warnings
   • Set up log-based alerts for critical issues

3. Scaling:

   • Monitor resource usage and scale as needed
   • Consider upgrading instance size for increased traffic

Rollback Procedure

If a deployment introduces issues:

1. Revert to the previous commit:

git checkout server-main
git revert HEAD~1
git push origin server-main

2. Use Digital Ocean’s rollback feature:
   • Navigate to the App Platform dashboard
   • Select the affected app
   • Go to “Deployments” tab
   • Click “Revert” on the last working deployment

Database Considerations

Each environment uses its own Turso database instance:

• Production: DATABASE_URL=libsql://production-db-xxxx.turso.io
• Staging: DATABASE_URL=libsql://staging-db-xxxx.turso.io
• Beta: DATABASE_URL=libsql://beta-db-xxxx.turso.io

Schema changes should be propagated through environments in the same order as code changes.

Security Considerations

1. Authentication:

   • Use different Clerk keys for each environment
   • Regularly rotate webhook secrets

2. CORS configuration:

   • Configure CORS to only allow requests from the corresponding frontend
   • Use environment variables to specify allowed origins

3. API access:

   • Limit access to admin endpoints with authentication
   • Use rate limiting for public endpoints

Future Improvements

• Implement CI/CD pipeline for automated testing before deployment
• Add automated database migrations
• Set up monitoring dashboards for each environment
• Implement canary deployments for production