Skip to main content

Deployment

Guide to deploying PBS Knowledge in development and production environments.

Prerequisites​

Required Software​

  • Docker 24.x or later
  • Docker Compose v2
  • Git
  • Node.js 20.x (for local development)

Server Requirements​

Minimum:

  • 4 CPU cores
  • 8 GB RAM
  • 50 GB storage

Recommended:

  • 8 CPU cores
  • 16 GB RAM
  • 100 GB SSD storage

Configuration Files​

Docker Compose Files​

FilePurpose
docker-compose.hybrid.ymlProduction configuration
docker-compose.dev.ymlDevelopment overrides

Environment Variables​

Copy .env.example to .env and configure:

# Database
TERMINUSDB_ADMIN_PASS=secure-password-here

# Authentication
FIREBASE_PROJECT_ID=your-project
FIREBASE_CLIENT_EMAIL=service@project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."

# SAML
SAML_CERT="..."
SAML_PRIVATE_KEY="..."

# Email
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
SES_FROM_EMAIL=noreply@dartmouthpbs.org

# Dartmouth API
DARTMOUTH_API_KEY=...
DARTMOUTH_API_URL=https://api.dartmouth.edu

# Optional
REDIS_PASSWORD=redis-password
SENTRY_DSN=https://...@sentry.io/...

Development Deployment​

Starting Development Environment​

cd /opt/pbs_knowledge

# Start with hot reload
docker compose -f docker-compose.hybrid.yml -f docker-compose.dev.yml up -d

# View logs
docker compose -f docker-compose.hybrid.yml -f docker-compose.dev.yml logs -f

Development Features​

  • Frontend hot reload on file changes
  • Backend auto-restart on changes
  • Source maps for debugging
  • Verbose logging

Accessing Services​

Production Deployment​

Initial Setup​

# Clone repository
git clone https://github.com/cosanlab/pbs_knowledge.git
cd pbs_knowledge

# Configure environment
cp .env.example .env
# Edit .env with production values

# Build and start
docker compose -f docker-compose.hybrid.yml up -d --build

# Check status
docker compose -f docker-compose.hybrid.yml ps

SSL Configuration​

NGINX handles SSL termination. Configure certificates:

  1. Obtain SSL certificate (Let's Encrypt recommended)
  2. Place certificates in appropriate location
  3. Update NGINX configuration

Health Checks​

Verify deployment:

# Check all containers
docker compose -f docker-compose.hybrid.yml ps

# Check API health
curl http://localhost/api/health

# Check logs for errors
docker compose -f docker-compose.hybrid.yml logs --tail 100

CI/CD Pipeline​

GitHub Actions​

The repository includes CI/CD workflows:

  1. On Pull Request:

    • Lint code
    • Run tests
    • Type checking
    • Build verification

  2. On Push to Main:

    • All PR checks
    • Deploy to production

Deployment Workflow​

deploy:
  runs-on: ubuntu-latest
  steps:
    - name: Deploy to server
      uses: appleboy/ssh-action@v0.1.5
      with:
        host: ${{ secrets.DEPLOY_HOST }}
        username: ${{ secrets.DEPLOY_USER }}
        key: ${{ secrets.DEPLOY_SSH_KEY }}
        script: |
          cd /opt/pbs_knowledge
          git pull origin main
          docker compose -f docker-compose.hybrid.yml build
          docker compose -f docker-compose.hybrid.yml up -d

Container Management​

Viewing Logs​

# All services
docker compose -f docker-compose.hybrid.yml logs -f

# Specific service
docker compose -f docker-compose.hybrid.yml logs -f backend

# Last 100 lines
docker compose -f docker-compose.hybrid.yml logs --tail 100 backend

Restarting Services​

# Restart single service
docker compose -f docker-compose.hybrid.yml restart backend

# Restart all services
docker compose -f docker-compose.hybrid.yml restart

# Rebuild and restart
docker compose -f docker-compose.hybrid.yml up -d --build backend

Scaling Workers​

# Scale worker containers
docker compose -f docker-compose.hybrid.yml up -d --scale worker=3

Database Management​

Backups​

# Manual backup
./scripts/backup-terminusdb.sh

# Automated backups are scheduled via BullMQ

Restore​

# Restore from backup
./scripts/restore-terminusdb.sh backup-file.tar.gz

Schema Updates​

# Apply schema changes
docker compose -f docker-compose.hybrid.yml exec backend node scripts/schema/load-schema.js

Monitoring​

Container Health​

# Check container status
docker compose -f docker-compose.hybrid.yml ps

# Resource usage
docker stats

Application Logs​

Logs are available via:

  • Docker logs (stdout/stderr)
  • Sentry (if configured)
  • Application log files

Metrics​

Monitor key metrics:

  • Response times
  • Error rates
  • Queue depths
  • Database performance

Troubleshooting​

Common Issues​

Container Won't Start:

# Check logs
docker compose -f docker-compose.hybrid.yml logs service-name

# Check configuration
docker compose -f docker-compose.hybrid.yml config

Database Connection Failed:

# Verify TerminusDB is running
docker compose -f docker-compose.hybrid.yml ps terminusdb

# Check network
docker network ls

Out of Memory:

# Check memory usage
docker stats

# Increase limits in docker-compose.yml

Recovery Procedures​

Service Crash:

# Restart affected service
docker compose -f docker-compose.hybrid.yml restart backend

Data Corruption:

# Restore from backup
./scripts/restore-terminusdb.sh latest-backup.tar.gz

Security Checklist​

Before going to production:

  • Change default passwords
  • Configure SSL certificates
  • Set up firewall rules
  • Enable rate limiting
  • Configure backup schedule
  • Set up monitoring alerts
  • Review environment variables
  • Test recovery procedures