# Hoppscotch API Testing

> Open source API development ecosystem - Postman alternative.

- Category: Development Tools
- Difficulty: beginner
- Components: hoppscotch, postgresql, smtp4dev
- Tags: hoppscotch, api-testing, postman, rest, graphql
- Source: https://docker.recipes/development/hoppscotch-api

## 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.

## 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

## Use cases

- API-first development teams transitioning from Postman to a self-hosted solution for enhanced privacy and control
- Enterprise organizations requiring on-premises API testing tools that comply with strict data governance policies
- Development agencies managing multiple client API projects with separate workspaces and team access controls
- Microservices architectures where teams need to test complex inter-service communication and authentication flows
- Educational institutions teaching API development and testing methodologies in controlled environments
- Startups building API products who need comprehensive testing capabilities without recurring SaaS subscription costs
- DevOps 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    image: rnwood/smtp4dev:latest
    ports:
      - "5000:80"
    networks:
      - hoppscotch-net
    restart: unless-stopped

volumes:
  postgres_data:

networks:
  hoppscotch-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=hoppscotch
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=hoppscotch

# Hoppscotch
JWT_SECRET=$(openssl rand -hex 32)
SESSION_SECRET=$(openssl rand -hex 32)
```

## Usage notes

- Hoppscotch at http://localhost:3000
- Admin at http://localhost:3100
- Backend at http://localhost:3170
- SMTP4Dev for email testing at http://localhost:5000

## 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

