Hoppscotch is a powerful, open-source API development tool designed for testing and interacting with APIs efficiently. While deploying Hoppscotch AIO (All-In-One) in Docker is relatively straightforward, configuring it to work seamlessly behind a reverse proxy with subpaths can be quite challenging. Subpath-based access allows services like the Hoppscotch App, Admin App, and Backend to be accessed through specific routes (e.g., /, /admin, /backend), but enabling this setup without encountering errors requires careful configuration of both the application and the reverse proxy.In my experience, setting up Hoppscotch AIO with subpath-based access involved troubleshooting issues like misrouted requests, conflicts with port bindings, and reverse proxy misconfigurations. After resolving these challenges, I decided to write this guide to help others configure Hoppscotch AIO in Docker behind a reverse proxy with subpaths—without running into the same pitfalls.

Setup

Database

To set up the PostgreSQL database for Hoppscotch, you can use the following Docker command:

sudo docker run -p 5432:5432 --name hopp-DB \
  -e POSTGRES_DB=hoppscotch \
  -e POSTGRES_PASSWORD=<your-secret-password> \
  -d postgres

• -p 5432:5432: Maps port 5432 on your host machine to port 5432 inside the container (default PostgreSQL port).
• --name hopp-DB: Assigns the container a recognizable name (hopp-DB).
• POSTGRES_DB: Specifies the name of the database to be created (hoppscotch).
• POSTGRES_PASSWORD: Sets the password for the default PostgreSQL user (postgres). Replace <your-secret-password> with a strong password of your choice.
• -d postgres: Runs the container in detached mode using the official PostgreSQL image.

Customizing the External Port

If you want to expose PostgreSQL on a different port on your host machine (e.g., 1234), modify the -p flag as follows:

sudo docker run -p 1234:5432 --name hopp-DB \
  -e POSTGRES_DB=hoppscotch \
  -e POSTGRES_PASSWORD=<your-secret-password> \
  -d postgres

• Port 1234 on your host machine will map to port 5432 inside the container.
• You can then connect to PostgreSQL using localhost:1234.

This flexibility allows you to avoid conflicts if port 5432 is already in use by another service.

Hoppscotch

Environment variables

When configuring Hoppscotch AIO, environment variables play a critical role in defining how the application interacts with its backend, database, authentication, and frontend. Below are some key considerations and a sample .env file to help you set up your environment correctly.

Important notes:

#-----------------------Backend Config------------------------------#
# Prisma Config
DATABASE_URL=postgresql://postgres:<your-pg-password>@localhost:5432/hoppscotch

# Auth Tokens Config
JWT_SECRET=<your-jwt-secret>
TOKEN_SALT_COMPLEXITY=10
MAGIC_LINK_TOKEN_VALIDITY=3
REFRESH_TOKEN_VALIDITY=604800000
ACCESS_TOKEN_VALIDITY=86400000
SESSION_SECRET=<your-session-secret>

# Recommended to be true. Set to false if you are using http.
# Note: Some auth providers may not support http requests and may stop working when set to false.
ALLOW_SECURE_COOKIES=true

# Sensitive Data Encryption Key while storing in Database (32 character)
DATA_ENCRYPTION_KEY=<32-character-data-encryption-key>

# Hoppscotch App Domain Config
REDIRECT_URL=https://hoppscotch.example.com
WHITELISTED_ORIGINS=https://hoppscotch.example.com,https://hoppscotch.example.com/admin,https://hoppscotch.example.com/backend/v1,https://hoppscotch.example.com/backend/graphql
VITE_ALLOWED_AUTH_PROVIDERS=EMAIL

# Mailer config
MAILER_SMTP_ENABLE=true
MAILER_USE_CUSTOM_CONFIGS=true
MAILER_ADDRESS_FROM=<hoppscotch@example.com>
#MAILER_SMTP_URL=smtps://user@domain.com:pass@smtp.domain.com # used if custom mailer configs is false
# The following are used if custom mailer configs is true
MAILER_SMTP_HOST=smtp.example.com
MAILER_SMTP_PORT=465
MAILER_SMTP_SECURE=true
MAILER_SMTP_USER=<your-mail-user>
MAILER_SMTP_PASSWORD=<your-mail-password>
MAILER_TLS_REJECT_UNAUTHORIZED=true

# Rate Limit Config
RATE_LIMIT_TTL=60 # In seconds
RATE_LIMIT_MAX=100 # Max requests per IP

#-----------------------Frontend Config------------------------------#

# Base URLs
VITE_BASE_URL=https://hoppscotch.example.com
VITE_SHORTCODE_BASE_URL=https://hoppscotch.example.com
VITE_ADMIN_URL=https://hoppscotch.example.com/admin

# Backend URLs
VITE_BACKEND_GQL_URL=https://hoppscotch.example.com/backend/graphql
VITE_BACKEND_WS_URL=wss://hoppscotch.example.com/backend/graphql
VITE_BACKEND_API_URL=https://hoppscotch.example.com/backend/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=true

Save this configuration as .env in your working directory. This file will be loaded when starting the Hoppscotch container using the --env-file flag.By following these steps and ensuring proper configuration of your environment variables, you'll avoid common pitfalls such as misconfigured backend URLs or failed health checks due to incorrect port settings.

DB Migration

Before starting the Hoppscotch container, it’s essential to run the database migrations to ensure the database schema is properly set up. Follow these steps:

1. Start a Temporary Container for MigrationsUse the following command to launch an interactive shell inside a temporary Hoppscotch container with your environment variables loaded:

docker run -it --entrypoint sh --env-file .env hoppscotch/hoppscotch

• --env-file .env: Loads your environment variables from the .env file. Ensure this file contains the necessary database connection details.
• --entrypoint sh: Overrides the default entrypoint to start a shell session inside the container.
1. Run Database MigrationsOnce inside the container, execute the following command to apply all pending migrations using Prisma:

pnpm dlx prisma migrate deploy

• pnpm dlx prisma migrate deploy: This command applies all migrations to your database, ensuring it is ready for use with Hoppscotch.
1. Exit the ContainerAfter the migrations are successfully applied, exit the container by typing:

exit

This step is crucial because running the migrations initializes and updates your database schema, ensuring compatibility with Hoppscotch's back

Start

Once the database is set up and migrations are complete, you can start the Hoppscotch container using the following command:

docker run --name hoppscotch \
  -p 80:80 \
  --env-file .env \
  --restart unless-stopped \
  -d hoppscotch/hoppscotch

After running this command, Hoppscotch will be accessible via your browser at http://<your-server-ip> or http://localhost. If you’re using a reverse proxy with subpaths, ensure that your proxy configuration is properly set up to forward requests to this container. The admin page is reachable with the sub route /admin.