🚀 BidScript Setup and Deployment Guide¶

Setup Overview Workflow¶

graph TB
    subgraph "Prerequisites"
        PreReq1[Node.js v18+]
        PreReq2[Git]
        PreReq3[Docker]
        PreReq4[Azure Account]
        PreReq5[Vercel Account]
    end

    subgraph "Local Development Setup"
        Clone[Clone Repositories]
        InstallFE[Install Frontend Dependencies]
        InstallBE[Install Backend Dependencies]
        EnvConfig[Configure Environment]
        DBSetup[Database Setup]
        RunLocal[Run Locally]
    end

    subgraph "Production Deployment"
        AzureSetup[Azure Infrastructure]
        VercelDeploy[Vercel Frontend Deploy]
        ContainerDeploy[Container Apps Deploy]
        DBProd[Production Database]
        Monitor[Monitoring Setup]
    end

    PreReq1 --> Clone
    PreReq2 --> Clone
    PreReq3 --> DBSetup
    PreReq4 --> AzureSetup
    PreReq5 --> VercelDeploy

    Clone --> InstallFE
    Clone --> InstallBE
    InstallFE --> EnvConfig
    InstallBE --> EnvConfig
    EnvConfig --> DBSetup
    DBSetup --> RunLocal

    RunLocal -.-> AzureSetup
    AzureSetup --> ContainerDeploy
    AzureSetup --> DBProd
    EnvConfig -.-> VercelDeploy
    ContainerDeploy --> Monitor
    VercelDeploy --> Monitor

Environment Setup Flow¶

graph LR
    subgraph "Development Environment"
        DevFE[Frontend .env.local]
        DevBE[Backend .env]
        DevDB[Local PostgreSQL]
    end

    subgraph "Staging Environment"
        StageFE[Staging .env]
        StageBE[Container Environment]
        StageDB[Azure PostgreSQL]
    end

    subgraph "Production Environment"
        ProdFE[Vercel Environment]
        ProdBE[Container Apps Environment]
        ProdDB[Production PostgreSQL]
    end

    DevFE -.-> StageFE
    DevBE -.-> StageBE
    DevDB -.-> StageDB

    StageFE --> ProdFE
    StageBE --> ProdBE
    StageDB --> ProdDB

    style DevFE fill:#e3f2fd
    style StageFE fill:#90caf9
    style ProdFE fill:#1976d2

📋 Prerequisites¶

💻 Local Development¶

🟢 Node.js (v18 or higher)
📦 Git
🐳 Docker
☁️ Azure account (basic permissions)

🚀 Deployment Requirements¶

⚡ Vercel account (frontend deployment)
🔧 Azure Container Apps access
📍 Pinecone account
☁️ Azure account with elevated permissions for:
📦 Container Registry
🤖 OpenAI
💾 Storage
🗄️ SQL Database

🏗️ Local Setup Guide¶

⚛️ Frontend Setup¶

📥 Clone and install:

git clone https://github.com/BidScript/bidscriptfrontend.git
cd bidscriptfrontend
npm install

⚙️ Configure environment: Create .env.local:

NEXTAUTH_SECRET=your_auth_secret
AZURE_STORAGE_CONNECTION_STRING=your_azure_connection_string
DATABASE_URL=your_database_url

🔧 Initialize:

npm run copy-pspdfkit-files
npx prisma generate
npx prisma migrate

🚀 Start development:

npm run dev

🔧 Backend Setup¶

📥 Clone and install:

git clone https://github.com/BidScript/bidssappserver-nestjs.git
cd bidssappserver-nestjs
npm install

Configure environment: Create .env:

CONNECTION_STRING=your_connection_string
PINECONE_API_KEY=your_pinecone_api_key

SQL_DB_PASSWORD=your_sql_password
SQL_DB_USERNAME=your_sql_username
SQL_SERVER=your_sql_server
SQL_DATABASE=your_sql_database

GRAFANA_USER_ID=your_grafana_user_id
GRAFANA_API_KEY=your_grafana_api_key

AZURE_OPENAI_API_KEY=your_azure_openai_api_key
AZURE_OPENAI_EMBED_API_KEY=your_azure_openai_embed_api_key
AZURE_OPENAI_ENDPOINT=your_azure_openai_endpoint

