Skip to content
Klutch.sh Docs

Deploying Hoppscotch

Introduction

Hoppscotch is a lightweight, open-source API development ecosystem that serves as an alternative to Postman. It provides a beautiful, fast, and free interface for testing REST, GraphQL, WebSocket, Server-Sent Events (SSE), and Socket.IO APIs. Deploying Hoppscotch on Klutch.sh gives you a self-hosted API testing platform with full control over your data, team collaboration features, and seamless integration with your development workflow.

This comprehensive guide walks you through deploying Hoppscotch on Klutch.sh using a Dockerfile, configuring environment variables, setting up persistent storage for collections and environments, and implementing production-ready best practices for scalability and security.

Prerequisites

  • A Klutch.sh account (sign up at klutch.sh/app)
  • A GitHub repository for your Hoppscotch deployment
  • Basic knowledge of Docker and API development tools
  • (Optional) PostgreSQL database for production deployments
  • (Optional) OAuth provider credentials (GitHub, Google, Microsoft) for authentication

Understanding Hoppscotch Architecture

Hoppscotch consists of two main components:

  1. Frontend Application: The Vue.js-based web interface that users interact with
  2. Backend Services (optional): Provides authentication, collections sync, and team collaboration features

For basic deployments, you can run just the frontend with local storage. For production deployments with team features, you’ll need both frontend and backend services with a PostgreSQL database.

Project Layout

A minimal repository layout for deploying Hoppscotch:

hoppscotch-deploy/
├── Dockerfile
├── .env.example
├── docker-compose.yml (for local testing only)
└── README.md

For production deployments, keep sensitive configuration in environment variables, not in the repository.

1. Basic Dockerfile (Frontend Only)

This Dockerfile creates a lightweight Hoppscotch frontend deployment suitable for individual use or small teams. It uses the official Hoppscotch Docker image as a base:

FROM hoppscotch/hoppscotch:latest


# Set environment variables for frontend
ENV VITE_ALLOWED_AUTH_PROVIDERS=GITHUB,GOOGLE,EMAIL
ENV VITE_BASE_URL=https://example-app.klutch.sh
ENV VITE_SHORTCODE_BASE_URL=https://example-app.klutch.sh


# Expose the application port
EXPOSE 3000


# The base image already contains the start command
# CMD is inherited from the base image

Notes:

  • The official Hoppscotch image listens on port 3000 by default
  • This basic setup stores data in the browser’s local storage
  • For team features and data persistence, you’ll need the backend services (see next section)

2. Production Dockerfile with Backend Services

For production deployments with authentication, collection syncing, and team collaboration, deploy both the frontend and backend:

Backend Service Dockerfile

FROM hoppscotch/hoppscotch-backend:latest


# The backend requires PostgreSQL connection
ENV DATABASE_URL=postgresql://YOUR_USERNAME:YOUR_PASSWORD@postgres-host:5432/hoppscotch
ENV JWT_SECRET=GENERATE_32_CHAR_RANDOM_STRING_HERE
ENV SESSION_SECRET=GENERATE_32_CHAR_RANDOM_STRING_HERE
ENV REDIRECT_URL=https://example-app.klutch.sh
ENV WHITELISTED_ORIGINS=https://example-app.klutch.sh
ENV VITE_ALLOWED_AUTH_PROVIDERS=GITHUB,GOOGLE,EMAIL


# GitHub OAuth (optional)
ENV GITHUB_CLIENT_ID=YOUR_GITHUB_CLIENT_ID
ENV GITHUB_CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET
ENV GITHUB_CALLBACK_URL=https://example-app.klutch.sh/v1/auth/github/callback


# Google OAuth (optional)
ENV GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
ENV GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
ENV GOOGLE_CALLBACK_URL=https://example-app.klutch.sh/v1/auth/google/callback


# SMTP Configuration (for email auth)
ENV MAILER_SMTP_HOST=smtp.example.com
ENV MAILER_SMTP_PORT=587
ENV MAILER_SMTP_USER=noreply@example.com
ENV MAILER_SMTP_PASSWORD=YOUR_SMTP_APP_PASSWORD
ENV MAILER_ADDRESS_FROM=noreply@example.com


# Expose backend port
EXPOSE 3100


