Self-hosting Hoppscotch gives you complete control over your API development workflow and will allow you to run Hoppscotch on your own servers, giving you more control over your data and security.

This guide covers the basics of self-hosting Hoppscotch, including the necessary configurations and settings you need to get started. You can install and run Hoppscotch on any operating system that can run a Docker Engine, but you will need a 4 CPU core machine with at least 16 GB of RAM to build the docker images. However, you can use a 1 CPU core machine with 2GB of RAM to host the generated output files.

Before we get started with the setup, we're excited to announce that we are working on an enterprise edition of Hoppscotch. Fill out the form here to be the first to know when it's launched!

Prerequisites

To get started with self-hosting Hoppscotch, make sure you have the following prerequisites in place:

1. node.js & npm
2. pnpm
3. docker
4. git

Visit our documentation for a detailed guide on installing the prerequisite softwares.

Cloning the repository

Now that you have all the necessary tools to get started with the installation, let's begin by cloning the Hoppscotch GitHub repository. You can clone the repository locally using git by running the following command in your terminal:

git clone https://github.com/hoppscotch/hoppscotch.git

Alternatively, you can use GitHub CLI to clone the repository:

gh repo clone hoppscotch/hoppscotch

Configuring Environment Variables

Before building the Docker image and using Hoppscotch locally, you need to configure a few environment variables. Create a new file within the root directory of the repository called .env and paste the following configurations:

#-----------------------Backend Config------------------------------#
# Prisma Config
DATABASE_URL=postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch # or replace with your database URL 

# Auth Tokens Config
JWT_SECRET="secretcode123"
TOKEN_SALT_COMPLEXITY=10
MAGIC_LINK_TOKEN_VALIDITY= 3
REFRESH_TOKEN_VALIDITY="604800000" # Default validity is 7 days (604800000 ms) in ms
ACCESS_TOKEN_VALIDITY="86400000" # Default validity is 1 day (86400000 ms) in ms
SESSION_SECRET='anothersecretcode123'

# Hoppscotch App Domain Config
REDIRECT_URL="http://localhost:3000"
WHITELISTED_ORIGINS = "http://localhost:3170,http://localhost:3000,http://localhost:3100"

# Google Auth Config
GOOGLE_CLIENT_ID="*****"
GOOGLE_CLIENT_SECRET="*****"
GOOGLE_CALLBACK_URL="http://localhost:3170/v1/auth/google/callback"
GOOGLE_SCOPE="email,profile"

# Github Auth Config
GITHUB_CLIENT_ID="*****"
GITHUB_CLIENT_SECRET="*****"
GITHUB_CALLBACK_URL="http://localhost:3170/v1/auth/github/callback"
GITHUB_SCOPE="user:email"

# Microsoft Auth Config
MICROSOFT_CLIENT_ID="*****"
MICROSOFT_CLIENT_SECRET="*****"
MICROSOFT_CALLBACK_URL="http://localhost:3170/v1/auth/microsoft/callback"
MICROSOFT_SCOPE="user.read"

# Mailer config
MAILER_SMTP_URL="smtps://user@domain.com:pass@smtp.domain.com"
MAILER_ADDRESS_FROM='"From Name Here" <from@example.com>'

# Rate Limit Config
RATE_LIMIT_TTL=60 # In seconds
RATE_LIMIT_MAX=100 # Max requests per IP

#-----------------------Frontend Config------------------------------#

# Base URLs
VITE_BASE_URL=http://localhost:3000
VITE_SHORTCODE_BASE_URL=http://localhost:3000
VITE_ADMIN_URL=http://localhost:3100

# Backend URLs
VITE_BACKEND_GQL_URL=http://localhost:3170/graphql
VITE_BACKEND_WS_URL=wss://localhost:3170/graphql
VITE_BACKEND_API_URL=http://localhost:3170/v1

# Terms Of Service And Privacy Policy Links (Optional)
VITE_APP_TOS_LINK=https://docs.hoppscotch.io/terms
VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/privacy

Please refer to our documentation for more details on what each variable means. However, there are three key variables that you need to configure to start building the image:

1. Database configuration
2. SMTP configuration
3. OAuth configuration

Database Configuration

By default, Hoppscotch ships with a Docker container that has a pre-configured Postgres database. However, if you need to configure your own Postgres database on the cloud, make sure you have a valid URL in the format postgresql://username:password@url:5432/dbname, and replace the existing DATABASE_URL in the environment file.

SMTP Configuration

In order to invite your team to use Hoppscotch and enable email functionality, you need to set up proper SMTP configuration as described below. Replace the current value of MAILER_SMTP_URL with a valid SMTP URL in the format smtps://user@domain.com:pass@smtp.domain.com.

You can also use Mailcatcher as a simple SMTP server. To install Mailcatcher and start the server, run the following command:

brew install mailcatcher # install Mailcatcher
mailcatcher -f

You can also install mailcatcher using gem

gem install mailcatcher

Mailcatcher will start at smtp://127.0.0.1:1025. When configuring the environment variable, set MAILER_SMTP_URL as smtp://host.docker.internal:1025 and set MAILER_ADDRESS_FROM as any of your current email addresses, such as frodo@shire.com.

OAuth Configuration

You can still use the self-hosted Hoppscotch app without logging in, but if you need to log in or access the admin dashboard, you need to configure an OAuth provider. In this document, we will set up GitHub as our OAuth provider. The GitHub OAuth configurations have the following variables:

GITHUB_CLIENT_ID="*****"
GITHUB_CLIENT_SECRET="*****"
GITHUB_CALLBACK_URL="http://localhost:3170/v1/auth/github/callback"
GITHUB_SCOPE="user:email"

To set up GitHub as your OAuth provider, follow these steps:

1. Click your profile photo in the upper-right corner of any page, then click Settings.
2. On the left sidebar, scroll down and click Developer Settings.
3. On the left sidebar, click OAuth Apps.
4. Click New OAuth App.
5. Provide the required information and the callback URL as specified in the configuration.
6. After registering the application, copy the Client ID and Client Secret and add them to the environment file.

Installing dependencies & building the image

After configuring the required environment variables, install the necessary dependencies for Hoppscotch by running the following command on the root directory of the repository:

pnpm install

Next, use Docker to build the images. This process may take a while, and we recommend using a system with at least 16 GB of RAM for building the image:

docker compose build

Running Migrations

To start using Hoppscotch, you must run migrations on the Postgres database.

If you are using the default database that comes with Hoppscotch, you need to get the process ID of the container and run the migrations within the container by executing the following commands.

docker ps # copy the id of hoppscotch-backend
docker exec -it id bash
pnpm exec prisma migrate deploy

However, if you are using your own hosted database, you can run migrations using the following commands:

cd packages/hoppscotch-backend
pnpm exec prisma migrate deploy
cd .. # make sure you return back to the root directory 

Running Hoppscotch

Now that everything is configured and migrations are run, you can start using Hoppscotch by running

docker compose up

The Hoppsoctch app will now be available at http://localhost:3000

You can also access the admin dashboard at http://localhost:3100.

In conclusion, self-hosting your API testing with Hoppscotch gives you complete control over your API development workflow. This guide covers the basics of self-hosting Hoppscotch, including the necessary configurations and settings you'll need to get started. If you prefer not to self-host, you can check out our cloud instance at hoppscotch.io. Also, don't forget to check out our GitHub repository and provide feedback!