Deployment Guide

Learn how to deploy PROVESA Web to production environments

This guide covers deploying PROVESA Web to production, including setup, configuration, and best practices for a secure and performant deployment.

Prerequisites

Before deploying, ensure you have:

1. Production Environment

   • Node.js v20+ installed
   • PostgreSQL 15+ database (local or hosted)
   • Domain name configured (optional but recommended)
   • SSL certificate (for HTTPS)
2. Environment Variables

   All required environment variables documented and ready:

   • Database connection string
   • Authentication secrets
   • Email credentials (for password recovery)
   • Production URL/domain
3. Code Repository

   • Code committed to Git repository
   • .env file excluded from version control
   • Production branch ready

Environment Configuration

Required Environment Variables

Create a .env file in production with the following variables:

# Database
DATABASE_URL="postgres://user:password@host:5432/provesa"

# Application URL
ORIGIN="https://your-domain.com"

# Better Auth Secret (32+ characters, high entropy)
BETTER_AUTH_SECRET="your-secure-random-secret-here"

# Gmail for Password Recovery
GMAIL_USER="[e-mail]"
GMAIL_APP_PASSWORD="your-16-char-app-password"

Security Critical: Never commit .env files to version control. Use environment variables or secure secret management services.

Generating Secure Secrets

Generate a strong BETTER_AUTH_SECRET:

Using OpenSSL

openssl rand -base64 32

This generates a cryptographically secure 32-byte random string.

Using Node.js

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Generates a secure random secret using Node’s crypto module.

Online Generator

Use a password generator like 1Password or LastPass:

• Set length to 32+ characters
• Include uppercase, lowercase, numbers, symbols
• Copy and store securely

Database Setup

PostgreSQL Production Database

1. Create Database

   Create a new PostgreSQL database:

   CREATE DATABASE provesa;
   CREATE USER provesa_user WITH PASSWORD 'secure_password';
   GRANT ALL PRIVILEGES ON DATABASE provesa TO provesa_user;
   
2. Configure Connection

   Update DATABASE_URL in .env:

   DATABASE_URL="postgres://provesa_user:secure_password@localhost:5432/provesa"
   

   For hosted databases (like Railway, Supabase, or Heroku):

   DATABASE_URL="postgres://user:[e-mail]:5432/dbname"
   
3. Run Migrations

   Apply database schema:

   pnpm db:push
   

   Or use migrations:

   pnpm db:generate  # Generate migration files
   pnpm db:migrate   # Apply migrations
   
4. Seed Initial Data

   Create admin user and default theme:

   pnpm db:seed
   

   Change the default admin password immediately after first login.

Database Hosting Options

Supabase

• Free tier with 500MB database
• Automatic backups
• Easy PostgreSQL management
• Global CDN for assets

Learn more →

Railway

• PostgreSQL as a service
• Auto-scaling
• Simple deployment
• $5/month starter plan

Learn more →

Neon

• Serverless Postgres
• Free tier available
• Instant branching
• Auto-scaling compute

Learn more →

Self-Hosted

• Full control
• No vendor lock-in
• Requires server management
• Custom backup solutions

Building for Production

Creating Production Build

1. Install Dependencies

   pnpm install --production=false
   

   Installs all dependencies including dev dependencies needed for build.

2. Run Production Build

   pnpm build
   

   This:

   • Compiles SvelteKit application
   • Optimizes assets
   • Generates static files
   • Creates production-ready build in build/ directory
3. Test Production Build

   Preview the production build locally:

   pnpm preview
   

   Visit the preview URL to test before deploying.

Build Output

The build creates:

• /build - Production server files
• /build/client - Client-side assets
• /build/server - Server-side code
• Static assets optimized and fingerprinted

Deployment Options

Option 1: Vercel (Recommended)

Vercel provides seamless SvelteKit deployment:

1. Install Vercel CLI

   pnpm install -g vercel
   
