Prerequisites

Hoppscotch is a self-hosted API development platform, packaged as a set of Docker containers. You can install and run Hoppscotch on any operating system that can run a Docker Engine. You can use Hoppscotch on your local machine or a cloud provider of your choice.

System Requirements

Hoppscotch is designed to run well on both small and large deployments. The minimum requirements to run Hoppscotch are an operating system that supports Docker and 4 CPU core + 16GB of RAM to generate the build image and as little as 1 CPU core + 2GB of RAM to host the generated output files.

Install Node.js, npm, pnpm

Node.js + npm

Install Node.js (v18+) and npm (v9+).

Verify Node.js and npm installation by running the following commands in your terminal:

node -v

npm -v

pnpm

Install pnpm (v6+).

Verify pnpm installation by running the following command in your terminal:

pnpm -v

Docker

Install Docker (v20+).

Verify Docker installation by running the following command in your terminal:

docker -v

It is recommended to use Compose V2. To switch to Compose V2, use the docker compose CLI plugin or activate the Use Docker Compose V2 setting in Docker Desktop. For more information, see the Evolution of Compose.

Git

Install Git (v2+).

Verify Git installation by running the following command in your terminal:

git --version

Email delivery

Hoppscotch come with support for easy integrations with 3rd party SMTP providers. You will need emails so that you can invite your team to use Hoppscotch and order for emails to work, you will need to setup proper SMTP configuration as described below.

To enable email delivey, you will need to generate a valid SMTP URL in the below format:

smtps://user@domain.com:pass@smtp.domain.com

For example, if you are using Gmail as your SMTP server your SMTP URL will look like something shown below:

smtps://user@gmail.com:pass@smtp.gmail.com

You can also use mailcatcher as a simple SMTP server

Postgres database

Hoppscotch uses a Postgres database to store all the data. You can use any Postgres database provider of your choice - hosted locally or on a cloud provider. Make sure you have a valid Postgres database URL in the below format:

postgresql://username:password@url:5432/dbname

By default, the package is shipped with a container with a postgres DB and can be configured with the below URL

postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch

OAuth

You also need to configure an OAuth provider to enable third party authentication. Hoppscotch supports the following OAuth providers:

1. Email
2. GitHub
3. Google
4. Microsoft

To configure the mandatory third party authentication, you will need to generate a valid OAuth client ID and client secret for the OAuth provider of your choice. You will also need to provide a valid callback URL for the OAuth provider.

For example, if you are using GitHub as your OAuth provider, you will need to generate a valid OAuth client ID and client secret for GitHub. You will also need to provide a valid callback URL for GitHub. The environment variables for GitHub OAuth provider will look like something shown below:

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

The CALLBACK_URL variable is the URL that is invoked after the authorization is done and it follows the pattern http://localhost:3170/v1/auth/[auth_provider_name]/callback.

The SCOPE variable defines the scope of the data that the OAuth provider passes on to Hoppscotch.

The links to configure OAuth for various providers are given below

1. GitHub (scope: email)
2. Google (scope: email, profile)
3. Microsoft (scope: user with read permission)