Codakey
Play
← Back to hoppscotch/hoppscotch

How to Deploy & Use hoppscotch/hoppscotch

Hoppscotch Deployment & Usage Guide

1. Prerequisites

Runtime & Tools:

  • Node.js (v18 or later) - JavaScript runtime
  • npm or yarn or pnpm - Package manager
  • Git - Version control
  • Docker & Docker Compose (optional, for containerized deployment)
  • PostgreSQL (for backend persistence)

Development Tools:

  • TypeScript (included as dev dependency)
  • NestJS CLI (for backend development)
  • Vue.js ecosystem tools (for frontend development)

Accounts (Optional):

  • GitHub account (for OAuth/GitHub Gist integration)
  • Cloud provider account (for deployment: Vercel, Railway, AWS, etc.)

2. Installation

Clone the repository:

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

Install dependencies:

# Using npm (recommended)
npm install

# Or using yarn
yarn install

# Or using pnpm
pnpm install

Install workspace dependencies:

# Install dependencies for all workspaces
npm run bootstrap

3. Configuration

Environment Variables:

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

# Database Configuration (PostgreSQL)
DATABASE_URL=postgresql://username:password@localhost:5432/hoppscotch
DIRECT_URL=postgresql://username:password@localhost:5432/hoppscotch

# Authentication
JWT_SECRET=your-jwt-secret-key-here
GITHUB_OAUTH_CLIENT_ID=your-github-client-id
GITHUB_OAUTH_CLIENT_SECRET=your-github-client-secret
GOOGLE_OAUTH_CLIENT_ID=your-google-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-google-client-secret

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

# File Upload (if using S3)
S3_ACCESS_KEY_ID=your-s3-access-key
S3_SECRET_ACCESS_KEY=your-s3-secret-key
S3_BUCKET_NAME=your-bucket-name
S3_REGION=your-region

# Email (optional, for notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

Database Setup:

  1. Install PostgreSQL locally or use a cloud provider
  2. Create a database:
CREATE DATABASE hoppscotch;
  1. Run database migrations:
# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma db push
# or
npx prisma migrate dev

4. Build & Run

Development Mode:

# Start both frontend and backend in development mode
npm run dev

# Or start them separately:

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

# Frontend only
cd packages/hoppscotch-common
npm run dev

Production Build:

# Build all packages
npm run build

# Build specific packages:
npm run build:backend
npm run build:common
npm run build:cli

Run Production Build:

# Start the production server
npm run start:prod

# Or using Docker:
docker-compose up -d

Run Tests:

# Run all tests
npm test

# Run specific test suites
npm run test:backend
npm run test:common
npm run test:e2e

5. Deployment

Option 1: Docker Deployment (Recommended)

# Build Docker image
docker build -t hoppscotch .

# Run with Docker Compose
docker-compose up -d

# Docker Compose configuration should include:
# - PostgreSQL service
# - Backend service
# - Frontend service (or use static build)

Option 2: Platform-as-a-Service

Vercel (Frontend):

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Railway (Backend + Database):

# Install Railway CLI
npm i -g @railway/cli

# Link project
railway link

# Deploy
railway up

Option 3: Traditional Server Deployment

  1. Build the application:
npm run build
  1. Set up a reverse proxy (Nginx example):
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        root /path/to/hoppscotch/packages/hoppscotch-common/dist;
        try_files $uri $uri/ /index.html;
    }
    
    location /api {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
  1. Use PM2 for process management:
# Install PM2 globally
npm install -g pm2

# Start backend
pm2 start packages/hoppscotch-backend/dist/main.js --name hoppscotch-backend

# Start frontend (if using Node server)
pm2 start packages/hoppscotch-common/server.js --name hoppscotch-frontend

Option 4: Static Deployment

For frontend-only deployment (using cloud backend):

# Build static files
cd packages/hoppscotch-common
npm run build:static

# Deploy to any static hosting:
# - GitHub Pages
# - Netlify
# - Cloudflare Pages
# - AWS S3 + CloudFront

6. Troubleshooting

Common Issues:

  1. Database Connection Errors:
Error: P1001: Can't reach database server
  • Verify PostgreSQL is running: sudo systemctl status postgresql
  • Check DATABASE_URL in .env file
  • Ensure database exists: psql -U username -c "\l"
  1. Port Already in Use:
Error: listen EADDRINUSE: address already in use :::3000
  • Change PORT in .env file
  • Find and kill the process: lsof -ti:3000 | xargs kill -9
  1. Build Failures:
TypeScript compilation errors
  • Clear node_modules and reinstall: rm -rf node_modules && npm install
  • Update TypeScript: npm install typescript@latest
  • Check for type mismatches in source files
  1. Prisma Client Generation Issues:
Error: PrismaClient is unable to run in this browser environment
  • Ensure you're running npx prisma generate in the backend package
  • Check prisma/schema.prisma for syntax errors
  1. Authentication Issues:
  • Verify JWT_SECRET is set and sufficiently long
  • Check OAuth callback URLs match your deployment URL
  • Ensure CORS is properly configured in backend
  1. Collection Import/Export Errors:
  • For JSON import errors, validate the JSON structure matches Hoppscotch schema
  • Check file encoding (UTF-8 recommended)
  • Ensure the imported file doesn't exceed size limits
  1. WebSocket/Real-time Features Not Working:
  • Verify WebSocket server is running on correct port
  • Check firewall settings allow WebSocket connections
  • Ensure reverse proxy is configured for WebSocket upgrades

Debugging Tips:

  • Enable verbose logging: Set DEBUG=* in environment variables
  • Check application logs: pm2 logs hoppscotch-backend
  • Use browser developer tools for frontend issues
  • Monitor database queries with Prisma Studio: npx prisma studio
  • Test API endpoints directly with curl or Postman

Getting Help:

← Project overviewView alternatives to hoppscotch/hoppscotch →