Hoppscotch API Testing

beginner

Open source API development ecosystem - Postman alternative.

Overview

Hoppscotch is an open-source API development ecosystem that serves as a modern alternative to Postman, providing a lightweight yet powerful interface for testing REST APIs, GraphQL endpoints, WebSocket connections, and more. Originally created as Postwoman before rebranding, Hoppscotch offers both web-based and self-hosted solutions for API testing, making it particularly attractive for teams seeking privacy, customization, and complete control over their API testing infrastructure. This stack combines Hoppscotch's multi-port architecture with PostgreSQL for robust data persistence and SMTP4Dev for comprehensive email testing capabilities. The configuration exposes three distinct Hoppscotch services: the main application interface on port 3000, an administrative dashboard on port 3100, and the backend API on port 3170, while PostgreSQL handles user data, workspace configurations, and API collections with full ACID compliance. SMTP4Dev provides a local email testing environment, capturing and displaying all outbound emails from Hoppscotch notifications, user invitations, and password reset workflows without requiring external email services. This combination is ideal for development teams, API-first companies, and organizations that need a self-hosted API testing solution with complete email workflow testing, offering enterprise-grade features while maintaining the flexibility and privacy that comes with self-hosted infrastructure.

Key Features

Multi-service Hoppscotch architecture with separate frontend, admin panel, and backend API endpoints
PostgreSQL-backed persistent storage for API collections, workspace data, and user authentication with full ACID compliance
Integrated SMTP4Dev email testing server for capturing and viewing registration, invitation, and notification emails
RESTful API testing with support for various HTTP methods, headers, authentication schemes, and response validation
GraphQL query and mutation testing with schema introspection and real-time query building
WebSocket connection testing for real-time API endpoints and bidirectional communication protocols
Team collaboration features with workspace sharing, user management, and role-based access controls
Environment variable management for testing across development, staging, and production API endpoints

Common Use Cases

1API-first development teams transitioning from Postman to a self-hosted solution for enhanced privacy and control
2Enterprise organizations requiring on-premises API testing tools that comply with strict data governance policies
3Development agencies managing multiple client API projects with separate workspaces and team access controls
4Microservices architectures where teams need to test complex inter-service communication and authentication flows
5Educational institutions teaching API development and testing methodologies in controlled environments
6Startups building API products who need comprehensive testing capabilities without recurring SaaS subscription costs
7DevOps teams integrating API testing into CI/CD pipelines with programmatic access to collections and test results

Prerequisites

Docker and Docker Compose installed with at least 2GB available RAM for PostgreSQL and Hoppscotch services
Ports 3000, 3100, 3170, and 5000 available on the host system for web interfaces and email testing
Basic understanding of API testing concepts including REST, GraphQL, and HTTP authentication methods
Environment variables configured for JWT_SECRET, SESSION_SECRET, and PostgreSQL credentials
Familiarity with PostgreSQL administration for potential database maintenance and backup procedures
Network access requirements for testing external APIs while maintaining isolated internal service communication

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  hoppscotch: 
3    image: hoppscotch/hoppscotch:latest
4    ports: 
5      - "3000:3000"
6      - "3100:3100"
7      - "3170:3170"
8    environment: 
9      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
10      JWT_SECRET: ${JWT_SECRET}
11      SESSION_SECRET: ${SESSION_SECRET}
12      MAILER_SMTP_HOST: smtp4dev
13      MAILER_SMTP_PORT: 25
14      MAILER_ADDRESS: noreply@hoppscotch.local
15    depends_on: 
16      postgres: 
17        condition: service_healthy
18    networks: 
19      - hoppscotch-net
20    restart: unless-stopped
21
22  postgres: 
23    image: postgres:16-alpine
24    environment: 
25      POSTGRES_USER: ${POSTGRES_USER}
26      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
27      POSTGRES_DB: ${POSTGRES_DB}
28    volumes: 
29      - postgres_data:/var/lib/postgresql/data
30    healthcheck: 
31      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
32      interval: 10s
33      timeout: 5s
34      retries: 5
35    networks: 
36      - hoppscotch-net
37    restart: unless-stopped
38
39  smtp4dev: 
40    image: rnwood/smtp4dev:latest
41    ports: 
42      - "5000:80"
43    networks: 
44      - hoppscotch-net
45    restart: unless-stopped
46
47volumes: 
48  postgres_data: 
49
50networks: 
51  hoppscotch-net: 
52    driver: bridge

.env Template

.env

