Install and build

​

Configuring the environment

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

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

#-----------------------Backend Config------------------------------#
# Enterprise License Key
# Get your license key from https://enterprise.hoppscotch.com
ENTERPRISE_LICENSE_KEY=***************************************

# (Optional) By default, the AIO container (when in subpath access mode) exposes the endpoint on port 80. Use this setting to specify a different port if needed.
HOPP_AIO_ALTERNATE_PORT=80

# Prisma Config
DATABASE_URL=postgresql://username:password@url:5432/dbname # or replace with your database URL

# ClickHouse Config
ALLOW_AUDIT_LOGS=true
CLICKHOUSE_HOST=http://clickhouse:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=''

# Enable/Disable Horizontal Scaling
HORIZONTAL_SCALING=false

# Redis Config 
# Note: Configure Redis only if HORIZONTAL_SCALING is set to true
REDIS_HOST=host.docker.internal
REDIS_PORT=6379
REDIS_PASSWORD=password
REDIS_DATABASE=0

# 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

# Recommended to be true. Set to false if you are using http.
# Note: Some auth providers may not support http requests and may stop working when set to false.
ALLOW_SECURE_COOKIES=true

# Sensitive Data Encryption Key while storing in Database (32 character)
DATA_ENCRYPTION_KEY=********************************

# Hoppscotch App Domain Config
REDIRECT_URL=http://localhost:3000
WHITELISTED_ORIGINS=http://localhost:3170,http://localhost:3000,http://localhost:3100
VITE_ALLOWED_AUTH_PROVIDERS=GOOGLE,GITHUB,MICROSOFT,EMAIL,SAML,OIDC

# 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

# Set to 'true' if you are using github enterprise
IS_GITHUB_ENTERPRISE_ENABLED=false

# Change domain to respective org domain, if using Github Enterprise Cloud use github.com as domain
GITHUB_AUTHORIZATION_URL=https://{domain}/login/oauth/authorize
GITHUB_TOKEN_URL=https://{domain}/login/oauth/access_token

# If using Github Enterprise Cloud use api.github.com as domain for 2 fields below
GITHUB_USER_PROFILE_URL=https://{domain}/users
GITHUB_USER_EMAIL_URL=https://{domain}/user/emails

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

# SAML Auth Config
SAML_ISSUER=**********
SAML_AUDIENCE=nestjs-saml
SAML_CALLBACK_URL=http://localhost:3170/v1/auth/saml/callback
SAML_CERT=**********
SAML_ENTRY_POINT=**********
SAML_WANT_ASSERTIONS_SIGNED=true
SAML_WANT_RESPONSE_SIGNED=false

# OIDC Auth Config
OIDC_PROVIDER_NAME=************************************************
OIDC_ISSUER=************************************************
OIDC_AUTH_URL=************************************************
OIDC_TOKEN_URL=************************************************
OIDC_USER_INFO_URL=************************************************
OIDC_CLIENT_ID=************************************************
OIDC_CLIENT_SECRET=************************************************
OIDC_CALLBACK_URL=http://localhost:3170/v1/auth/oidc/callback
OIDC_SCOPE=openid profile email

# Mailer config
MAILER_SMTP_ENABLE=true
MAILER_USE_CUSTOM_CONFIGS=false
MAILER_ADDRESS_FROM=<from@example.com>
MAILER_SMTP_URL=smtps://user@domain.com:pass@smtp.domain.com # used if custom mailer configs is false
# The following are used if custom mailer configs is true
MAILER_SMTP_HOST=smtp.domain.com
MAILER_SMTP_PORT=587
MAILER_SMTP_SECURE=true
MAILER_SMTP_USER=user@domain.com
MAILER_SMTP_PASSWORD=pass
MAILER_TLS_REJECT_UNAUTHORIZED=true

# 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/support/terms
VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy

# Set to `true` for subpath based access
ENABLE_SUBPATH_BASED_ACCESS=false

Let’s understand the major environment variables:

1. ENTERPRISE_LICENSE_KEY: The license key required to use Hoppscotch Enterprise.
2. DATABASE_URL: This is where you add your Postgres database URL.
3. HOPP_AIO_ALTERNATE_PORT: This is an optional variable that lets you specify an alternate port for the AIO container’s endpoint when operating in subpath access mode. By default, this endpoint is exposed on port 80.
4. HORIZONTAL_SCALING: Set to true to enable horizontal scaling, which uses Redis for managing pub-sub and state across instances.
5. TOKEN_SALT_COMPLEXITY: Defines the complexity of the SALT that is used for hashing - a higher number implies a more complex salt.
6. MAGIC_LINK_TOKEN_VALIDITY: Duration of the validity of the magic link being sent to sign in to Hoppscotch (in days).
7. REFRESH_TOKEN_VALIDITY: Validity of the refresh token for auth (in ms).
8. ACCESS_TOKEN_VALIDITY: Validity of the access token for auth (in ms).
9. JWT_SECRET, SESSION_SECRET: Secret Keys for security purposes.
10. ALLOW_SECURE_COOKIES: If disabled users will be able to use Hoppscotch over HTTP connections as well. It is recommended that this be left enabled as some auth providers may not work if this value is set to true.
11. DATA_ENCRYPTION_KEY: A 32-character key used for encrypting sensitive data stored in the database.
12. REDIRECT_URL: This is a fallback URL to debug when the actual redirects fail.
13. WHITELISTED_ORIGINS: URLs of Hoppscotch backend, admin dashboard, and the frontend app.
14. VITE_ALLOWED_AUTH_PROVIDERS: Allows you to specify which auth providers you want to enable.
15. MAILER_SMTP_ENABLE: Enables the SMTP mailer configuration.
16. MAILER_USE_CUSTOM_CONFIGS: When custom mailer configurations are used.
17. MAILER_SMTP_URL: The SMTP URL for email delivery.
18. MAILER_ADDRESS_FROM: The email address that you would be using.
19. MAILER_SMTP_HOST: The SMTP host.
20. MAILER_SMTP_PORT: The port to connect to the SMTP server.
21. MAILER_SMTP_USER: The SMTP user or email for authentication.
22. MAILER_SMTP_PASSWORD: Provide the password set for the SMTP user.
23. RATE_LIMIT_TTL: The time it takes to refresh the maximum number of requests being received.
24. RATE_LIMIT_MAX: The maximum number of requests that Hoppscotch can handle under RATE_LIMIT_TTL.
25. VITE_BASE_URL: This is the URL where your deployment will be accessible from.
26. VITE_SHORTCODE_BASE_URL: A URL to generate shortcodes for sharing, can be the same as VITE_BASE_URL.
27. VITE_BACKEND_GQL_URL: The URL for GraphQL within the instance.
28. VITE_BACKEND_WS_URL: The URL for WebSockets within the instance.
29. VITE_BACKEND_API_URL: The URL for REST APIs within the instance.
30. VITE_APP_TOS_LINK and VITE_APP_PRIVACY_POLICY_LINK are optional and are used to configure the links to the Terms & Conditions and Privacy Policy.

Third-party auth configs have to be obtained from the respective providers. You can choose and configure the auth providers by following the configuring OAuth guide.

​

Docker

Once the environment variables are configured, you may proceed to the next step of setting up the Hoppscotch instance. Currently, there are two ways to set up Hoppscotch:

• Using individual containers for the services

• Using the AIO container

• Before proceeding further, ensure that you have a running instance of Postgres.

​

Using individual containers for the services

To self-host Hoppscotch Enterprise Edition, you will need the following services running via Docker:

• Hoppscotch enterprise frontend
• Hoppscotch enterprise backend
• Hoppscotch enterprise admin dashboard

Pull the containers from DockerHub with the following command:

docker pull hoppscotch/hoppscotch-enterprise-frontend
docker pull hoppscotch/hoppscotch-enterprise-backend
docker pull hoppscotch/hoppscotch-enterprise-admin

After pulling the containers, start Hoppscotch by running all three services:

docker run -p 3000:3000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise-frontend
docker run -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise-backend
docker run -p 3100:3100 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise-admin

• Ensure that the environment variables are configured in the .env file and the restart policy is mentioned.

Open admin dashboard or PORT 3100 in the browser to setup and access the Hoppscotch instance.

​

Using the AIO container

The All-In-One (AIO) container is a single container that provides all the services required to run Hoppscotch.

Pull the container from DockerHub with the following command:

docker pull hoppscotch/hoppscotch-enterprise

After pulling the container, start Hoppscotch by running the container:

docker run -p 3000:3000 -p 3100:3100 -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise

• Ensure that the environment variables are configured in the .env file and the restart policy is mentioned.

Open admin dashboard or PORT 3100 in the browser to setup and access the Hoppscotch instance.

​

Subpath Based Access

To enable subpath based access the following .env variable must be set to true, it is set to false by default.

ENABLE_SUBPATH_BASED_ACCESS=false

When set to true the following is the expected behavior:

​

Using individual containers for the services

When using the individual containers it is up to the users to configure a reverse proxy to allow requests made to a specific route to be rerouted to the relevant containers.

​

Using the AIO container

When using AIO, when subpath access is set to true the services can be accessed from the following routes

​

Migrations

Once the instance of Hoppscotch is up, you need to run migrations on the database to ensure that it has the relevant tables. Depending on how Hoppscotch was set up, the method to run the migrations changes.

​

Using individual containers for the services

Run the following command to copy the ID of the backend container:

docker ps

​

Using the AIO container

Run the following command to copy the ID of the AIO container:

docker ps

​

Running migrations

Once the respective container ID is copied, execute the following command to open an interactive shell within the AIO container to execute the migration command:

docker exec -it <container_id> /bin/sh

Once inside the container, run the migration using:

pnpx prisma migrate deploy

Should the user ever encounter the following error:

Database migration not found. Please check the documentation for assistance: https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build#running-migrations

It means the user is trying to start the backend (or AIO) service before the database has all the relevant tables in it. In order to run the migration to populate the database run the following command.

docker run -it --entrypoint sh --env-file .env <container_name>

Making sure to pass in the .env file containing the right .env variables for the instance. On executing the aforementioned command will result in a shell being opened inside a instance of the container following which user can execute a database migration normally with

pnpx prisma migrate deploy

Once the database has been successfully run and the database populated with tables the backend containers ( or AIO container) can be started normally.

Note: If user is using docker compose to run the services the following command can be used to open a shell inside the backend (or AIO) service.

docker compose run --entrypoint sh <Service_name>

​

ClickHouse setup

To start saving the audit logs into ClickHouse, first you need to create the relevant databases with the relevant tables in them. Follow the following instructions to set up ClickHouse to start saving logs:

1. Ensure that all the relevant containers are running.

2. Run the following command to get the ID of the ClickHouse container:

   docker ps
   

3. Once the ClickHouse container is also running, open an interactive bash into it using the clickhouse-client:

   docker exec -it <clickhouse_container_id> clickhouse-client
   

4. Once inside the container, execute the following SQL commands:

   # Create a database called logs
   CREATE DATABASE logs
   
   # Create a table called audit_logs in the logs database
   CREATE TABLE IF NOT EXISTS logs.audit_logs
   (
       `event` String,
       `timestamp` DateTime,
       `user` Tuple(id String, email String, name String),
       `group` Tuple(type LowCardinality(String), id String),
       `resource` Tuple(type LowCardinality(String), metadata String),
       `statusCode` Int16,
       `errorMessage` String,
       `result` LowCardinality(String),
       `server_version` String
   )
   ENGINE = MergeTree
   ORDER BY timestamp
   

​

SAML Configuration

When you use SAML authentication, by default Hoppscotch only pulls the email of the user as the platform uses it as the unique identifier to verify the user. Starting from v2024.9.2 onwards, Hoppscotch Enterprise Edition instances support pulling the following attributes from the SAML response to fill in additional user details:

• displayName: The name of the user which is displayed within the Hoppscotch platform.
• photoURL: The URL where to find the user’s profile picture. Do not set this attribute if a profile picture doesn’t exist.
• isAdmin (optional): A boolean attribute (true or false) that automatically assigns the Admin role to users who belong to a designated group in the configured Identity Provider (e.g., Okta).

You have to configure your SAML IdP (Identity Provider) to include these attributes exactly in the response. For example, for Okta, you can follow this guide to configure the attributes.