How to Self-Host Hoppscotch API Development Environment

What Is Hoppscotch?

Hoppscotch is an open-source API development ecosystem. It provides a fast, lightweight interface for building, testing, and documenting HTTP, WebSocket, GraphQL, SSE, and MQTT requests. Self-hosting gives your team a shared workspace with collections, environments, and team collaboration features.

Prerequisites

• A Breeze with at least 2 GB RAM running Ubuntu 22.04+
• Docker and Docker Compose installed
• A domain name pointed to your Breeze

Docker Compose Setup

mkdir -p ~/hoppscotch && cd ~/hoppscotch

version: "3.8"
services:
  hoppscotch:
    image: hoppscotch/hoppscotch:latest
    container_name: hoppscotch
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "3100:3100"
      - "3170:3170"
    environment:
      - DATABASE_URL=postgresql://hoppscotch:HoppPass123@hoppscotch-db:5432/hoppscotch
      - MAILER_SMTP_ENABLE=false
      - INFRA_TOKEN_SALT=replace-with-random-salt
      - JWT_SECRET=replace-with-random-jwt-secret
      - SESSION_SECRET=replace-with-random-session-secret
    depends_on:
      - hoppscotch-db

  hoppscotch-db:
    image: postgres:16-alpine
    container_name: hoppscotch-db
    restart: unless-stopped
    volumes:
      - hoppscotch_db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=hoppscotch
      - POSTGRES_USER=hoppscotch
      - POSTGRES_PASSWORD=HoppPass123

volumes:
  hoppscotch_db:

Launch and Initialize

docker compose up -d
docker exec hoppscotch pnpx prisma migrate deploy

Access the web app at http://your-breeze-ip:3000, the admin dashboard at port 3100, and the backend API at port 3170. Create your admin account through the admin dashboard.

Key Features

• Shared collections and team workspaces for collaborative API development
• Environment variables with secret masking
• Pre-request scripts and test assertions
• Import and export collections in OpenAPI and other formats
• Real-time WebSocket, SSE, GraphQL, and MQTT testing