2. Login to Vercel

   vercel login
   
3. Deploy

   vercel
   

   Follow prompts to:

   • Link to existing project or create new
   • Configure project settings
   • Set environment variables
4. Configure Environment Variables

   In Vercel dashboard:

   1. Go to Project Settings → Environment Variables
   2. Add all required variables from .env
   3. Set for Production environment
   4. Redeploy if needed
5. Production Deploy

   vercel --prod
   

   Deploys to production domain.

Vercel automatically handles:

• SSL certificates
• Global CDN
• Automatic HTTPS
• Serverless functions
• Build optimization

Option 2: Node.js Server

Deploy to a traditional Node.js server:

1. Prepare Server

   Install Node.js 20+ and pnpm on your server:

   curl -fsSL https://get.pnpm.io/install.sh | sh -
   
2. Clone Repository

   git clone https://github.com/your-org/provesa-web.git
   cd provesa-web
   
3. Install and Build

   pnpm install
   pnpm build
   
4. Set Environment Variables

   Create .env file with production values.

5. Start Server

   NODE_ENV=production node build/index.js
   

   Or use a process manager like PM2:

   pm2 start build/index.js --name provesa-web
   pm2 save
   pm2 startup
   

Option 3: Docker Container

Containerize the application:

1. Create Dockerfile

   FROM node:20-alpine
   
   WORKDIR /app
   
   # Install pnpm
   RUN npm install -g pnpm
   
   # Copy package files
   COPY package.json pnpm-lock.yaml ./
   
   # Install dependencies
   RUN pnpm install --frozen-lockfile
   
   # Copy source
   COPY . .
   
   # Build application
   RUN pnpm build
   
   # Expose port
   EXPOSE 3000
   
   # Start app
   CMD ["node", "build/index.js"]
   
2. Build Image

   docker build -t provesa-web .
   
3. Run Container

   docker run -d \
     -p 3000:3000 \
     --env-file .env \
     --name provesa-web \
     provesa-web
   

Option 4: Railway

Deploy with one click to Railway:

1. Connect Repository

   1. Visit Railway
   2. Click “New Project” → “Deploy from GitHub repo”
   3. Select your PROVESA Web repository
2. Add PostgreSQL

   1. Click “New” → “Database” → “Add PostgreSQL”
   2. Railway provisions database automatically
   3. Copy DATABASE_URL from database variables
3. Configure Variables

   Add environment variables in Railway dashboard:

   • BETTER_AUTH_SECRET
   • GMAIL_USER
   • GMAIL_APP_PASSWORD
   • ORIGIN (use Railway-provided domain)
4. Deploy

   Railway automatically builds and deploys on push to main branch.

Post-Deployment Tasks

1. Verify Database Connection

   Check that the application can connect to the database:

   • Visit /login page
   • Attempt to log in
   • Check server logs for database errors
2. Change Default Password

   Log in with seeded admin credentials and immediately change password:

   1. Log out
   2. Use password recovery flow
   3. Set strong, unique password
3. Test Email Delivery

   Verify password recovery emails work:

   1. Request password reset
   2. Check if email arrives
   3. Test reset link
4. Configure Domain

   Set up custom domain:

   • Point DNS A record to server IP
   • Or add CNAME to Vercel/Railway domain
   • Configure SSL certificate
   • Update ORIGIN environment variable
5. Enable Monitoring

   Set up application monitoring:

   • Error tracking (Sentry, Bugsnag)
   • Performance monitoring
   • Uptime monitoring (UptimeRobot, Pingdom)
   • Log aggregation

Security Checklist

Environment

• All secrets stored securely (not in code)
• .env excluded from version control
• Strong BETTER_AUTH_SECRET (32+ chars)
• Production ORIGIN matches actual domain
• Gmail app password (not regular password)

Database

• Strong database password
• Database user has minimal required permissions
• Database not publicly accessible
• Regular backups configured
• SSL/TLS connection to database

