Deployment Guide

This guide covers multiple deployment strategies for the Pet Service Management System.

Docker

Containerized deployment

Railway

One-click deployment with Railway MCP

Cloud Platforms

AWS, GCP, Vercel

Docker Deployment

Prerequisites

Docker 20.10+
Docker Compose 2.0+

Step 1: Build Docker Images

Create a Dockerfile in the root directory:

# backend/Dockerfile
FROM node:18-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./
COPY prisma ./prisma/

# Install dependencies
RUN npm ci

# Copy source code
COPY . .

# Generate Prisma client
RUN npx prisma generate

# Build application
RUN npm run build

# Production stage
FROM node:18-alpine

WORKDIR /app

# Copy built files
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/package*.json ./

# Expose port
EXPOSE 3001

# Start application
CMD ["npm", "run", "start:prod"]

Step 2: Docker Compose Configuration

Create docker-compose.yml in the root directory:

docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: petservice-db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: petservice
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - petservice-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: petservice-backend
    environment:
      NODE_ENV: production
      PORT: 3001
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/petservice
      BETTER_AUTH_URL: http://backend:3001/api/auth
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
      SESSION_SECRET: ${SESSION_SECRET}
      JWT_SECRET: ${JWT_SECRET}
      FRONTEND_URL: http://frontend:3000
    ports:
      - "3001:3001"
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - petservice-network
    command: >
      sh -c "npx prisma migrate deploy &&
             npm run start:prod"

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    container_name: petservice-frontend
    environment:
      NEXT_PUBLIC_API_URL: http://localhost:3001
      NEXT_PUBLIC_APP_URL: http://localhost:3000
    ports:
      - "3000:3000"
    depends_on:
      - backend
    networks:
      - petservice-network

volumes:
  postgres_data:

networks:
  petservice-network:
    driver: bridge

Step 3: Environment Configuration

Create .env file in the root directory:

.env

# Secrets (Generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET=your-32-char-secret-here
SESSION_SECRET=your-32-char-secret-here
JWT_SECRET=your-32-char-secret-here

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=petservice

Security: Never commit .env to version control. Use .env.example as template.

Step 4: Build and Run

Build Images

docker-compose build

Start Services

docker-compose up -d

Verify Services

# Check running containers
docker-compose ps

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

Access Application

Frontend: http://localhost:3000
Backend API: http://localhost:3001
Prisma Studio: docker-compose exec backend npx prisma studio

Docker Management Commands

docker-compose up -d

Railway Deployment

Railway provides automatic deployments with built-in PostgreSQL and zero-config setup.

Option 1: Deploy via Railway CLI

Install Railway CLI

npm install -g @railway/cli

railway login

Initialize Project

railway init

Add PostgreSQL Database

railway add postgresql

Railway automatically sets DATABASE_URL environment variable.

Set Environment Variables

railway variables set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
railway variables set SESSION_SECRET=$(openssl rand -base64 32)
railway variables set JWT_SECRET=$(openssl rand -base64 32)
railway variables set NODE_ENV=production
railway variables set FRONTEND_URL=https://your-app.railway.app

Deploy Backend

cd backend
railway up

Deploy Frontend

cd frontend
railway up

Run Migrations

railway run npx prisma migrate deploy

Option 2: Deploy via Railway Button

Deploy to Railway

Click to deploy with one button

Click “Deploy on Railway” button
Connect your GitHub repository
Railway auto-detects backend/frontend
Add PostgreSQL database from Railway marketplace
Set environment variables in Railway dashboard
Deploy automatically on git push

Railway Environment Variables

Set these in Railway dashboard or CLI:

Variable	Value	Notes
`NODE_ENV`	`production`	Environment mode
`DATABASE_URL`	Auto-set by Railway	PostgreSQL connection
`BETTER_AUTH_SECRET`	Generate 32+ chars	Auth secret
`SESSION_SECRET`	Generate 32+ chars	Session encryption
`JWT_SECRET`	Generate 32+ chars	JWT signing
`FRONTEND_URL`	`https://your-app.railway.app`	Frontend URL
`PORT`	`3001` (backend)	Service port

