Skip to main content
Self-hosting API Lab gives you complete control over your API development workflow and allows you to deploy API Lab in your own data center or cloud, giving you greater control over data and security. Self-hosted API Lab comes in two variants - Community and Enterprise Edition, both of which can be deployed on systems that support Docker. You can host API Lab on your servers, providing a private workspace for the individuals or teams using it. This guide covers the basics of self-hosting API Lab, including the configurations and settings needed to get started.

​
Pre-requisites

Before you start ensure that your system or environment meets the following requirements:
  • Node.js (v18+) and npm (v9+) - Ensure that both Node.js and npm are up-to-date to support the latest features and security patches.
  • pnpm (v6+) - Recommended for efficient package management and faster installations.
  • Docker (v20+) - Docker should be properly installed and configured for containerization of your API Lab instance.
  • Git - Required for version control and managing API Lab source code.
Visit our documentation for a detailed guide on installing the prerequisite softwares.

​
Configuring the Environment

Create a .env file in your working directory, copy the example environment variable configurations provided below into it, and then replace the example values with your actual values.
Ensure that there are NO QUOTES encapsulating the values of the environment variables and NO SPACES around the equals sign (=). 
#-----------------------Backend Config------------------------------#

# Prisma Config
DATABASE_URL=postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch

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

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

# Whitelisted origins for the API Lab 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.app.apilab.work/support/terms
VITE_APP_PRIVACY_POLICY_LINK=https://docs.app.apilab.work/support/privacy

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

​
1. Database Configuration

API Lab uses a Postgres database to store all the data. You can use any Postgres database provider of your choice, hosted locally or on a cloud. Update the DATABASE_URL variable in your .env file with your custom database connection string, which should include the username, password, and database name. 
DATABASE_URL=postgresql://username:password@url:5432/dbname

​
2. SMTP Configuration

To invite your team to use API Lab and enable email delivery, you’ll need to configure SMTP settings properly.

​
2.1 Basic SMTP Configuration

For basic SMTP configuration, you can use mailcatcher. It runs a super simple SMTP server which catches any message sent to it to display in a web interface. You can set up mailcatcher using Docker with 2 below easy steps:
  1. Pull the Mailcatcher Image from Docker Hub, 
    docker pull dockage/mailcatcher:0.9.0
  2. With Mailcatcher set up on your machine, start the Mailcatcher container using docker run with the appropriate port mappings (1080 for the web interface and 1025 for SMTP).
    Docker containers are isolated from the host by default. When using localhost inside a Docker container, it refers to the container itself, and not the host machine. Since API Lab runs inside a Docker container while Mailcatcher runs on the host machine, you’ll need to use the Docker bridge network IP instead of localhost to ensure that the containerized application can communicate with the Mailcatcher service on the host. To find this IP address, run: 
    ip addr show docker0
    Look for the inet address associated with the docker0 interface. It’s typically in the 172.17.0.0/16 range but may vary based on your Docker network configuration. And If you’re using Docker Desktop, you can use host.docker.internal instead of localhost. 
    docker run --name='mailcatcher' -d \
  --publish=<Docker_bridge_IP or host.docker.internal>:1080:1080 \
  --publish=<Docker_bridge_IP or host.docker.internal>:1025:1025 \
  dockage/mailcatcher:0.9.0
    Visit http://<Docker_bridge_IP or host.docker.internal>:1080 to access the Mailcatcher web interface and view email communications. Further, configure the below environment variables in your .env file: 
    MAILER_SMTP_ENABLE=true
MAILER_USE_CUSTOM_CONFIGS=false
MAILER_ADDRESS_FROM=from@example.com
MAILER_SMTP_URL=smtp://<Docker_bridge_IP or host.docker.internal>:1025

​
2.2 Custom Mailer Configuration

For advanced email delivery needs, such as for production environments, you can configure a custom email service by setting MAILER_USE_CUSTOM_CONFIGS=true. You can choose from services like SendGrid, Amazon SES, or your own SMTP server. Once you’ve set up your chosen service, update your .env file with the following details: 
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

​
3. OAuth Configuration

To access the admin dashboard, you’ll need to configure an OAuth provider. In the Community Edition, API Lab supports:
  1. Google
  2. GitHub
  3. Microsoft
In the Enterprise Edition, support also includes SAML SSO, OpenID Connect, and GitHub Enterprise. Here’s a quick guide to registering an OAuth application with GitHub:
  1. Click your profile photo in the upper-right corner and select Settings.
  2. In the left sidebar, scroll down and click Developer Settings.
  3. Click OAuth Apps in the sidebar.
  4. Click New OAuth App.
  5. Enter the required information and specify the callback URL as indicated in your configuration.
  6. After registering the application, copy the Client ID and Client Secret, and add them to your environment file.
Similarly, you can follow the specific setup instructions for other OAuth providers to complete your configuration.

​
4. Subpath Access

Subpath access allows you to host multiple services under a single domain by assigning each service a specific subpath. When ENABLE_SUBPATH_BASED_ACCESS=true, you can access all three services (API Lab App, Admin Dashboard, API Lab Backend) on the same domain using different routes. If subpath access is disabled (ENABLE_SUBPATH_BASED_ACCESS=false), you will need to access the services on different ports.
By default, the AIO container exposes the app on port 80. This can cause conflicts if you’re running on a host system where port 80 is privileged, such as with Rootless Docker, Podman, or hardened environments like OpenShift. If you experience issues on these setups, try setting HOPP_AIO_ALTERNATE_PORT to bind the app to a non-privileged port.

​
Installing dependencies, running migrations & building the image

Once the environment variables are configured, you may now proceed to the next step of setting up the API Lab instance.
1

Check Database Connectivity

Ensure that the database instance is active and running at the DATABASE_URL specified in your .env file.
docker ps
2

Select the suitable API Lab instance to self-host

There are two ways to set up API Lab:
  1. Using individual containers for the services - API Lab Backend, API Lab Frontend and API Lab Admin Dashboard.
  2. Using the AIO container - a single container that provides all the services required to run API Lab.
For a streamlined setup, let’s proceed with the AIO container. If you’d like to set up individual containers instead, refer to the documentation.
3

Pull the latest API Lab container

Pull the container from DockerHub with the following command. If a specific version isn’t provided, it will automatically pull the latest version:
docker pull hoppscotch/hoppscotch
4

Run Database Migrations

After pulling the API Lab image from DockerHub, you need to run database migrations to set up the necessary tables. Use the following commands:
docker run -it --entrypoint sh --env-file .env hoppscotch/hoppscotch
# pnpm exec prisma migrate deploy
5

Start the API Lab Instance

To launch API Lab, run the container with the following command:
docker run -p 3000:3000 -p 3100:3100 -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch

​
Accessing Admin Dashboard and Application

  • Accessing the Admin Dashboard
    • After successfully running the required containers, the next step is to create an Admin account.
    • To access the Admin Dashboard, visit http://localhost:3100 if ENABLE_SUBPATH_BASED_ACCESS=false.
    • Log in with your credentials or create a new account to obtain admin privileges.
    • Once logged in, you’ll find the Dashboard as your central hub for managing workspaces, overseeing user activities, and configuring OAuth environment variables directly from the Settings page.
  • Accessing the API Lab Application
    • You can access the API Lab application itself at http://localhost:3000.
In conclusion, this guide has covered how to self-host API Lab, helping you set everything up in one go. If you prefer visual guidance, check out the video below for a detailed walkthrough that complements the instructions provided here. For additional details on each step of self-hosting API Lab, refer to our documentation.