1# PostgreSQL
2POSTGRES_USER=hoppscotch
3POSTGRES_PASSWORD=secure_postgres_password
4POSTGRES_DB=hoppscotch
5
6# Hoppscotch
7JWT_SECRET=$(openssl rand -hex 32)
8SESSION_SECRET=$(openssl rand -hex 32)

Usage Notes

1Hoppscotch at http://localhost:3000
2Admin at http://localhost:3100
3Backend at http://localhost:3170
4SMTP4Dev for email testing at http://localhost:5000

Individual Services(3 services)

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

hoppscotch

hoppscotch:
  image: hoppscotch/hoppscotch:latest
  ports:
    - "3000:3000"
    - "3100:3100"
    - "3170:3170"
  environment:
    DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
    JWT_SECRET: ${JWT_SECRET}
    SESSION_SECRET: ${SESSION_SECRET}
    MAILER_SMTP_HOST: smtp4dev
    MAILER_SMTP_PORT: 25
    MAILER_ADDRESS: noreply@hoppscotch.local
  depends_on:
    postgres:
      condition: service_healthy
  networks:
    - hoppscotch-net
  restart: unless-stopped

postgres

postgres:
  image: postgres:16-alpine
  environment:
    POSTGRES_USER: ${POSTGRES_USER}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    POSTGRES_DB: ${POSTGRES_DB}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  healthcheck:
    test:
      - CMD-SHELL
      - pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}
    interval: 10s
    timeout: 5s
    retries: 5
  networks:
    - hoppscotch-net
  restart: unless-stopped

smtp4dev

smtp4dev:
  image: rnwood/smtp4dev:latest
  ports:
    - "5000:80"
  networks:
    - hoppscotch-net
  restart: unless-stopped

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  hoppscotch:
5    image: hoppscotch/hoppscotch:latest
6    ports:
7      - "3000:3000"
8      - "3100:3100"
9      - "3170:3170"
10    environment:
11      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
12      JWT_SECRET: ${JWT_SECRET}
13      SESSION_SECRET: ${SESSION_SECRET}
14      MAILER_SMTP_HOST: smtp4dev
15      MAILER_SMTP_PORT: 25
16      MAILER_ADDRESS: noreply@hoppscotch.local
17    depends_on:
18      postgres:
19        condition: service_healthy
20    networks:
21      - hoppscotch-net
22    restart: unless-stopped
23
24  postgres:
25    image: postgres:16-alpine
26    environment:
27      POSTGRES_USER: ${POSTGRES_USER}
28      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
29      POSTGRES_DB: ${POSTGRES_DB}
30    volumes:
31      - postgres_data:/var/lib/postgresql/data
32    healthcheck:
33      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
34      interval: 10s
35      timeout: 5s
36      retries: 5
37    networks:
38      - hoppscotch-net
39    restart: unless-stopped
40
41  smtp4dev:
42    image: rnwood/smtp4dev:latest
43    ports:
44      - "5000:80"
45    networks:
46      - hoppscotch-net
47    restart: unless-stopped
48
49volumes:
50  postgres_data:
51
52networks:
53  hoppscotch-net:
54    driver: bridge
55EOF
56
57# 2. Create the .env file
58cat > .env << 'EOF'
59# PostgreSQL
60POSTGRES_USER=hoppscotch
61POSTGRES_PASSWORD=secure_postgres_password
62POSTGRES_DB=hoppscotch
63
64# Hoppscotch
65JWT_SECRET=$(openssl rand -hex 32)
66SESSION_SECRET=$(openssl rand -hex 32)
67EOF
68
69# 3. Start the services
70docker compose up -d
71
72# 4. View logs
73docker compose logs -f

One-Liner

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

terminal

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

Troubleshooting

Hoppscotch admin panel shows database connection errors: Verify PostgreSQL health check is passing and DATABASE_URL environment variable matches postgres service credentials
CORS errors when testing localhost APIs: Configure Hoppscotch proxy settings or use the desktop app for local API testing without browser restrictions
Email notifications not appearing in SMTP4Dev: Check that MAILER_SMTP_HOST points to smtp4dev service name and port 25 is correctly configured
PostgreSQL data loss after container restart: Ensure postgres_data volume is properly mounted and has correct permissions for the postgres user
JWT token validation failures: Regenerate JWT_SECRET and SESSION_SECRET environment variables with sufficient entropy (32+ character random strings)
GraphQL schema introspection failing: Verify target GraphQL endpoint allows introspection queries and authentication headers are properly configured in Hoppscotch

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

hoppscotchpostgresqlsmtp4dev

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download