Railway MCP Integration

Railway MCP (Model Context Protocol) enables AI assistants to manage your deployments.

Configure Railway MCP:

Install Railway MCP server:

npm install -g @railway/mcp

Configure in your Claude Code settings:

{
  "mcpServers": {
    "railway": {
      "command": "railway-mcp",
      "env": {
        "RAILWAY_TOKEN": "your-railway-token"
      }
    }
  }
}

Use AI commands:

Claude: "Deploy backend to Railway"
Claude: "Check Railway deployment status"
Claude: "View Railway logs for backend service"
Claude: "Add PostgreSQL to Railway project"

Cloud Platform Deployment

Vercel (Frontend)

Install Vercel CLI

npm install -g vercel

Deploy Frontend

cd frontend
vercel

Set Environment Variables

vercel env add NEXT_PUBLIC_API_URL
vercel env add NEXT_PUBLIC_APP_URL

Production Deployment

vercel --prod

Heroku (Backend)

Install Heroku CLI

brew install heroku/brew/heroku

Create Heroku App

cd backend
heroku create petservice-backend

Add PostgreSQL

heroku addons:create heroku-postgresql:mini

Set Environment Variables

heroku config:set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
heroku config:set SESSION_SECRET=$(openssl rand -base64 32)
heroku config:set JWT_SECRET=$(openssl rand -base64 32)
heroku config:set NODE_ENV=production

Deploy

git push heroku main

Run Migrations

heroku run npx prisma migrate deploy

AWS (Full Stack)

Frontend on S3 + CloudFront
Backend on EC2
Database on RDS

# Build frontend
cd frontend
npm run build

# Deploy to S3
aws s3 sync .next/static s3://your-bucket/static
aws cloudfront create-invalidation --distribution-id XXX --paths "/*"

# SSH to EC2
ssh -i key.pem ec2-user@your-ec2-ip

# Install dependencies
sudo yum update
sudo yum install nodejs npm postgresql

# Clone and setup
git clone your-repo
cd backend
npm install
npm run build

# Setup PM2
npm install -g pm2
pm2 start dist/main.js --name petservice-backend
pm2 save
pm2 startup

# Create RDS PostgreSQL instance via AWS Console
# Update DATABASE_URL with RDS endpoint
DATABASE_URL=postgresql://user:pass@rds-endpoint:5432/petservice

Production Checklist

Security

HTTPS/TLS enabled (use Let’s Encrypt or cloud provider SSL)
Strong secrets (32+ characters, randomly generated)
Environment variables properly set (no hardcoded secrets)
CORS configured for specific origins
Rate limiting enabled on API endpoints
Database backups configured (daily/hourly)
Security headers configured (Helmet.js)

Performance

CDN configured for static assets
Database connection pooling enabled
Query optimization with proper indexes
Caching strategy implemented (Redis optional)
Image optimization enabled
Gzip compression enabled

Monitoring

Application logging configured
Error tracking (Sentry, LogRocket)
Uptime monitoring (UptimeRobot, Pingdom)
Performance monitoring (New Relic, DataDog)
Database monitoring (pgAdmin, Railway analytics)

Database

Production database created
Migrations applied: npx prisma migrate deploy
Seed data loaded (if needed)
Backup strategy configured
Connection pool configured
Indexes optimized

Environment

NODE_ENV=production set
All required environment variables configured
Frontend API URL points to production backend
Backend CORS allows production frontend
Email service configured (SMTP credentials)

Continuous Deployment

GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy-backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        working-directory: backend
        run: npm ci

      - name: Build
        working-directory: backend
        run: npm run build

      - name: Deploy to Railway
        run: |
          npm install -g @railway/cli
          railway up --service backend
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

  deploy-frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        working-directory: frontend
        run: npm ci

      - name: Build
        working-directory: frontend
        run: npm run build

      - name: Deploy to Vercel
        run: vercel --prod --token ${{ secrets.VERCEL_TOKEN }}

