Install and build Enterprise Edition

If you’re interested in deploying Hoppscotch on Kubernetes, you can conveniently skip this guide and proceed directly to the Helm chart deployment guide.

Configuring the environment

Before you get started with the installation, you need to configure the environment variables. Create a .env file in the root directory of the project and add the following environment variables:

Ensure that the environment values are not enclosed within quotes [""].

To enable desktop app support for self-hosted instances, make sure you’ve enabled subpath based access.

#-----------------------Backend Config------------------------------#

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

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

# Enable/Disable Horizontal Scaling
# Set to 'true' to enable horizontal scaling across multiple backend instances
# When enabled, Redis is required for session management and data synchronization
HORIZONTAL_SCALING=false

# Redis Config
# Note: Configure Redis only if HORIZONTAL_SCALING is set to true
REDIS_URL=redis://username:password@host:6379/0

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

# Whitelisted origins for the Hoppscotch App.
# This list controls which origins can interact with the app through cross-origin comms.
# - localhost ports (3170, 3000, 3100): app, backend, development servers and services
# - app://localhost_3200: Bundle server origin identifier
#   NOTE: `3200` here refers to the bundle server (port 3200) that provides the bundles,
#   NOT where the app runs. The app itself uses the `app://` protocol with dynamic
#   bundle names like `app://{bundle-name}/`
WHITELISTED_ORIGINS=http://localhost:3170,http://localhost:3000,http://localhost:3100,app://localhost_3200,app://hoppscotch

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

# Optional: Local Proxy Server Config
# Enables a local proxy server for routing API requests.
# This will only work if ENABLE_SUBPATH_BASED_ACCESS is set to `true`.
LOCAL_PROXY_SERVER_ENABLE=false

# Optional: Route all API requests via a proxy server for added security.
# Set your proxy server URL here, or remove this variable to send requests directly.
PROXY_APP_URL=https://proxy.hoppscotch.io

#-----------------------Container Runtime Config---------------------#

# (Optional) Caddy's in-container HTTP port. Defaults to 80 when unset.
# Set a free port (for example 8000) to run the container under a non-root UID.
# HOPP_ALTERNATE_PORT=8000

Let’s understand the major environment variables:

ENTERPRISE_LICENSE_KEY: The license key required to use Hoppscotch Enterprise.
DATABASE_URL: This is where you add your Postgres database URL.
HORIZONTAL_SCALING: Set to true to enable horizontal scaling, which uses Redis for managing pub-sub and state across instances.
DATA_ENCRYPTION_KEY: A 32-character key used for encrypting sensitive data stored in the database.
WHITELISTED_ORIGINS: URLs of Hoppscotch backend, admin dashboard, frontend app and the bundle server that are allowed to interact with the desktop app.
VITE_BASE_URL: This is the URL where your deployment will be accessible from.
VITE_SHORTCODE_BASE_URL: A URL to generate shortcodes for sharing, can be the same as VITE_BASE_URL.
VITE_BACKEND_GQL_URL: The URL for GraphQL within the instance.
VITE_BACKEND_WS_URL: The URL for WebSockets within the instance.
VITE_BACKEND_API_URL: The URL for REST APIs within the instance.
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.
HOPP_ALTERNATE_PORT: An optional variable that changes the HTTP port Caddy listens on inside the container, which is 80 by default. Set it to run under a non-root user, or when port 80 is already taken. See running under a non-root user.

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.

To enable desktop app support for your self-hosted Hoppscotch instance, make sure you expose the web app server which is a part of the frontend container. You can do this by running the following command:

docker run -p 3000:3000 -p 3200:3200 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-frontend

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

To enable desktop app support for your self-hosted Hoppscotch instance, make sure to set ENABLE_SUBPATH_BASED_ACCESS to true in your .env file.

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

Service	Route
Hoppscotch App	`/`
Hoppscotch Admin App	`/admin`
Hoppscotch Backend	`/backend`

By default, the AIO container serves the app on port 80. Ports below 1024 are privileged, so a non-root user can’t bind them — a common restriction in rootless Docker, Podman, and hardened environments like OpenShift. On those setups, set HOPP_ALTERNATE_PORT to bind the app to a port at or above 1024. See running under a non-root user.

Running under a non-root user

By default the images serve on port 80 inside the container (the HTTP port Caddy binds), which a non-root user can’t bind since ports below 1024 are privileged. To run under a non-root UID — OpenShift’s restricted SCC, rootless Docker, Podman — set HOPP_ALTERNATE_PORT to a free port at or above 1024, run the container with GID 0, and update your published port mapping to match:

docker run --user 1000:0 -p 3000:8000 -e HOPP_ALTERNATE_PORT=8000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise

On OpenShift the restricted SCC assigns the UID and GID 0 for you; just set the variable and point your Service and Route at the port you chose. If you deploy with the provided docker-compose.yml, the container side of the port mapping already follows HOPP_ALTERNATE_PORT. The port must not collide with one the image already uses, or the container exits at startup naming the conflict. Port 9159 is the local proxy server, which the backend starts when LOCAL_PROXY_SERVER_ENABLE is true:

Image	Reserved ports
AIO (subpath access mode)	`8080`, `3200`, `9159`
Frontend	`3000`, `3200`
Backend	`3170`, `8080`, `9159`
Admin	`3100`

The container needs a writable root filesystem, and the non-root UID must belong to GID 0.

The ClickHouse container used for audit logs is the official clickhouse/clickhouse-server image, which expects to run as its own UID and is not arbitrary-UID safe. On OpenShift, use a managed or externally hosted ClickHouse instead of running it alongside Hoppscotch under the restricted SCC.

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:

pnpm exec 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. Executing the aforementioned command will result in a shell being opened inside an instance of the container, following which the user can execute a database migration normally with

pnpm exec prisma migrate deploy

Once the migration 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:

Ensure that all the relevant containers are running.
Run the following command to get the ID of the ClickHouse container:
docker ps
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

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

The isAdmin attribute is evaluated only during the user’s first login or signup. Subsequent logins or signups will not re-evaluate this flag.

Name	Name Format	Value
displayName	Basic	user.displayName
photoURL	Basic	user.profileURL
isAdmin	Basic	isMemberOfGroupName(“Hoppscotch Admins”) ? “true” : “false”

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.

Getting started

Clients

Protocols

Features

Self-Host

Resources

Configuring the environment

Docker

Using individual containers for the services

Using the AIO container

Subpath Based Access

Using individual containers for the services

Using the AIO container

Running under a non-root user

Migrations

Using individual containers for the services

Using the AIO container

Running migrations

ClickHouse setup

SAML Configuration

​Configuring the environment

​Docker

​Using individual containers for the services

​Using the AIO container

​Subpath Based Access

​Using individual containers for the services

​Using the AIO container

​Running under a non-root user

​Migrations

​Using individual containers for the services

​Using the AIO container

​Running migrations

​ClickHouse setup

​SAML Configuration

Configuring the environment

Docker

Using individual containers for the services

Using the AIO container

Subpath Based Access

Using individual containers for the services

Using the AIO container

Running under a non-root user

Migrations

Using individual containers for the services

Using the AIO container

Running migrations

ClickHouse setup

SAML Configuration