Self-Host Your API Testing with Hoppscotch: The open-source API Platform
Tags: webdev, opensource, api, tutorial
Published: 2023-06-02 13:07:14

Self-hosting Hoppscotch gives you complete control over your API development workflow and will allow you to run Hoppscotch on your own servers, giving you more control over your data and security.

This guide covers the basics of self-hosting Hoppscotch, including the necessary configurations and settings you need to get started. You can install and run Hoppscotch on any operating system that can run a [Docker Engine](https://docs.docker.com/engine), but you will need a 4 CPU core machine with at least 16 GB of RAM to build the docker images. However, you can use a 1 CPU core machine with 2GB of RAM to host the generated output files.

Before we get started with the setup, we're excited to announce that we are working on an enterprise edition of Hoppscotch. Fill out the form [here](https://hoppscotch.io/beta) to be the first to know when it's launched!

## Prerequisites

To get started with self-hosting Hoppscotch, make sure you have the following prerequisites in place:

1. node.js & npm
2. pnpm
3. docker
4. git

Visit our [documentation](https://docs.hoppscotch.io/documentation/self-host/prerequisites) for a detailed guide on installing the prerequisite softwares. 

## Cloning the repository

Now that you have all the necessary tools to get started with the installation, let's begin by cloning the Hoppscotch GitHub repository. You can clone the repository locally using git by running the following command in your terminal:

```bash
git clone https://github.com/hoppscotch/hoppscotch.git
```

Alternatively, you can use GitHub CLI to clone the repository:

```bash
gh repo clone hoppscotch/hoppscotch
```

## Configuring Environment Variables

Before building the Docker image and using Hoppscotch locally, you need to configure a few environment variables. Create a new file within the root directory of the repository called `.env` and paste the following configurations:

```bash
#-----------------------Backend Config------------------------------#
# Prisma Config
DATABASE_URL=postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch # 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" # 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'

# Hoppscotch App Domain Config
REDIRECT_URL="http://localhost:3000"
WHITELISTED_ORIGINS = "http://localhost:3170,http://localhost:3000,http://localhost:3100"

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

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

Please refer to our [documentation](https://docs.hoppscotch.io/documentation/self-host/install-and-build#configuring-the-environment) for more details on what each variable means. However, there are three key variables that you need to configure to start building the image:

1. Database configuration
2. SMTP configuration
3. OAuth configuration

### Database Configuration

By default, Hoppscotch ships with a Docker container that has a pre-configured Postgres database. However, if you need to configure your own Postgres database on the cloud, make sure you have a valid URL in the format `postgresql://username:password@url:5432/dbname`, and replace the existing `DATABASE_URL` in the environment file.

### SMTP Configuration

In order to invite your team to use Hoppscotch and enable email functionality, you need to set up proper SMTP configuration as described below. Replace the current value of `MAILER_SMTP_URL` with a valid SMTP URL in the format `smtps://user@domain.com:pass@smtp.domain.com`.

You can also use Mailcatcher as a simple SMTP server. To install Mailcatcher and start the server, run the following command:

```bash
brew install mailcatcher # install Mailcatcher
mailcatcher -f
```

You can also install mailcatcher using gem
```bash
gem install mailcatcher
```

Mailcatcher will start at `smtp://127.0.0.1:1025`. When configuring the environment variable, set `MAILER_SMTP_URL` as `smtp://host.docker.internal:1025` and set `MAILER_ADDRESS_FROM` as any of your current email addresses, such as `frodo@shire.com`.

### OAuth Configuration

You can still use the self-hosted Hoppscotch app without logging in, but if you need to log in or access the admin dashboard, you need to configure an OAuth provider. In this document, we will set up GitHub as our OAuth provider. The GitHub OAuth configurations have the following variables:

```bash
GITHUB_CLIENT_ID="*****"
GITHUB_CLIENT_SECRET="*****"
GITHUB_CALLBACK_URL="http://localhost:3170/v1/auth/github/callback"
GITHUB_SCOPE="user:email"
```

To set up GitHub as your OAuth provider, follow these steps:

1. Click your profile photo in the upper-right corner of any page, then click Settings.
2. On the left sidebar, scroll down and click Developer Settings.
3. On the left sidebar, click OAuth Apps.
4. Click New OAuth App.
5. Provide the required information and the callback URL as specified in the configuration.
6. After registering the application, copy the Client ID and Client Secret and add them to the environment file.

## Installing dependencies & building the image

After configuring the required environment variables, install the necessary dependencies for Hoppscotch by running the following command on the root directory of the repository:

```bash
pnpm install
```

Next, use Docker to build the images. This process may take a while, and we recommend using a system with at least 16 GB of RAM for building the image:

```bash
docker compose build
```

## Running Migrations

To start using Hoppscotch, you must run migrations on the Postgres database.

If you are using the default database that comes with Hoppscotch, you need to get the process ID of the container and run the migrations within the container by executing the following commands.

```bash
docker ps # copy the id of hoppscotch-backend
docker exec -it id bash
pnpm exec prisma migrate deploy
```

However, if you are using your own hosted database, you can run migrations using the following commands:

```bash
cd packages/hoppscotch-backend
pnpm exec prisma migrate deploy
cd .. # make sure you return back to the root directory 
```
## Running Hoppscotch

Now that everything is configured and migrations are run, you can start using Hoppscotch by running

```bash
docker compose up
```

The Hoppsoctch app will now be available at `http://localhost:3000`

![Hoppscotch app](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/az34pbvfklwtwiud3hnl.png)

You can also access the admin dashboard at `http://localhost:3100`.

![Hoppscotch admin dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/loqylvprn2zoy11teh5v.png)

In conclusion, self-hosting your API testing with Hoppscotch gives you complete control over your API development workflow. This guide covers the basics of self-hosting Hoppscotch, including the necessary configurations and settings you'll need to get started. If you prefer not to self-host, you can check out our cloud instance at [hoppscotch.io](https://hoppscotch.io). Also, don't forget to check out our [GitHub repository](https://hoppscotch.io/github) and provide feedback!