Application

• HTTPS enabled (SSL certificate)
• Default admin password changed
• No development endpoints exposed
• CORS configured correctly
• Rate limiting enabled (if applicable)

Access Control

• Only necessary admin accounts created
• Strong passwords enforced
• Regular security audits scheduled
• Activity logging enabled

Performance Optimization

Caching Strategies

Static Asset Caching

Configure CDN or reverse proxy caching:

• Cache static files (JS, CSS, images)
• Set appropriate cache headers
• Use fingerprinting for cache busting
• Consider using Cloudflare or similar CDN

Database Query Optimization

• Add database indexes on frequently queried columns
• Use connection pooling
• Implement query caching where appropriate
• Monitor slow queries

Image Optimization

• Compress images before uploading
• Use WebP format when possible
• Implement lazy loading
• Consider image CDN (Cloudinary, imgix)

Monitoring and Logging

Set up comprehensive monitoring:

Application Monitoring

• Response times
• Error rates
• Memory usage
• CPU utilization

Tools: New Relic, Datadog

Error Tracking

• Runtime errors
• Stack traces
• User impact
• Error trends

Tools: Sentry, Rollbar

Uptime Monitoring

• Service availability
• Response time
• SSL certificate expiry
• Alerts and notifications

Tools: UptimeRobot, Pingdom

Log Management

• Centralized logging
• Log search and analysis
• Retention policies
• Alert on patterns

Tools: Logtail, Papertrail

Backup and Recovery

Database Backups

1. Configure Automated Backups

   Set up daily database backups:

   # Example: Daily PostgreSQL backup
   pg_dump -U provesa_user provesa > backup_$(date +%Y%m%d).sql
   

   Or use your hosting provider’s backup service.

2. Test Backup Restoration

   Regularly test that backups can be restored:

   psql -U provesa_user provesa_test < backup_20240312.sql
   
3. Off-Site Storage

   Store backups in different location:

   • Cloud storage (S3, Google Cloud Storage)
   • Different geographic region
   • Encrypted backups

Disaster Recovery Plan

1. Backup Frequency: Daily automated backups
2. Retention: Keep 30 days of daily backups
3. Recovery Time Objective (RTO): 4 hours
4. Recovery Point Objective (RPO): 24 hours
5. Testing: Quarterly disaster recovery drills

Scaling Considerations

Horizontal Scaling

As traffic grows:

1. Multiple App Instances: Deploy multiple server instances behind load balancer
2. Database Replication: Set up read replicas for database queries
3. CDN Integration: Offload static assets to CDN
4. Caching Layer: Add Redis for session storage and caching

Vertical Scaling

Increase server resources:

• Upgrade server CPU and RAM
• Increase database compute
• Optimize database queries and indexes

Troubleshooting Production Issues

Application won't start

Check:

• Environment variables set correctly
• Database accessible from server
• Port not already in use
• Node.js version compatible (20+)
• Build completed successfully

Logs to review:

# Check server logs
tail -f /var/log/provesa-web.log

# Or PM2 logs
pm2 logs provesa-web

Database connection errors

Verify:

• DATABASE_URL format correct
• Database server running
• Firewall allows connection
• User has necessary permissions
• SSL settings if required

Test connection:

psql "$DATABASE_URL"

Email not sending

Check:

• GMAIL_USER and GMAIL_APP_PASSWORD correct
• App password (not regular password)
• Gmail 2FA enabled
• SMTP ports not blocked
• Rate limits not exceeded

Maintenance Best Practices

1. Regular Updates: Keep dependencies updated monthly
2. Security Patches: Apply critical security updates immediately
3. Backup Verification: Test backups quarterly
4. Performance Audits: Review performance metrics monthly
5. Security Audits: Conduct security review quarterly
6. Dependency Audits: Run pnpm audit regularly

Next Steps

Admin Panel Usage

Learn to use the admin interface

Managing Content

Update and manage site content