Riswis Deployment Guide for DigitalOcean App Platform

This document provides instructions for deploying the Riswis application to DigitalOcean App Platform.

Table of Contents

1. Prerequisites

2. Preparing for Deployment

3. Generating Secrets

4. Deployment Options

   • Option 1: Automated Deployment with Scripts

   • Option 2: Manual Deployment via DigitalOcean UI

5. Post-Deployment Configuration

6. Monitoring and Logs

7. Troubleshooting

Prerequisites

Before starting the deployment process, make sure you have:

1. A DigitalOcean account with billing information set up.

2. The doctl CLI tool installed and authenticated.

   # Install doctl (example for Linux/MacOS)
   brew install doctl  # For MacOS
   # OR for Linux
   curl -sL https://github.com/digitalocean/doctl/releases/download/v1.101.0/doctl-1.101.0-linux-amd64.tar.gz | tar -xzv
   sudo mv doctl /usr/local/bin
   
   # Authenticate doctl
   doctl auth init

3. Access to the GitHub repository: Linxford/riswis

4. A PostgreSQL database provisioned (DigitalOcean managed database recommended).

5. A Redis instance provisioned (DigitalOcean managed Redis recommended).

Preparing for Deployment

1. Make sure your code is committed and pushed to the GitHub repository branch to-office.

2. Update the environment files with the correct values:

   • backend/.env.production

   • frontend/.env.production

Generating Secrets

Run the script to generate secure secrets:

bash scripts/generate-do-secrets.sh

This will output the following secrets that you'll need to configure in DigitalOcean:

• JWT_SECRET: A secure secret for JWT token generation

• ENCRYPTION_KEY: A secure key for encrypting sensitive data

You'll also need to provide these additional secrets:

• DATABASE_URL: Your PostgreSQL connection string

• REDIS_URL: Your Redis connection string

• REDIS_PASSWORD: Your Redis password

• AFRICAS_TALKING_API_KEY: Your Africa's Talking API key

• MOMO_API_USER_ID: Your MTN MoMo API user ID

• MOMO_PRIMARY_KEY: Your MTN MoMo primary key

• NEXT_PUBLIC_MOMO_API_KEY: Your public MTN MoMo API key

• NEXT_PUBLIC_MOMO_USER_ID: Your public MTN MoMo user ID

• NEXT_PUBLIC_MOMO_PRIMARY_KEY: Your public MTN MoMo primary key

Deployment Options

Option 1: Automated Deployment with Scripts

Run the deployment script:

bash scripts/deploy-to-do.sh

This script will:

1. Check if doctl is installed and authenticated

2. Generate an app specification file with the following configuration:

   • Backend service using Dockerfile

   • Frontend service using Next.js

   • Environment variables and secrets

   • Domain configuration

   • Health check at /api/health

3. Deploy the application to DigitalOcean App Platform

4. Provide post-deployment instructions

Option 2: Manual Deployment via DigitalOcean UI

1. Log in to your DigitalOcean account.

2. Navigate to the App Platform section.

3. Click "Create App" and select GitHub as the source.

4. Select the repository Linxford/riswis and branch to-office.

5. Configure the services:

   Backend Service:

   • Choose to use the Dockerfile at ./backend/Dockerfile

   • Set the HTTP Port to 5000

   • Add all environment variables from backend/.env.production

   • Configure health check at /api/health

   Frontend Service:

   • Set Source Directory to frontend

   • Set Build Command to npm run build

   • Set Run Command to npm run start

   • Add all environment variables from frontend/.env.production

6. Configure custom domains:

   • Primary domain: modernsavingsandloans.com

   • Alias domain: api.modernsavingsandloans.com (for backend)

Post-Deployment Configuration

After deployment:

1. Configure Environment Variables:

   • Go to the DigitalOcean App Platform dashboard.

   • Select your app, then go to the Settings tab.

   • Add all the required environment variables from the secrets generation step.

2. Configure Database Connection:

   • If you're using a DigitalOcean managed database, you can link it to your app for automatic connection.

   • Make sure the database connection string is properly set in the environment variables.

3. Configure Domain Names:

   • In the Settings > Domains section, add your domains:

     • modernsavingsandloans.com for the frontend

     • api.modernsavingsandloans.com for the backend

   • Configure DNS records to point to the DigitalOcean App Platform.

4. Verify Health Checks:

   • The backend service includes a health check at /api/health.

   • Monitor the health check status in the DigitalOcean dashboard to ensure your app is functioning correctly.

Monitoring and Logs

To check the deployment status and view logs:

bash scripts/check-do-deployment.sh

This script will:

1. Check if the application is deployed

2. Show the current status

3. Allow you to view logs from both frontend and backend

You can also monitor your application through the DigitalOcean App Platform dashboard.

Troubleshooting

If you encounter issues during deployment:

1. Check Logs:

   doctl apps logs <app-id> --component backend
   doctl apps logs <app-id> --component frontend

2. Check Deployment Status:

   doctl apps get <app-id>

3. Common Issues:

   • If the build fails, check the build logs for syntax errors.

   • If the app deploys but doesn't work, check the runtime logs for errors.

   • If environment variables are not accessible, verify they're correctly set in the app settings.

   • If health checks fail, verify that the /api/health endpoint is responding correctly.

   • If database connection fails, check the DATABASE_URL environment variable and network settings.

4. Testing Database Connection:

   doctl apps exec <app-id> --component backend --command 'node -e "require('\''./dist/scripts/test-db-connection'\'');"'

For additional help, refer to the DigitalOcean App Platform documentation.