# Hoppscotch

> Open source API development ecosystem.

- Category: Development Tools
- Difficulty: intermediate
- Components: hoppscotch, postgres
- Tags: hoppscotch, api, client, postman-alternative
- Source: https://docker.recipes/development/hoppscotch

## Overview

Hoppscotch is an open-source API development ecosystem that serves as a modern, lightweight alternative to Postman. Originally known as Postwoman before rebranding, it provides a comprehensive platform for testing REST APIs, GraphQL endpoints, WebSockets, and Server-Sent Events through an intuitive web interface. The platform emphasizes real-time collaboration, offline functionality through Progressive Web App (PWA) capabilities, and team-based workspace management for API development workflows.

This deployment configuration creates a complete Hoppscotch environment using two services: the main Hoppscotch application container that includes both frontend and backend components, and a dedicated PostgreSQL database for persistent data storage. The Hoppscotch container exposes both port 3000 for the web interface and port 3100 for the backend API, while the PostgreSQL database handles user accounts, API collections, team workspaces, and collaboration data with full ACID compliance.

This stack is ideal for development teams seeking to self-host their API testing infrastructure, organizations requiring data sovereignty for their API development workflows, and teams that need collaborative API testing without relying on external SaaS platforms. The combination provides enterprise-grade data persistence through PostgreSQL while maintaining the modern, fast user experience that makes Hoppscotch a compelling Postman alternative.

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

## Use cases

- Development teams transitioning from Postman to a self-hosted API testing solution
- Organizations requiring on-premises API development tools for compliance or security policies
- Startup teams building REST and GraphQL APIs who need collaborative testing workflows
- Remote development teams needing shared API collections and real-time collaboration features
- Companies developing WebSocket-based applications requiring specialized connection testing
- Educational institutions teaching API development with controlled, self-hosted environments
- Enterprise 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

```yaml
services:
  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

volumes:
  hoppscotch_db:
```

## .env

```bash
DB_PASSWORD=changeme
JWT_SECRET=generate-long-secret
SESSION_SECRET=generate-another-secret
```

## Usage notes

- Docs: https://docs.hoppscotch.io/
- Access at http://localhost:3000 (frontend), :3100 (backend)
- Open-source Postman alternative with real-time collaboration
- Supports REST, GraphQL, WebSocket, and SSE testing
- Team workspaces with shared collections
- PWA support - works offline after initial load

## Troubleshooting

- Database connection failed: Verify DB_PASSWORD environment variable matches between hoppscotch and db services, and ensure PostgreSQL container is fully started
- Port 3000 or 3100 already in use: Check for conflicting services with 'netstat -tulpn | grep :3000' and modify port mappings in docker-compose.yml if needed
- JWT authentication errors: Ensure JWT_SECRET and SESSION_SECRET environment variables are set with sufficient entropy (minimum 32 characters recommended)
- Collections not persisting between restarts: Verify the hoppscotch_db volume is properly mounted and PostgreSQL container has write permissions
- WebSocket connections failing: Check that port 3100 is accessible and not blocked by firewall rules, as WebSocket connections use the backend service
- Slow API response testing: Monitor PostgreSQL performance with 'docker stats hoppscotch-db' and consider increasing available memory if database queries are bottlenecking