LLAMA_CLOUD_API_KEY=your_llama_cloud_api_key

DISABLE_NEST_ASYNCIO=your_disable_nest_asyncio
NEXTAUTH_SECRET=your_nextauth_secret

Start development:

npm run start:dev

WebSocket Server Setup¶

Clone and install:

git clone https://github.com/BidScript/bidscript-yjs-ws-backend.git
cd bidscript-yjs-ws-backend
npm install

Configure environment: Create .env.local with Redis and Azure Storage configuration from backend.

Deployment Guide¶

Frontend Deployment (Vercel)¶

Connect GitHub repo in Vercel dashboard
Configure Vercel environment:
Set NEXTAUTH_URL to production URL
Add all environment variables from .env.local
Branch deployments:
main -> Production (https://app.bidscript.co.uk/app)
staging -> Staging (https://staging-app.bidscript.co.uk/app)
Build settings:

Build Command: npm run build
Output Directory: .next
Install Command: npm install

Backend Deployment (Azure Container Apps)¶

Required Azure Resources:
Container Registry: BidScriptContainerRegistry (UK South)
SQL Database: bidscriptsqldb on bidscriptsqslserver (UK South)
Azure OpenAI: BidScriptOpenAI (Switzerland North)
Redis Cache: bidscript-basic (UK West)
Storage Account: bidscriptstorage (Switzerland North)
Container Apps Environment: managedEnvironment-BidScript (UK South)
Required GitHub Actions secrets:

AZURE_CREDENTIALS=your_azure_credentials
REGISTRY_LOGIN_SERVER=bidscriptcontainerregistry.azurecr.io
REGISTRY_USERNAME=your_acr_username
REGISTRY_PASSWORD=your_acr_password
SQL_SERVER=bidscriptsqslserver.database.windows.net
SQL_DATABASE=bidscriptsqldb
CONNECTION_STRING=your_storage_connection_string
OPENAI_API_KEY=your_openai_api_key
PINECONE_API_KEY=your_pinecone_api_key

Container configuration:

services:
  bidsappserver:
    image: ${REGISTRY_LOGIN_SERVER}/bidscriptappserver01:latest
    ports:
      - "8000:8000"
    cpus: "14.0"
    memory: "3G"
    env:
      - name: REDIS_HOST
        value: "bidscript-basic.redis.cache.windows.net"
      - name: SQL_SERVER
        value: "bidscriptsqslserver.database.windows.net"

WebSocket Server Deployment (Azure Container Apps)¶

Required Azure Resources:
Container App: bidscript-yjs-container (UK West)
Container Apps Environment: yjs-websocket-env (UK West)
Redis Cache: bidscript-basic (UK West)
Storage Account: bidscript9e55 (UK West)
Log Analytics: workspace-bidscriptwebsocket57B5 (UK West)
Container configuration:

name: bidscript-yjs-container
location: ukwest
properties:
  ingress:
    external: true
    targetPort: 3000
    transport: http2
    allowInsecure: false
  scale:
    minReplicas: 1
    maxReplicas: 10
  managedEnvironmentId: /subscriptions/your-subscription/resourceGroups/bidscript-websocket/providers/Microsoft.App/managedEnvironments/yjs-websocket-env

resources:
  limits:
    cpu: "0.5"
    memory: "1Gi"
  requests:
    cpu: "0.2"
    memory: "512Mi"

Environment configuration:

env:
  - name: SERVER_PORT
    value: "3000"
  - name: REDIS_HOST
    value: "bidscript-basic.redis.cache.windows.net"
  - name: AZURE_STORAGE_ACCOUNT
    value: "bidscript9e55"

Troubleshooting Common Issues¶

Frontend¶

Check environment variables
Verify backend services are running
Ensure Prisma migrations are up to date
Verify PDF viewer files are copied

Backend¶

Verify Azure SQL connection strings
Check Redis configuration
Ensure environment variables are set
Verify Pinecone API key and environment

WebSocket Server¶

Check Redis configuration
Verify Azure Storage connection
Ensure proper CORS configuration