Cloud Deployment Guide

This guide covers deploying AuditSphere to various cloud platforms using Docker containers.

Prerequisites

Docker installed locally
Cloud CLI tools (AWS CLI, gcloud, or Azure CLI)
Access to your cloud provider account

Docker Configuration

AuditSphere uses Next.js standalone output for optimized Docker deployments, resulting in images around 150-200MB.

Building the Image


# Build the Docker image
docker build -t auditsphere:latest .
 
# Run locally for testing
docker run -p 3000:3000 --env-file .env.local auditsphere:latest

Dockerfile Overview

The Dockerfile uses a multi-stage build:

base: Node.js 22 Alpine base image
deps: Install dependencies only
builder: Generate Prisma client and build Next.js
runner: Minimal production image with non-root user

Environment Variables

The following environment variables must be configured in your container:

Variable	Description	Required
`DATABASE_URL`	PostgreSQL connection string	Yes
`NEXTAUTH_URL`	Full URL of your deployment	Yes
`NEXTAUTH_SECRET`	Random secret for NextAuth.js	Yes
`AUTH0_CLIENT_ID`	Auth0 application client ID	If using Auth0
`AUTH0_CLIENT_SECRET`	Auth0 application secret	If using Auth0
`AUTH0_ISSUER_BASE_URL`	Auth0 domain URL	If using Auth0
`MICROSOFT_CLIENT_ID`	Azure AD application ID	If using Azure AD
`MICROSOFT_CLIENT_SECRET`	Azure AD client secret	If using Azure AD
`MICROSOFT_TENANT_ID`	Azure AD tenant ID	If using Azure AD
`ML_API_URL`	URL to ML service	For risk scoring
`UPSTASH_REDIS_REST_URL`	Redis URL for rate limiting	Optional
`UPSTASH_REDIS_REST_TOKEN`	Redis auth token	Optional

AWS Deployment (ECS Fargate)

Architecture

Step 1: Create ECR Repository


# Create repository
aws ecr create-repository --repository-name auditsphere
 
# Get login credentials
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com
 
# Tag and push image
docker tag auditsphere:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/auditsphere:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/auditsphere:latest

Step 2: Create ECS Task Definition


