Hoppscotch Deployment and Usage Guide

1. Prerequisites

Runtime & Tools

Node.js (v18 or later) - JavaScript runtime
npm or yarn or pnpm - Package manager
Git - Version control
Docker and Docker Compose (optional, for containerized deployment)
PostgreSQL (v12+) - Primary database (required for backend)
Redis (v6+) - For PubSub and caching (required for backend)

Accounts & Services (Optional)

GitHub Account - For OAuth authentication and GitHub Gist integration
Google Account - For OAuth authentication
Microsoft Account - For OAuth authentication

2. Installation

Clone the Repository

git clone https://github.com/hoppscotch/hoppscotch.git
cd hoppscotch

Install Dependencies

Hoppscotch uses a monorepo structure with multiple packages. Install dependencies for all packages:

# Using npm
npm install

# Using yarn
yarn install

# Using pnpm (recommended)
pnpm install

Database Setup

Initialize PostgreSQL database:

# Create a PostgreSQL database named 'hoppscotch'
createdb hoppscotch

# Or using Docker
docker run --name hoppscotch-db -e POSTGRES_PASSWORD=yourpassword -e POSTGRES_DB=hoppscotch -p 5432:5432 -d postgres:15

3. Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/hoppscotch"
REDIS_URL="redis://localhost:6379"

# Authentication
JWT_SECRET="your-jwt-secret-key-here"
JWT_REFRESH_SECRET="your-jwt-refresh-secret-key-here"

# OAuth Providers (optional)
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
MICROSOFT_CLIENT_ID=""
MICROSOFT_CLIENT_SECRET=""

# Application
NODE_ENV="development"
PORT=3000
FRONTEND_URL="http://localhost:3000"
BACKEND_URL="http://localhost:3001"
CORS_ORIGIN="http://localhost:3000"

# Email (optional, for team features)
SMTP_HOST=""
SMTP_PORT=""
SMTP_USER=""
SMTP_PASSWORD=""
FROM_EMAIL=""

Database Schema Generation

Generate Prisma schema and run migrations:

# Navigate to backend package
cd packages/hoppscotch-backend

# Generate Prisma client
npx prisma generate

# Run database migrations
npx prisma migrate dev

# Or push schema directly (development only)
npx prisma db push

4. Build & Run

Development Mode

Run the application in development mode with hot reload:

# Start both frontend and backend concurrently
npm run dev

# Or start separately:
# Terminal 1 - Frontend
cd packages/hoppscotch-frontend
npm run dev

# Terminal 2 - Backend
cd packages/hoppscotch-backend
npm run start:dev

The application will be available at:

Frontend: http://localhost:3000
Backend API: http://localhost:3001

Production Build

Build the application for production:

# Build all packages
npm run build

# Or build individually:
# Build frontend
cd packages/hoppscotch-frontend
npm run build

# Build backend
cd packages/hoppscotch-backend
npm run build

Run Production Build

# Start production server
npm start

# Or start backend only
cd packages/hoppscotch-backend
npm run start:prod

Using Docker

Build and run using Docker Compose:

# Copy example docker-compose file
cp docker-compose.example.yml docker-compose.yml

# Edit docker-compose.yml with your configuration
# Then run:
docker-compose up -d

5. Deployment

Platform Recommendations

Vercel / Netlify (Frontend)

Ideal for the Vue.js frontend
Supports automatic deployments from GitHub
Free tier available

# Deploy to Vercel
npm i -g vercel
vercel --prod

# Deploy to Netlify
npm run build
netlify deploy --prod

Railway / Render (Full Stack)

Supports Node.js backend with PostgreSQL
Easy database integration
Free tier available

# Railway deployment
railway up

# Render deployment
# Connect your GitHub repository and use Render blueprint

Self-Hosted with Docker

Create a docker-compose.prod.yml:

version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: hoppscotch
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    build:
      context: .
      dockerfile: Dockerfile.backend
    environment:
      DATABASE_URL: postgresql://postgres:${DB_PASSWORD}@postgres:5432/hoppscotch
      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379
      JWT_SECRET: ${JWT_SECRET}
      NODE_ENV: production
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "3001:3001"

  frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
    environment:
      VITE_BACKEND_URL: ${BACKEND_URL}
    ports:
      - "3000:80"
    depends_on:
      - backend

volumes:
  postgres_data:
  redis_data:

Deploy with:

docker-compose -f docker-compose.prod.yml up -d

Kubernetes

For production Kubernetes deployment, use the provided Helm chart or create Kubernetes manifests with:

PostgreSQL StatefulSet
Redis Deployment
Backend Deployment/Service
Frontend Deployment/Service
Ingress controller for routing

6. Troubleshooting

Common Issues

Database Connection Errors

# Error: Cannot connect to PostgreSQL
# Solution: Check if PostgreSQL is running and credentials are correct
psql -U postgres -h localhost -p 5432

# Reset database (development only)
cd packages/hoppscotch-backend
npx prisma migrate reset

Prisma Client Generation Issues

# Error: Prisma client not found
# Solution: Regenerate Prisma client
npx prisma generate

# Clear Prisma cache
rm -rf node_modules/.prisma
rm -rf node_modules/@prisma
npm install

Redis Connection Errors

# Test Redis connection
redis-cli ping
# Expected response: PONG

# If using Docker, ensure Redis container is running
docker ps | grep redis

Build Errors

# Clear node_modules and reinstall
rm -rf node_modules
rm -rf packages/*/node_modules
npm install

# Or with pnpm
pnpm install --force

Port Already in Use

# Find process using port 3000 or 3001
lsof -i :3000
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or change ports in .env file
PORT=3002

TypeScript Compilation Errors

# Clean and rebuild
npm run clean
npm run build

# Check TypeScript version compatibility
npm list typescript

Subscription/PubSub Issues

Ensure Redis is properly configured and accessible
Check WebSocket connections are not blocked by firewall
Verify CORS settings include WebSocket origins

Team Collection Errors

If encountering team collection errors like TEAM_COLL_CREATION_FAILED:

Verify user has proper team permissions
Check database constraints and foreign keys
Ensure collection data JSON is valid (use stringToJson helper)

Getting Help

Logs & Debugging

Enable verbose logging:

# Set debug environment variable
DEBUG=hoppscotch:* npm run dev

# Check backend logs
cd packages/hoppscotch-backend
npm run start:dev 2>&1 | tee backend.log

# Check frontend logs in browser console
# Press F12 → Console tab

How to Deploy & Use hoppscotch