How to install Hoppscotch on a VPS

Prerequisites

Prepare Ubuntu 22.04 or 24.04 with SSH, a public IP, at least 2 GB of RAM and a domain such as api-tools.example.com. A full installation includes frontend, backend and persistence services, so review the current official requirements before choosing the VPS.

You need Docker Compose, an external backup target and a PostgreSQL database (version 14+) accessible from your VPS. Also define a policy for API keys that users may save in collections. Never use a public demo server for real production credentials.

Step 1, Connecting to your server

Patch the host and create an administrator-only directory:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl git
mkdir -p /opt/hoppscotch
cd /opt/hoppscotch
chmod 750 /opt/hoppscotch

Keep ports 80 and 443 available for the proxy. Do not expose database, mail or internal API ports publicly.

Step 2, Installing Docker and Docker Compose

Install Docker Engine and Compose using Docker's current Ubuntu instructions:

docker --version
docker compose version
systemctl enable --now docker

Check available resources and use the Node, database and image versions supported by the Hoppscotch release you select.

Step 3, Running the maintained Hoppscotch stack

Use the official self-hosting documentation and repository to obtain the current Compose files. Place them in /opt/hoppscotch, read the environment example and replace every secret placeholder. The stack can add services or variables between releases, so do not reduce it to a frontend-only Compose file for production.

Create a .env file with at least the following variables:

DATABASE_URL=postgresql://user:password@host:5432/hoppscotch
DATA_ENCRYPTION_KEY=REPLACE_WITH_32_CHAR_HEX_STRING
WHITELISTED_ORIGINS=http://localhost:3000,https://yourdomain.com
VITE_BASE_URL=https://yourdomain.com
VITE_BACKEND_GQL_URL=https://yourdomain.com/graphql
VITE_BACKEND_WS_URL=wss://yourdomain.com/graphql
VITE_ADMIN_URL=https://yourdomain.com/admin

The DATA_ENCRYPTION_KEY must be exactly 32 characters. Generate it with openssl rand -hex 16.

Do NOT wrap environment variable values in quotes. Hoppscotch reads them literally and quotes will be treated as part of the value.

The AIO image includes a built-in Caddy server on port 80, so you may not need an external reverse proxy for basic setups.

Use the exact variable names from the release and keep .env out of Git. Validate the supplied project:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

After starting, run the Prisma migrations:

docker exec -it <container> pnpm exec prisma migrate deploy

Run any documented seed steps before opening registration. Inspect frontend and backend logs separately.

Security: Never expose port 3100 (admin UI) to the public internet. Keep it behind a firewall or restrict it to internal networks.

Step 4, Configuring the reverse proxy

Route the public Hoppscotch web hostname to the service port defined by the official Compose file. Use Caddy or Nginx for HTTPS, preserve forwarded headers and configure websocket forwarding if the release uses it. Keep PostgreSQL and internal APIs private.

Test login, an API request from the web client and any callback used by the authentication flow. Confirm that cookies are marked secure and that the browser does not report mixed content.

Step 5, First access and initial setup

Open the HTTPS hostname and create an administrator or organization. Register a test user, create a collection and send a request to a disposable API. Verify that the collection survives a restart and that access permissions work for a second user.

Configure email only after securing SMTP credentials. Review whether request and response bodies may contain tokens or personal information before enabling shared workspaces.

Maintenance

Back up the database, collection data and environment secrets. Test a restore on a clean host. Update the official stack after reading migration notes and test authentication, collections and request execution after every release.

Monitor memory, database connections, proxy errors and failed jobs. If the web UI loads but sync fails, inspect the backend and websocket path before rebuilding the frontend.