{
  "family": "auditsphere",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "containerDefinitions": [
    {
      "name": "auditsphere",
      "image": "<account-id>.dkr.ecr.us-east-1.amazonaws.com/auditsphere:latest",
      "portMappings": [
        {
          "containerPort": 3000,
          "protocol": "tcp"
        }
      ],
      "secrets": [
        {
          "name": "DATABASE_URL",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:<account-id>:secret:auditsphere/database-url"
        },
        {
          "name": "NEXTAUTH_SECRET",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:<account-id>:secret:auditsphere/nextauth-secret"
        }
      ],
      "environment": [
        {
          "name": "NEXTAUTH_URL",
          "value": "https://auditsphere.example.com"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/auditsphere",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

Step 3: Create ECS Service


# Create cluster
aws ecs create-cluster --cluster-name auditsphere-cluster
 
# Create service with ALB
aws ecs create-service \
  --cluster auditsphere-cluster \
  --service-name auditsphere-service \
  --task-definition auditsphere \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}" \
  --load-balancers "targetGroupArn=arn:aws:elasticloadbalancing:...,containerName=auditsphere,containerPort=3000"

Database Options for AWS

Option 1: Continue using Neon

Simply pass your existing DATABASE_URL to the container
No additional AWS infrastructure needed

Option 2: Amazon RDS PostgreSQL


aws rds create-db-instance \
  --db-instance-identifier auditsphere-db \
  --db-instance-class db.t3.micro \
  --engine postgres \
  --master-username admin \
  --master-user-password <password> \
  --allocated-storage 20

Connection string format:


postgresql://admin:<password>@auditsphere-db.xxx.us-east-1.rds.amazonaws.com:5432/auditsphere

GCP Deployment (Cloud Run)

Architecture

Step 1: Push to Artifact Registry


# Configure Docker for GCP
gcloud auth configure-docker us-central1-docker.pkg.dev
 
# Tag and push
docker tag auditsphere:latest us-central1-docker.pkg.dev/<project-id>/auditsphere/app:latest
docker push us-central1-docker.pkg.dev/<project-id>/auditsphere/app:latest

Step 2: Deploy to Cloud Run


gcloud run deploy auditsphere \
  --image us-central1-docker.pkg.dev/<project-id>/auditsphere/app:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --port 3000 \
  --memory 1Gi \
  --cpu 1 \
  --min-instances 1 \
  --max-instances 10 \
  --set-env-vars "NEXTAUTH_URL=https://auditsphere-xxx.run.app" \
  --set-secrets "DATABASE_URL=auditsphere-db-url:latest,NEXTAUTH_SECRET=auditsphere-nextauth-secret:latest"

Database Options for GCP

Option 1: Continue using Neon

Pass your existing DATABASE_URL as a secret

Option 2: Cloud SQL PostgreSQL


gcloud sql instances create auditsphere-db \
  --database-version=POSTGRES_15 \
  --tier=db-f1-micro \
  --region=us-central1
 
gcloud sql databases create auditsphere --instance=auditsphere-db

Azure Deployment (Container Apps)

Architecture

Step 1: Push to Azure Container Registry


# Login to ACR
az acr login --name <registry-name>
 
# Tag and push
docker tag auditsphere:latest <registry-name>.azurecr.io/auditsphere:latest
docker push <registry-name>.azurecr.io/auditsphere:latest

Step 2: Deploy to Container Apps


# Create Container Apps environment
az containerapp env create \
  --name auditsphere-env \
  --resource-group auditsphere-rg \
  --location eastus
 
# Deploy the app
az containerapp create \
  --name auditsphere \
  --resource-group auditsphere-rg \
  --environment auditsphere-env \
  --image <registry-name>.azurecr.io/auditsphere:latest \
  --target-port 3000 \
  --ingress external \
  --min-replicas 1 \
  --max-replicas 10 \
  --cpu 0.5 \
  --memory 1Gi \
  --secrets "db-url=<database-url>,nextauth-secret=<secret>" \
  --env-vars "DATABASE_URL=secretref:db-url" "NEXTAUTH_SECRET=secretref:nextauth-secret" "NEXTAUTH_URL=https://auditsphere.<env-id>.eastus.azurecontainerapps.io"

Database Options for Azure

Option 1: Continue using Neon

Pass your existing DATABASE_URL as a secret

Option 2: Azure Database for PostgreSQL


az postgres flexible-server create \
  --resource-group auditsphere-rg \
  --name auditsphere-db \
  --location eastus \
  --admin-user admin \
  --admin-password <password> \
  --sku-name Standard_B1ms \
  --tier Burstable

CI/CD Pipeline

GitHub Actions Example


name: Deploy to Cloud
 
on:
  push:
    branches: [main]
 
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Build Docker image
        run: docker build -t auditsphere:${{ github.sha }} .
 
      # AWS deployment
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
 
      - name: Push to ECR
        run: |
          aws ecr get-login-password | docker login --username AWS --password-stdin ${{ secrets.ECR_REGISTRY }}
          docker tag auditsphere:${{ github.sha }} ${{ secrets.ECR_REGISTRY }}/auditsphere:latest
          docker push ${{ secrets.ECR_REGISTRY }}/auditsphere:latest
 
      - name: Deploy to ECS
        run: aws ecs update-service --cluster auditsphere-cluster --service auditsphere-service --force-new-deployment

Health Checks

Configure health checks for your cloud provider:

Health endpoint: GET /api/health (you may need to create this)
Port: 3000
Interval: 30 seconds
Timeout: 5 seconds
Healthy threshold: 2
Unhealthy threshold: 3

Scaling Recommendations

Traffic Level	CPU	Memory	Min Instances	Max Instances
Development	0.25	512MB	1	1
Small (< 100 users)	0.5	1GB	1	3
Medium (100-1000 users)	1	2GB	2	10
Large (> 1000 users)	2	4GB	3	20

Troubleshooting

Container won’t start

Check that all required environment variables are set
Verify DATABASE_URL is accessible from the container network
Check container logs for Prisma connection errors

502/503 errors after deployment

Ensure health check endpoint is responding
Verify port 3000 is correctly mapped
Check that NEXTAUTH_URL matches your actual domain

Database connection issues

Ensure security groups/firewall rules allow connections
For cloud databases, check that SSL mode is correctly configured
Verify the connection string format is correct