API Development

Docker

Deploy Hoppscotch on a VPS

Self-hosted API development platform — a lightweight, open-source alternative to Postman with shared team workspaces.

Prerequisites

A RamNode VPS running Ubuntu 22.04 LTS (1 vCPU / 1 GB RAM minimum, 2 GB recommended)
A non-root sudo user
Three subdomains pointed to your server (app, API, admin)
Ports 80 and 443 open in your firewall

Required Subdomains

Service	Suggested Subdomain	Purpose
App	`hoppscotch.yourdomain.com`	Main API testing UI
Backend	`api.hoppscotch.yourdomain.com`	REST/GraphQL API server
Admin	`admin.hoppscotch.yourdomain.com`	Admin dashboard

Update the System and Install Dependencies

Update and install Nginx + Certbot

sudo apt update && sudo apt upgrade -y
sudo apt install -y nginx certbot python3-certbot-nginx

Install Docker and Docker Compose

Install Docker

curl -fsSL https://get.docker.com | sudo bash
sudo usermod -aG docker $USER
newgrp docker

Verify installation

docker --version
docker compose version

Clone the Hoppscotch Repository

Clone repository

mkdir -p /opt/hoppscotch && cd /opt/hoppscotch
git clone https://github.com/hoppscotch/hoppscotch.git .

Configure Environment Variables

Hoppscotch is configured entirely through environment variables. Copy the example file and edit it:

Create .env file

cp .env.example .env
nano .env

Database

.env — Database

POSTGRES_USER=hoppscotch
POSTGRES_PASSWORD=your_strong_db_password
POSTGRES_DB=hoppscotch
DATABASE_URL=postgresql://hoppscotch:your_strong_db_password@hoppscotch-db:5432/hoppscotch

JWT and Security Secrets

Generate secure random secrets with openssl rand -hex 32:

.env — Secrets

JWT_SECRET=your_jwt_secret_here
SESSION_SECRET=your_session_secret_here

URLs

.env — URLs

VITE_BASE_URL=https://hoppscotch.yourdomain.com
VITE_SHORTCODE_BASE_URL=https://hoppscotch.yourdomain.com
VITE_ADMIN_URL=https://admin.hoppscotch.yourdomain.com
VITE_BACKEND_GQL_URL=https://api.hoppscotch.yourdomain.com/graphql
VITE_BACKEND_WS_URL=wss://api.hoppscotch.yourdomain.com/graphql
VITE_BACKEND_API_URL=https://api.hoppscotch.yourdomain.com/v1
REDIRECT_URL=https://hoppscotch.yourdomain.com
WHITELISTED_ORIGINS=https://hoppscotch.yourdomain.com,https://admin.hoppscotch.yourdomain.com,https://api.hoppscotch.yourdomain.com

Email (SMTP)

.env — SMTP

MAILER_SMTP_URL=smtps://user:password@smtp.yourprovider.com
MAILER_ADDRESS_FROM="Hoppscotch <noreply@yourdomain.com>"

Authentication Providers

.env — OAuth (optional)

ALLOW_SECURE_COOKIES=true

# Google OAuth (optional)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=https://api.hoppscotch.yourdomain.com/v1/auth/google/callback
GOOGLE_SCOPE=email,profile

Start the Hoppscotch Stack

Start containers

docker compose up -d

Verify all four containers are running:

Check status

docker compose ps

You should see: hoppscotch-app, hoppscotch-backend, hoppscotch-admin, and hoppscotch-db.

Run Database Migrations

Apply database schema

docker compose exec hoppscotch-backend pnpx prisma migrate deploy

Configure Nginx as a Reverse Proxy

Hoppscotch's three services listen on different internal ports. Nginx handles external HTTPS traffic and proxies requests to each container.

App — hoppscotch.yourdomain.com

/etc/nginx/sites-available/hoppscotch-app

server {
    listen 80;
    server_name hoppscotch.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Backend API — api.hoppscotch.yourdomain.com

/etc/nginx/sites-available/hoppscotch-backend

server {
    listen 80;
    server_name api.hoppscotch.yourdomain.com;

    location / {
        proxy_pass http://localhost:3170;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Admin Dashboard — admin.hoppscotch.yourdomain.com

/etc/nginx/sites-available/hoppscotch-admin

server {
    listen 80;
    server_name admin.hoppscotch.yourdomain.com;

    location / {
        proxy_pass http://localhost:3100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable sites and reload

sudo ln -s /etc/nginx/sites-available/hoppscotch-app /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/hoppscotch-backend /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/hoppscotch-admin /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Issue SSL Certificates

Certbot for all three subdomains

sudo certbot --nginx \
  -d hoppscotch.yourdomain.com \
  -d api.hoppscotch.yourdomain.com \
  -d admin.hoppscotch.yourdomain.com

Confirm auto-renewal is scheduled:

Check renewal timer

sudo systemctl status certbot.timer

Create the First Admin Account

Open the admin dashboard at https://admin.hoppscotch.yourdomain.com. The first user to sign up via the main app and then log in to the admin panel is automatically promoted to admin.

From the admin panel you can invite team members, enable or disable authentication providers, view usage analytics, and manage workspaces and collections.

Configure Docker to Start on Boot

Enable Docker auto-start

sudo systemctl enable docker

Verify each service in docker-compose.yml has a restart policy:

Check restart policies

grep restart /opt/hoppscotch/docker-compose.yml

If any service is missing it, add restart: unless-stopped under each service block.

Maintenance and Updates

Viewing Logs

View logs

# All services
docker compose logs -f

# A single service
docker compose logs -f hoppscotch-backend

Updating Hoppscotch

Pull and restart

cd /opt/hoppscotch
git pull origin main
docker compose pull
docker compose up -d
docker compose exec hoppscotch-backend pnpx prisma migrate deploy

Backing Up the Database

Manual backup

docker compose exec hoppscotch-db pg_dump -U hoppscotch hoppscotch > /opt/hoppscotch/backups/hoppscotch-$(date +%F).sql

Automated Daily Backup

Add to crontab (crontab -e)

0 2 * * * docker compose -f /opt/hoppscotch/docker-compose.yml exec -T hoppscotch-db pg_dump -U hoppscotch hoppscotch > /opt/hoppscotch/backups/hoppscotch-$(date +\%F).sql

Troubleshooting

Containers are not starting

Check logs for the failing service. The most common causes are incorrect DATABASE_URL values and missing migration runs.

Check backend logs

docker compose logs hoppscotch-backend

502 Bad Gateway

Nginx is working but the upstream container is not responding. Verify the container is running on the expected port:

Debug 502

docker compose ps
docker inspect hoppscotch-app | grep HostPort

Migration errors

Check migration status

docker compose ps hoppscotch-db
docker compose exec hoppscotch-backend pnpx prisma migrate status

Email sign-in is not working

Double-check your MAILER_SMTP_URL value. The format for SMTPS is smtps://username:password@host:465.

Test SMTP connectivity

docker compose exec hoppscotch-backend nc -zv smtp.yourprovider.com 465

More Deployment Guides•View Cloud VPS Plans