Monitoring & Maintenance

Health Checks

# Backend health
curl https://api.yourapp.com/health

# Database connection
curl https://api.yourapp.com/db/health

# Frontend
curl https://yourapp.com

View Logs

Docker
Railway
Heroku

docker-compose logs -f backend
docker-compose logs -f frontend

railway logs
railway logs --service backend

heroku logs --tail --app petservice-backend

Database Backup

# PostgreSQL dump
pg_dump -h localhost -U postgres petservice > backup.sql

# Restore
psql -h localhost -U postgres petservice < backup.sql

Troubleshooting

Deployment Fails

Solution:

Check build logs: railway logs or docker-compose logs
Verify environment variables are set
Ensure dependencies are installed: npm ci
Check Dockerfile syntax

Database Connection Error

Solution:

Verify DATABASE_URL is correct
Check database is running
Confirm firewall rules allow connection
Test connection: psql $DATABASE_URL

CORS Errors

Solution:

Set FRONTEND_URL in backend environment
Verify CORS configuration in main.ts
Check frontend uses correct API URL

SSL/HTTPS Issues

Solution:

Use Railway/Vercel automatic SSL
For custom domains, configure SSL certificate
Use Let’s Encrypt for free SSL: certbot

Next Steps

Architecture Overview

Understand system design

API Reference

Explore REST endpoints

Installation Guide

Set up development environment

Back to Home

Return to homepage

Deployment Complete! Your Pet Service Management System is now live.

Getting Started

Setup & Deployment

Developer Resources

Project Management

Deployment Guide

Deployment Guide

Docker

Railway

Cloud Platforms

Docker Deployment

Prerequisites

Step 1: Build Docker Images

Step 2: Docker Compose Configuration

Step 3: Environment Configuration

Step 4: Build and Run

Docker Management Commands

Railway Deployment

Option 1: Deploy via Railway CLI

Option 2: Deploy via Railway Button

Deploy to Railway

Railway Environment Variables

Railway MCP Integration

Cloud Platform Deployment

Vercel (Frontend)

Heroku (Backend)

AWS (Full Stack)

Production Checklist

Continuous Deployment

GitHub Actions

Monitoring & Maintenance

Health Checks

View Logs

Database Backup

Troubleshooting

Next Steps

Architecture Overview

API Reference

Installation Guide

Back to Home

Getting Started

Setup & Deployment

Developer Resources

Project Management

​Deployment Guide

Docker

Railway

Cloud Platforms

​Docker Deployment

​Prerequisites

​Step 1: Build Docker Images

​Step 2: Docker Compose Configuration

​Step 3: Environment Configuration

​Step 4: Build and Run

​Docker Management Commands

​Railway Deployment

​Option 1: Deploy via Railway CLI

​Option 2: Deploy via Railway Button

Deploy to Railway

​Railway Environment Variables

​Railway MCP Integration

​Cloud Platform Deployment

​Vercel (Frontend)

​Heroku (Backend)

​AWS (Full Stack)

​Production Checklist

​Continuous Deployment

​GitHub Actions

​Monitoring & Maintenance

​Health Checks

​View Logs

​Database Backup

​Troubleshooting

​Next Steps

Architecture Overview

API Reference

Installation Guide

Back to Home

Deployment Guide

Docker Deployment

Prerequisites

Step 1: Build Docker Images

Step 2: Docker Compose Configuration

Step 3: Environment Configuration

Step 4: Build and Run

Docker Management Commands

Railway Deployment

Option 1: Deploy via Railway CLI

Option 2: Deploy via Railway Button

Railway Environment Variables

Railway MCP Integration

Cloud Platform Deployment

Vercel (Frontend)

Heroku (Backend)

AWS (Full Stack)

Production Checklist

Continuous Deployment

GitHub Actions

Monitoring & Maintenance

Health Checks

View Logs

Database Backup

Troubleshooting

Next Steps