# Start command is inherited from base image

Frontend Service with Backend Integration

FROM hoppscotch/hoppscotch:latest


# Configure frontend to use backend services
# Note: VITE_BACKEND_API_URL and VITE_BACKEND_WS_URL should point to your backend service URL
ENV VITE_BASE_URL=https://example-app.klutch.sh
ENV VITE_SHORTCODE_BASE_URL=https://example-app.klutch.sh
ENV VITE_BACKEND_API_URL=https://backend.example-app.klutch.sh
ENV VITE_BACKEND_WS_URL=wss://backend.example-app.klutch.sh
ENV VITE_ALLOWED_AUTH_PROVIDERS=GITHUB,GOOGLE,EMAIL


EXPOSE 3000

3. Environment Variables Configuration

Essential Variables for Frontend

Terminal window
# Base URLs
VITE_BASE_URL=https://example-app.klutch.sh
VITE_SHORTCODE_BASE_URL=https://example-app.klutch.sh


# Authentication providers (comma-separated)
VITE_ALLOWED_AUTH_PROVIDERS=GITHUB,GOOGLE,EMAIL

Essential Variables for Backend

Terminal window
# Database
DATABASE_URL=postgresql://YOUR_USERNAME:YOUR_PASSWORD@postgres-host:5432/hoppscotch


# Security (generate secure random strings - minimum 32 characters)
JWT_SECRET=GENERATE_32_CHAR_RANDOM_STRING_HERE
SESSION_SECRET=GENERATE_32_CHAR_RANDOM_STRING_HERE


# URLs
REDIRECT_URL=https://example-app.klutch.sh
WHITELISTED_ORIGINS=https://example-app.klutch.sh


# GitHub OAuth
GITHUB_CLIENT_ID=YOUR_GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET
GITHUB_CALLBACK_URL=https://example-app.klutch.sh/v1/auth/github/callback
GITHUB_SCOPE=user:email


# Google OAuth
GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
GOOGLE_CALLBACK_URL=https://example-app.klutch.sh/v1/auth/google/callback
GOOGLE_SCOPE=email,profile


# Email Configuration
MAILER_SMTP_ENABLE=true
MAILER_USE_CUSTOM_CONFIGS=true
MAILER_SMTP_HOST=smtp.example.com
MAILER_SMTP_PORT=587
MAILER_SMTP_SECURE=true
MAILER_SMTP_USER=noreply@example.com
MAILER_SMTP_PASSWORD=YOUR_SMTP_APP_PASSWORD
MAILER_ADDRESS_FROM=noreply@example.com


# Rate Limiting
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100

Important Security Notes:

  • Never commit secrets to your repository
  • Use Klutch.sh’s environment variable management to store sensitive values
  • Generate strong random strings for JWT_SECRET and SESSION_SECRET (minimum 32 characters)
  • Use secure SMTP credentials for email functionality

4. Persistent Storage Configuration

Hoppscotch stores user data differently depending on your deployment mode:

Frontend-Only Deployment

Data is stored in the browser’s local storage. No persistent volumes are needed, but users will lose data if they clear their browser cache.

Backend-Enabled Deployment

All user data is stored in the PostgreSQL database. You need persistent storage for:

  1. Database Volume: Mount a persistent volume for PostgreSQL data

    • Mount path: /var/lib/postgresql/data
    • Recommended size: 10GB (increases with usage)

  2. Backend Application Data (optional)

    • Mount path: /app/data
    • Recommended size: 5GB

Setting Up Volumes on Klutch.sh

When creating your app on Klutch.sh:

    1. Navigate to your app’s settings in the Klutch.sh dashboard
    2. Go to the “Volumes” section
    3. Create a new volume with the mount path /var/lib/postgresql/data
    4. Set the size to at least 10GB
    5. Save and restart your application

For more details, see the Volumes Guide.

5. Database Setup

For production deployments with backend services, you need a PostgreSQL database.

Option 1: Deploy PostgreSQL on Klutch.sh

    1. Create a new app in Klutch.sh for PostgreSQL
    2. Use the official PostgreSQL Docker image
    3. Attach a persistent volume to /var/lib/postgresql/data
    4. Set environment variables:
      Terminal window
      POSTGRES_DB=hoppscotch
      POSTGRES_USER=hoppscotch_user
      POSTGRES_PASSWORD=your-secure-password
    5. Configure TCP traffic on port 8000 (internal port: 5432)
    6. Note the connection details for your Hoppscotch backend configuration

