Install and build

  • In order for a smooth building process, it is recommended to have at least 16GB of RAM available in your system.

Cloning the repository

You can find the code to self-host Hoppscotch instance in our GitHub repository.

Clone the repo locally using git:

git clone
GitHub CLI
gh repo clone hoppscotch/hoppscotch

Configuring the environment

Before you get started with the installation, you need to configure the environment variables.

Copy the contents of .env.example file found in the root directory of cloned repository to .env and add your own values for the environment variables.

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

# Auth Tokens Config
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

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

# Google Auth Config

# Github Auth Config

# Microsoft Auth Config

# Mailer config
MAILER_ADDRESS_FROM='"From Name Here" <>'

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

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

# Base URLs

# Backend URLs

# Terms Of Service And Privacy Policy Links (Optional)

Let's understand the major environment variables:

  1. DATABASE_URL: This is where you add your Postgres database URL, you can also use our default database shipped within the docker container postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch
  2. TOKEN_SALT_COMPLEXITY: Defines the complexity of the SALT that is used for hashing - higher number implies more complex the salt
  3. MAGIC_LINK_TOKEN_VALIDITY:Duration of the validity of the magic link being sent to sign in to Hoppscotch (in days)
  4. REFRESH_TOKEN_VALIDITY: Validity of the refresh token for auth (in ms)
  5. ACCESS_TOKEN_VALIDITY : Validity of the access token for auth (in ms)
  6. JWT_SECRET, SESSION_SECRET: Secret Keys for security purposes
  7. REDIRECT_URL: Is a fallback URL to debug when the actual redirects fail
  8. WHITELISTED_ORIGINS: URLs of Hoppscotch backend, admin dashboard and the frontend app
  9. MAILER_SMTP_URL: The SMTP URL for email delivery
  10. MAILER_ADDRESS_FROM: The email address that you would be using
  11. RATE_LIMIT_TTL: The time it takes to refresh the maximum number of requests being received
  12. RATE_LIMIT_MAX: The maximum number of requests that Hoppscotch can handle under RATE_LIMIT_TTL
  13. VITE_BASE_URL: This is the URL where your deployment will be accesible from
  14. VITE_SHORTCODE_BASE_URL: A URL to generate shortcodes for sharing, can be same as VITE_BASE_URL
  15. VITE_BACKEND_GQL_URL: The URL for GraphQL within the instance
  16. VITE_BACKEND_WS_URL: The URL for WebSockets within the instance
  17. VITE_BACKEND_API_URL: The URL for REST APIs within the instance
  18. VITE_APP_TOS_LINK and VITE_APP_PRIVACY_POLICY_LINK are optional and is used to configure the links to the Terms & Conditions and Privacy Policy

Third party auth configs have to be obtained from the respective providers. Hoppscotch requires all three auth providers to be configured so that you can start using it. Read more about it here

Installing dependencies

Now that you've configured the enviornment file, let's get started with installing the dependencies.

Open your terminal and navigate inside the cloned repository and run:

pnpm install

Now to get the server running, you need to run migrations on the database, this can be done using the command below:

cd packages/hoppscotch-backend
pnpm exec prisma migrate deploy

But if you are using the default database that is provided with the docker container, you need to run the following commands after building the image. This is because you need to run migrations within the container

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

Building the docker image

Now return to the root directory and build the docker images using the following command:

docker compose build

Hoppscotch provides three different images, the backend, frontend and the admin dashboard. These are associated with the tags hoppscotch-backend, hoppscotch-app and hoppscotch-sh-admin respectively. You can run them up or push them to container registries for deployment or run from the preset config using docker compose.

docker compose

You can also run the individual images using the following commmands

docker compose up hoppscotch-backend # Runs the backend server up
docker compose up hoppscotch-sh-admin # Runs the self hosted server up (preset opens in port 3100)
docker compose up hoppscotch-app # Runs the main frontend app up