Set up Hoppscotch on your servers for complete control and customization.
Self-hosting Hoppscotch gives you complete control over your API development workflow and allows you to deploy Hoppscotch in your own data center or cloud, giving you greater control over data and security.
Self-hosted Hoppscotch comes in two variants - Community and Enterprise Edition, both of which can be deployed on systems that support Docker. You can host Hoppscotch on your servers, providing a private workspace for the individuals or teams using it.
This guide covers the basics of self-hosting Hoppscotch, including the configurations and settings needed to get started.
Before you start ensure that your system or environment meets the following requirements:
Visit our documentation for a detailed guide on installing the prerequisite softwares.
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.
=
). Hoppscotch 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.
To invite your team to use Hoppscotch and enable email delivery, you’ll need to configure SMTP settings properly.
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:
Pull the Mailcatcher Image from Docker Hub,
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 Hoppscotch 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: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 oflocalhost
.
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:
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:
To access the admin dashboard, you’ll need to configure an OAuth provider. In the Community Edition, Hoppscotch supports:
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:
Similarly, you can follow the specific setup instructions for other OAuth providers to complete your configuration.
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 (Hoppscotch App, Admin Dashboard, Hoppscotch 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.
Once the environment variables are configured, you may now proceed to the next step of setting up the Hoppscotch instance.
Check Database Connectivity
Ensure that the database instance is active and running at the DATABASE_URL
specified in your .env
file.
Select the suitable Hoppscotch instance to self-host
There are two ways to set up Hoppscotch:
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.
Pull the latest Hoppscotch container
Pull the container from DockerHub with the following command. If a specific version isn’t provided, it will automatically pull the latest version:
Run Database Migrations
After pulling the Hoppscotch image from DockerHub, you need to run database migrations to set up the necessary tables. Use the following commands:
Start the Hoppscotch Instance
To launch Hoppscotch, run the container with the following command:
http://localhost:3100
if ENABLE_SUBPATH_BASED_ACCESS=false
.http://localhost:3000
.In conclusion, this guide has covered how to self-host Hoppscotch, 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 Hoppscotch, refer to our documentation.
Set up Hoppscotch on your servers for complete control and customization.
Self-hosting Hoppscotch gives you complete control over your API development workflow and allows you to deploy Hoppscotch in your own data center or cloud, giving you greater control over data and security.
Self-hosted Hoppscotch comes in two variants - Community and Enterprise Edition, both of which can be deployed on systems that support Docker. You can host Hoppscotch on your servers, providing a private workspace for the individuals or teams using it.
This guide covers the basics of self-hosting Hoppscotch, including the configurations and settings needed to get started.
Before you start ensure that your system or environment meets the following requirements:
Visit our documentation for a detailed guide on installing the prerequisite softwares.
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.
=
). Hoppscotch 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.
To invite your team to use Hoppscotch and enable email delivery, you’ll need to configure SMTP settings properly.
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:
Pull the Mailcatcher Image from Docker Hub,
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 Hoppscotch 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: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 oflocalhost
.
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:
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:
To access the admin dashboard, you’ll need to configure an OAuth provider. In the Community Edition, Hoppscotch supports:
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:
Similarly, you can follow the specific setup instructions for other OAuth providers to complete your configuration.
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 (Hoppscotch App, Admin Dashboard, Hoppscotch 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.
Once the environment variables are configured, you may now proceed to the next step of setting up the Hoppscotch instance.
Check Database Connectivity
Ensure that the database instance is active and running at the DATABASE_URL
specified in your .env
file.
Select the suitable Hoppscotch instance to self-host
There are two ways to set up Hoppscotch:
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.
Pull the latest Hoppscotch container
Pull the container from DockerHub with the following command. If a specific version isn’t provided, it will automatically pull the latest version:
Run Database Migrations
After pulling the Hoppscotch image from DockerHub, you need to run database migrations to set up the necessary tables. Use the following commands:
Start the Hoppscotch Instance
To launch Hoppscotch, run the container with the following command:
http://localhost:3100
if ENABLE_SUBPATH_BASED_ACCESS=false
.http://localhost:3000
.In conclusion, this guide has covered how to self-host Hoppscotch, 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 Hoppscotch, refer to our documentation.