For detailed PostgreSQL deployment instructions, see the PostgreSQL Guide.

Option 2: Use a Managed PostgreSQL Service

Use external services like AWS RDS, Google Cloud SQL, or DigitalOcean Managed Databases. Simply provide the connection URL in your DATABASE_URL environment variable.

6. Deploying to Klutch.sh — Step-by-Step

Deploying Frontend-Only (Basic Setup)

    1. Create a new GitHub repository and add the Dockerfile from section 1
    2. Commit and push your changes to GitHub
    3. Log in to the Klutch.sh dashboard at klutch.sh/app
    4. Create a new project (or use an existing one)
    5. Create a new app and connect your GitHub repository
    6. Klutch.sh will automatically detect the Dockerfile in the root directory
    7. Configure the internal port to 3000
    8. Select HTTP traffic type
    9. Add environment variables from section 3 (frontend variables)
    10. Click “Deploy” to build and start your Hoppscotch instance

Deploying Full Stack (Production Setup)

    1. First, deploy a PostgreSQL database (see section 5)
    2. Create a GitHub repository for the backend service with the backend Dockerfile
    3. In Klutch.sh, create a new app for the backend:
      • Connect your backend repository
      • Configure internal port to 3100
      • Select HTTP traffic type
      • Add all backend environment variables from section 3
      • Include the DATABASE_URL pointing to your PostgreSQL instance
      • Deploy the backend service
    4. Create a second GitHub repository for the frontend with the frontend Dockerfile
    5. In Klutch.sh, create a new app for the frontend:
      • Connect your frontend repository
      • Configure internal port to 3000
      • Select HTTP traffic type
      • Add frontend environment variables
      • Set VITE_BACKEND_API_URL to your backend’s Klutch.sh URL
      • Set VITE_BACKEND_WS_URL to your backend’s WebSocket URL
      • Deploy the frontend service
    6. Access your Hoppscotch instance at the frontend app’s URL

7. Configuring OAuth Authentication

To enable social login with GitHub or Google:

GitHub OAuth Setup

    1. Go to GitHub Developer Settings
    2. Click “New OAuth App”
    3. Fill in the application details:
      • Application name: Your Hoppscotch Instance
      • Homepage URL: https://example-app.klutch.sh
      • Authorization callback URL: https://example-app.klutch.sh/v1/auth/github/callback
    4. Click “Register application”
    5. Copy the Client ID and generate a new Client Secret
    6. Add these to your backend environment variables:
      Terminal window
      GITHUB_CLIENT_ID=your-client-id
      GITHUB_CLIENT_SECRET=your-client-secret
      GITHUB_CALLBACK_URL=https://example-app.klutch.sh/v1/auth/github/callback

Google OAuth Setup

    1. Go to Google Cloud Console
    2. Create a new project or select an existing one
    3. Navigate to “APIs & Services” > “Credentials”
    4. Click “Create Credentials” > “OAuth client ID”
    5. Configure the consent screen if prompted
    6. Select “Web application” as the application type
    7. Add authorized redirect URIs:
      • https://example-app.klutch.sh/v1/auth/google/callback
    8. Copy the Client ID and Client Secret
    9. Add these to your backend environment variables:
      Terminal window
      GOOGLE_CLIENT_ID=your-client-id
      GOOGLE_CLIENT_SECRET=your-client-secret
      GOOGLE_CALLBACK_URL=https://example-app.klutch.sh/v1/auth/google/callback

8. Custom Domain Configuration

To use your own domain with Hoppscotch:

    1. In the Klutch.sh dashboard, navigate to your app settings
    2. Go to the “Domains” section
    3. Click “Add Custom Domain”
    4. Enter your domain (e.g., api-tools.yourdomain.com)
    5. Configure your DNS provider to point to the Klutch.sh provided address
    6. Klutch.sh automatically manages TLS certificates for custom domains
    7. Update your environment variables to reflect the new domain:
      Terminal window
      VITE_BASE_URL=https://api-tools.yourdomain.com
      REDIRECT_URL=https://api-tools.yourdomain.com
      WHITELISTED_ORIGINS=https://api-tools.yourdomain.com
    8. Redeploy your application for the changes to take effect

