Hoppscotch

Key Features

• Multi-protocol API testing supporting REST, GraphQL, WebSocket, and Server-Sent Events in a unified interface
• Real-time collaborative workspaces with shared collections and team-based permission management
• Progressive Web App functionality enabling offline API testing after initial load
• PostgreSQL-backed persistence for reliable storage of API collections, environments, and user data
• Dual-port architecture with separate frontend (3000) and backend (3100) services for flexible deployment
• Built-in request/response history tracking with full audit trails stored in PostgreSQL
• Environment variable management with secure storage and team-level sharing capabilities
• WebSocket connection testing with real-time message streaming and connection state monitoring

Common Use Cases

• 1Development teams transitioning from Postman to a self-hosted API testing solution
• 2Organizations requiring on-premises API development tools for compliance or security policies
• 3Startup teams building REST and GraphQL APIs who need collaborative testing workflows
• 4Remote development teams needing shared API collections and real-time collaboration features
• 5Companies developing WebSocket-based applications requiring specialized connection testing
• 6Educational institutions teaching API development with controlled, self-hosted environments
• 7Enterprise environments where external API testing services are restricted by corporate policies

Prerequisites

• Docker and Docker Compose installed with support for multi-container orchestration
• Minimum 1GB RAM available for PostgreSQL database operations and query processing
• Ports 3000 and 3100 available on the host system for Hoppscotch frontend and backend access
• Basic understanding of environment variables for JWT_SECRET, SESSION_SECRET, and DB_PASSWORD configuration
• Familiarity with API testing concepts including REST, GraphQL, and WebSocket protocols
• Network access for initial Docker image pulls (hoppscotch/hoppscotch:latest and postgres:15-alpine)

docker-compose.yml

1services: 
2  hoppscotch: 
3    image: hoppscotch/hoppscotch:latest
4    container_name: hoppscotch
5    restart: unless-stopped
6    environment: 
7      DATABASE_URL: postgres://hoppscotch:${DB_PASSWORD}@db:5432/hoppscotch
8      JWT_SECRET: ${JWT_SECRET}
9      SESSION_SECRET: ${SESSION_SECRET}
10    ports: 
11      - "3000:3000"
12      - "3100:3100"
13    depends_on: 
14      - db
15
16  db: 
17    image: postgres:15-alpine
18    container_name: hoppscotch-db
19    environment: 
20      POSTGRES_USER: hoppscotch
21      POSTGRES_PASSWORD: ${DB_PASSWORD}
22      POSTGRES_DB: hoppscotch
23    volumes: 
24      - hoppscotch_db:/var/lib/postgresql/data
25
26volumes: 
27  hoppscotch_db: 

.env Template

1DB_PASSWORD=changeme
2JWT_SECRET=generate-long-secret
3SESSION_SECRET=generate-another-secret

Usage Notes

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

hoppscotch:
  image: hoppscotch/hoppscotch:latest
  container_name: hoppscotch
  restart: unless-stopped
  environment:
    DATABASE_URL: postgres://hoppscotch:${DB_PASSWORD}@db:5432/hoppscotch
    JWT_SECRET: ${JWT_SECRET}
    SESSION_SECRET: ${SESSION_SECRET}
  ports:
    - "3000:3000"
    - "3100:3100"
  depends_on:
    - db

db:
  image: postgres:15-alpine
  container_name: hoppscotch-db
  environment:
    POSTGRES_USER: hoppscotch
    POSTGRES_PASSWORD: ${DB_PASSWORD}
    POSTGRES_DB: hoppscotch
  volumes:
    - hoppscotch_db:/var/lib/postgresql/data

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  hoppscotch:
5    image: hoppscotch/hoppscotch:latest
6    container_name: hoppscotch
7    restart: unless-stopped
8    environment:
9      DATABASE_URL: postgres://hoppscotch:${DB_PASSWORD}@db:5432/hoppscotch
10      JWT_SECRET: ${JWT_SECRET}
11      SESSION_SECRET: ${SESSION_SECRET}
12    ports:
13      - "3000:3000"
14      - "3100:3100"
15    depends_on:
16      - db
17
18  db:
19    image: postgres:15-alpine
20    container_name: hoppscotch-db
21    environment:
22      POSTGRES_USER: hoppscotch
23      POSTGRES_PASSWORD: ${DB_PASSWORD}
24      POSTGRES_DB: hoppscotch
25    volumes:
26      - hoppscotch_db:/var/lib/postgresql/data
27
28volumes:
29  hoppscotch_db:
30EOF
31
32# 2. Create the .env file
33cat > .env << 'EOF'
34DB_PASSWORD=changeme
35JWT_SECRET=generate-long-secret
36SESSION_SECRET=generate-another-secret
37EOF
38
39# 3. Start the services
40docker compose up -d
41
42# 4. View logs
43docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/hoppscotch/run | bash

Troubleshooting