How to Self-Host Hoppscotch with Docker Compose

What Is Hoppscotch?

Hoppscotch is an open-source API development ecosystem and Postman alternative. It supports REST, GraphQL, WebSocket, MQTT, and SSE testing with a clean, fast web UI. The self-hosted Community Edition gives you full control over your API collections and team workspaces without per-seat SaaS pricing.

Updated March 2026: Verified with latest Docker images and configurations.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 2 GB of free RAM (4 GB recommended)
• 5 GB of free disk space
• A domain name (recommended for OAuth callbacks)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  hoppscotch:
    image: hoppscotch/hoppscotch:2026.2.1
    container_name: hoppscotch
    restart: unless-stopped
    ports:
      - "3000:80"
    environment:
      # Database
      - DATABASE_URL=postgresql://hoppscotch:${DB_PASSWORD}@hoppscotch-db:5432/hoppscotch?connect_timeout=300
      # Encryption key — MUST be exactly 32 characters
      - DATA_ENCRYPTION_KEY=${DATA_ENCRYPTION_KEY}
      # Session secret — generate with: openssl rand -hex 32
      - JWT_SECRET=${JWT_SECRET}
      - TOKEN_SALT_COMPLEXITY=10
      - MAGIC_LINK_TOKEN_VALIDITY=3
      - REFRESH_TOKEN_VALIDITY=604800000
      - ACCESS_TOKEN_VALIDITY=86400000
      # CORS origins
      - WHITELISTED_ORIGINS=${APP_URL}
      # URLs — change to your domain
      - VITE_BASE_URL=${APP_URL}
      - VITE_SHORTCODE_BASE_URL=${APP_URL}
      - VITE_ADMIN_URL=${APP_URL}/admin
      - VITE_BACKEND_GQL_URL=${APP_URL}/backend/graphql
      - VITE_BACKEND_WS_URL=${WS_URL}/backend/graphql
      - VITE_BACKEND_API_URL=${APP_URL}/backend/v1
      # Subpath routing (all services on one port)
      - ENABLE_SUBPATH_BASED_ACCESS=true
      # Email (optional — required for magic link auth)
      - MAILER_SMTP_ENABLE=${SMTP_ENABLED:-false}
      - MAILER_SMTP_HOST=${SMTP_HOST:-}
      - MAILER_SMTP_PORT=${SMTP_PORT:-587}
      - MAILER_SMTP_USER=${SMTP_USER:-}
      - MAILER_SMTP_PASSWORD=${SMTP_PASSWORD:-}
      - MAILER_ADDRESS_FROM=${SMTP_FROM:[email protected]}
    depends_on:
      hoppscotch-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

  hoppscotch-db:
    image: postgres:16-alpine
    container_name: hoppscotch-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=hoppscotch
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=hoppscotch
    volumes:
      - hoppscotch_db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hoppscotch"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  hoppscotch_db:

Create a .env file alongside:

# Database password — generate with: openssl rand -hex 16
DB_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD

# Data encryption key — MUST be exactly 32 characters
# Generate with: openssl rand -hex 16
DATA_ENCRYPTION_KEY=CHANGE_ME_32_CHARS_EXACTLY_HERE

# JWT secret — generate with: openssl rand -hex 32
JWT_SECRET=CHANGE_ME_TO_RANDOM_64_CHAR_HEX

# Application URL — change to your domain
APP_URL=http://localhost:3000
WS_URL=ws://localhost:3000

# SMTP (optional — for magic link authentication)
SMTP_ENABLED=false
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_USER=your-smtp-user
# SMTP_PASSWORD=your-smtp-password
# [email protected]

Start the stack:

docker compose up -d

Initial Setup

1. Wait 30–60 seconds for database migrations to complete
2. Navigate to http://your-server:3000
3. Access the admin dashboard at http://your-server:3000/admin
4. Create the first admin account through the admin setup wizard
5. Configure authentication method (email magic link, GitHub OAuth, or Google OAuth)

The admin dashboard lets you manage users, teams, and global settings.

Configuration

OAuth Authentication (Recommended)

Add GitHub OAuth to your environment:

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-app-client-id
GITHUB_CLIENT_SECRET=your-github-app-client-secret
GITHUB_CALLBACK_URL=http://your-domain:3000/backend/v1/auth/github/callback
GITHUB_SCOPE=user:email

And add to the hoppscotch service environment in docker-compose.yml:

- GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
- GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
- GITHUB_CALLBACK_URL=${GITHUB_CALLBACK_URL}
- GITHUB_SCOPE=${GITHUB_SCOPE}

Google and Microsoft OAuth follow the same pattern with their respective variables.

Key Features

Feature	Details
REST API testing	Full request builder with headers, params, body, auth
GraphQL	Query builder with schema introspection
WebSocket	Real-time WebSocket connection testing
MQTT	IoT protocol testing support
SSE	Server-Sent Events testing
Collections	Organize requests into shared collections
Environments	Variable management across multiple environments
Team workspaces	Collaborate on API collections with role-based access
Request history	Automatic history of all requests
Pre-request scripts	JavaScript scripting before requests

Reverse Proxy

With ENABLE_SUBPATH_BASED_ACCESS=true, everything runs on a single port. Configure your reverse proxy to forward to port 80 with WebSocket support.

Nginx configuration note: You must enable WebSocket proxying for the /backend/graphql path:

location /backend/graphql {
    proxy_pass http://hoppscotch:80;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

For detailed setup, see Reverse Proxy Setup.

Backup

Back up the PostgreSQL database:

docker exec hoppscotch-db pg_dump -U hoppscotch hoppscotch > hoppscotch-backup-$(date +%Y%m%d).sql

Restore from backup:

cat hoppscotch-backup.sql | docker exec -i hoppscotch-db psql -U hoppscotch hoppscotch

For a comprehensive backup strategy, see Backup Strategy.

Troubleshooting

”connect_timeout” Database Errors

Symptom: Backend fails to start with PostgreSQL connection errors. Fix: Ensure your DATABASE_URL includes ?connect_timeout=300. The backend needs extra time for initial migrations.

WebSocket Connection Failed

Symptom: Real-time features don’t work, GraphQL subscriptions fail. Fix: Your reverse proxy must support WebSocket upgrades. Set proxy_buffering off and add the WebSocket upgrade headers.

Admin Dashboard Shows Blank Page

Symptom: /admin loads but shows nothing. Fix: Verify VITE_ADMIN_URL matches your actual admin URL. With subpath access, it should be https://your-domain/admin.

OAuth Callback Error

Symptom: “Invalid redirect_uri” after OAuth login attempt. Fix: The callback URL in your OAuth app settings must exactly match GITHUB_CALLBACK_URL (or Google/Microsoft equivalent), including the protocol and port.

Resource Requirements

• RAM: 500 MB idle, 1–2 GB under active use
• CPU: Low to moderate — 1 core minimum, 2 cores recommended
• Disk: 1 GB for application, plus database growth proportional to saved requests

Verdict

Hoppscotch is the best self-hosted Postman alternative if you want a clean, modern UI with team collaboration features. The all-in-one Docker image makes deployment straightforward, and the MIT license means no feature restrictions. It handles REST, GraphQL, and WebSocket testing well. For solo developers who prefer a desktop app, Bruno (Git-based, offline-first) is worth considering — but for teams sharing API collections, Hoppscotch wins.

Related

• Hoppscotch vs Insomnia: Which Should You Self-Host?
• Best Self-Hosted Development Tools
• Self-Hosted Alternatives to Postman
• Self-Hosted Alternatives to GitHub Codespaces
• How to Self-Host Code Server
• Code Server vs OpenVSCode Server
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy