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.

  • Ensure that the environment values are not enclosed within quotes.
#-----------------------Backend Config------------------------------#
# Prisma Config
DATABASE_URL=postgresql://username:password@url:5432/dbname # 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
ACCESS_TOKEN_VALIDITY=86400000
SESSION_SECRET=anothersecretcode123
# 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
# 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
MICROSOFT_TENANT=common
# 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
RATE_LIMIT_MAX=100
#-----------------------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
ENTERPRISE_LICENSE_KEY=***************************************

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 - a higher number implies a more complex 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: This 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. VITE_ALLOWED_AUTH_PROVIDERS: Allows you to specify which auth providers you want to enable
  10. MAILER_SMTP_URL: The SMTP URL for email delivery
  11. MAILER_ADDRESS_FROM: The email address that you would be using
  12. RATE_LIMIT_TTL: The time it takes to refresh the maximum number of requests being received
  13. RATE_LIMIT_MAX: The maximum number of requests that Hoppscotch can handle under RATE_LIMIT_TTL
  14. VITE_BASE_URL: This is the URL where your deployment will be accessible from
  15. VITE_SHORTCODE_BASE_URL: A URL to generate shortcodes for sharing, can be the same as VITE_BASE_URL
  16. VITE_BACKEND_GQL_URL: The URL for GraphQL within the instance
  17. VITE_BACKEND_WS_URL: The URL for WebSockets within the instance
  18. VITE_BACKEND_API_URL: The URL for REST APIs within the instance
  19. 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
  20. ENTERPRISE_LICENSE_KEY: The license key required to use Hoppscotch Enterprise

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

Recommended

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 hoppscotch-enterprise-frontend
docker run -p 3170:3170 --env-file .env hoppscotch-enterprise-backend
docker run -p 3100:3100 --env-file .env hoppscotch-enterprise-admin
  • Ensure that the environment variables are configured in the .env file.

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 hoppscotch/hoppscotch-enterprise
  • Ensure that the environment variables are configured in the .env file.

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

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

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