For detailed instructions, see the Custom Domains Guide.

9. Getting Started with Hoppscotch

Once your Hoppscotch instance is deployed, you can start testing APIs immediately:

Testing a Simple REST API

    1. Open your Hoppscotch instance in a web browser
    2. In the request builder, enter a URL (e.g., https://api.github.com/users/octocat)
    3. Select the HTTP method (GET, POST, PUT, DELETE, etc.)
    4. Click “Send” to make the request
    5. View the response in the response panel

Creating and Saving Collections

    1. Click the “Collections” tab in the sidebar
    2. Click “New Collection” to create a collection
    3. Add requests to your collection by clicking “Add Request”
    4. Organize requests into folders for better management
    5. Collections are saved to your backend database (if enabled) or browser local storage

Sample API Request Example

Here’s a sample request to test your Hoppscotch instance with the JSONPlaceholder API:

GET https://jsonplaceholder.typicode.com/posts/1
Content-Type: application/json

Expected response:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur..."
}

Testing GraphQL APIs

    1. Switch to the “GraphQL” tab in Hoppscotch
    2. Enter a GraphQL endpoint (e.g., https://api.spacex.land/graphql/)
    3. Write your GraphQL query in the query editor
    4. Click “Run Query” to execute
    5. View the response and explore the schema

Sample GraphQL query:

query {
  launchesPast(limit: 5) {
    mission_name
    launch_date_local
    rocket {
      rocket_name
    }
  }
}

Testing WebSocket Connections

    1. Switch to the “Realtime” tab
    2. Select “WebSocket” as the protocol
    3. Enter a WebSocket URL (e.g., wss://echo.websocket.org)
    4. Click “Connect”
    5. Send messages and receive responses in real-time

10. Customization with Nixpacks

Klutch.sh uses Nixpacks for automatic builds. If you need to customize the build or runtime behavior, you can set environment variables:

Custom Build Command

If you need to run custom build steps:

Terminal window
# Buildtime environment variable
NIXPACKS_BUILD_CMD=npm install && npm run build

Custom Start Command

To override the default start command:

Terminal window
# Runtime environment variable
NIXPACKS_START_CMD=node server.js

Install Additional Packages

To install system dependencies:

Terminal window
# Buildtime environment variable
NIXPACKS_PKGS=postgresql openssl

For more information on Nixpacks customization, see the Nixpacks documentation.

11. Monitoring and Scaling

Performance Monitoring

    1. Monitor your app’s resource usage in the Klutch.sh dashboard
    2. Track response times and error rates
    3. Set up alerts for high CPU or memory usage
    4. Review application logs for errors and performance issues

For detailed monitoring features, see the Monitoring Guide.

Scaling Considerations

  • Vertical Scaling: Increase instance size for more CPU and memory
  • Database Performance: Ensure your PostgreSQL instance is appropriately sized
  • Connection Pooling: Use connection pooling for database connections in high-traffic scenarios
  • Caching: Consider implementing Redis caching for frequently accessed data

12. Troubleshooting

Common Issues and Solutions

Issue: Application won’t start

  • Check logs in the Klutch.sh dashboard for error messages
  • Verify all required environment variables are set
  • Ensure the internal port is correctly configured to 3000 (frontend) or 3100 (backend)
  • Confirm the Dockerfile is in the root directory of your repository

Issue: Cannot connect to database

  • Verify the DATABASE_URL is correct and includes proper credentials
  • Ensure the PostgreSQL service is running and accessible
  • Check network connectivity between services
  • For Klutch.sh PostgreSQL deployments, ensure you’re using port 8000 for external connections

Issue: OAuth authentication fails

  • Double-check OAuth client IDs and secrets
  • Verify callback URLs match exactly in both OAuth provider settings and environment variables
  • Ensure REDIRECT_URL and WHITELISTED_ORIGINS are set correctly
  • Check that your domain has valid TLS certificates

Issue: WebSocket connections fail

  • Verify VITE_BACKEND_WS_URL uses wss:// (secure WebSocket) protocol
  • Check that the backend service is running and accessible
  • Ensure no proxy or firewall is blocking WebSocket connections

Issue: Collections not saving

  • For frontend-only deployments, check browser local storage permissions
  • For backend deployments, verify database connection is working
  • Check application logs for database errors
  • Ensure the backend service is properly configured and running

Debugging Commands

To troubleshoot issues, you can review logs in the Klutch.sh dashboard or use the following approaches:

Terminal window
# Check if the application is listening on the correct port
netstat -tulpn | grep 3000


# Verify environment variables are set
env | grep VITE


# Test database connectivity (from backend container)
psql $DATABASE_URL -c "SELECT version();"


# Check application logs
tail -f /var/log/hoppscotch/app.log

13. Security Best Practices

    1. Use Strong Secrets: Generate cryptographically secure random strings for JWT_SECRET and SESSION_SECRET (minimum 32 characters)
    2. Enable HTTPS: Always use HTTPS for your Hoppscotch instance (Klutch.sh provides this automatically)
    3. Secure Database: Use strong database passwords and restrict network access
    4. OAuth Security: Keep OAuth client secrets confidential and rotate them periodically
    5. SMTP Credentials: Use app-specific passwords for SMTP authentication
    6. Regular Updates: Keep Hoppscotch and its dependencies up to date
    7. Access Control: Implement team workspaces and role-based access control for production use
    8. Environment Variables: Never commit secrets to your repository; use Klutch.sh’s environment variable management
    9. CORS Configuration: Properly configure WHITELISTED_ORIGINS to prevent unauthorized access
    10. Rate Limiting: Configure appropriate rate limits to prevent abuse

14. Backup and Data Management

Database Backups

For PostgreSQL deployments, implement regular backups:

Terminal window
# Create a backup
pg_dump $DATABASE_URL > hoppscotch-backup-$(date +%Y%m%d).sql


# Restore from backup
psql $DATABASE_URL < hoppscotch-backup-20240101.sql

Exporting Collections

Users can export their collections as JSON files from the Hoppscotch UI:

    1. Navigate to Collections
    2. Click on the collection menu (three dots)
    3. Select “Export”
    4. Choose JSON format
    5. Save the file securely

Automated Backup Strategy

Consider implementing automated backups:

  • Schedule daily database dumps
  • Store backups in object storage (S3-compatible)
  • Implement backup retention policies (keep daily backups for 7 days, weekly for 4 weeks, monthly for 12 months)
  • Test restore procedures regularly

15. Migration from Hosted Hoppscotch

If you’re migrating from the hosted Hoppscotch service:

    1. Export all collections from the hosted service
    2. Deploy your self-hosted instance following this guide
    3. Create user accounts on your self-hosted instance
    4. Import collections using the import feature
    5. Update team settings and permissions
    6. Notify team members of the new URL

16. Advanced Configuration

Environment-Specific Settings

Use different environment variables for development, staging, and production:

Terminal window
# Development
VITE_BASE_URL=https://dev.example-app.klutch.sh
NODE_ENV=development


# Production
VITE_BASE_URL=https://api.example-app.klutch.sh
NODE_ENV=production

Custom Themes

Hoppscotch supports custom theming. You can extend the frontend build to include custom themes:

  1. Fork the Hoppscotch repository
  2. Customize theme files in the source
  3. Build your custom image
  4. Deploy to Klutch.sh

Proxy Configuration

For testing APIs behind firewalls or with CORS restrictions, configure the Hoppscotch proxy:

Terminal window
# Backend environment variable
PROXY_ENABLED=true

17. Resources and Documentation

Conclusion

Deploying Hoppscotch on Klutch.sh provides a powerful, self-hosted API development platform with full control over your data and infrastructure. Whether you’re running a simple frontend-only deployment for personal use or a full production setup with authentication and team collaboration, Klutch.sh’s automatic Dockerfile detection and managed infrastructure make deployment straightforward.

For production deployments, remember to:

  • Use PostgreSQL for data persistence
  • Configure OAuth providers for team authentication
  • Implement regular database backups
  • Monitor resource usage and scale as needed
  • Keep Hoppscotch and dependencies updated

With Hoppscotch deployed on Klutch.sh, you have a reliable, scalable API testing platform that grows with your needs.