Install and build

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 https://github.com/hoppscotch/hoppscotch.git

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
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

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