Cómo instalar Hoppscotch en un VPS

Requisitos previos

Prepara Ubuntu 22.04 o 24.04 con SSH, IP pública, al menos 2 GB de RAM y un dominio como api-tools.example.com. La instalación completa incluye frontend, backend y persistencia, así que revisa requisitos oficiales antes de elegir VPS.

Necesitas Docker Compose, backup externo y una base de datos PostgreSQL (versión 14+) accesible desde tu VPS. También define una política para las API keys guardadas por usuarios. Nunca uses un servidor demo público con credenciales reales.

Paso 1, Conectarte a tu servidor

Actualiza el host y crea una carpeta solo para administradores:

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

Deja 80 y 443 para el proxy. No expongas públicamente la base, mail o APIs internas.

Paso 2, Instalar Docker y Docker Compose

Instala Docker y Compose con las instrucciones actuales para Ubuntu:

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

Revisa recursos y usa las versiones de Node, base e imágenes soportadas por el release de Hoppscotch elegido.

Paso 3, Ejecutar el stack mantenido de Hoppscotch

Usa la documentación y el repositorio oficiales de self-hosting para obtener el Compose actual. Colócalo en /opt/hoppscotch, lee el ejemplo de entorno y sustituye todos los secretos. El stack puede añadir servicios o variables, así que no lo reduzcas a un frontend para producción.

Crea un archivo .env con al menos las siguientes variables:

DATABASE_URL=postgresql://usuario:contraseña@host:5432/hoppscotch
DATA_ENCRYPTION_KEY=REEMPLAZAR_CON_HEX_DE_32_CARACTERES
WHITELISTED_ORIGINS=http://localhost:3000,https://tudominio.com
VITE_BASE_URL=https://tudominio.com
VITE_BACKEND_GQL_URL=https://tudominio.com/graphql
VITE_BACKEND_WS_URL=wss://tudominio.com/graphql
VITE_ADMIN_URL=https://tudominio.com/admin

La DATA_ENCRYPTION_KEY debe tener exactamente 32 caracteres. Generala con openssl rand -hex 16.

NO envuelvas los valores de las variables de entorno entre comillas. Hoppscotch los lee literalmente y las comillas se tratarían como parte del valor.

La imagen AIO incluye un servidor Caddy integrado en el puerto 80, por lo que puede que no necesites un proxy inverso externo para configuraciones básicas.

Usa los nombres exactos del release y no subas .env a Git. Valida el proyecto:

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

Después de iniciar, ejecuta las migraciones de Prisma:

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

Ejecuta los seeds documentados antes de abrir registros. Revisa frontend y backend por separado.

Seguridad: Nunca expongas el puerto 3100 (admin UI) a internet público. Mantenlo detrás de un firewall o restringido a redes internas.

Paso 4, Configurar el proxy inverso

Dirige el hostname web al puerto del servicio indicado por Compose. Usa Caddy o Nginx para HTTPS, conserva las cabeceras reenviadas y configura websockets si el release los usa. Mantén PostgreSQL y APIs internas privadas.

Prueba login, una petición desde el cliente web y cualquier callback de auth. Comprueba cookies secure y que no haya mixed content.

Paso 5, Primer acceso y configuración inicial

Abre HTTPS y crea el administrador u organización. Registra un usuario de prueba, una colección y una petición a una API desechable. Verifica que la colección sobrevive al reinicio y que los permisos funcionan con otro usuario.

Configura email solo después de proteger SMTP. Revisa si requests y responses pueden contener tokens o datos personales antes de activar workspaces compartidos.

Mantenimiento

Haz backup de base, colecciones y secretos de entorno. Prueba un restore en otro host. Actualiza el stack oficial leyendo migraciones y prueba auth, colecciones y ejecución tras cada release.

Monitoriza memoria, conexiones, errores del proxy y jobs. Si carga la UI pero falla sync, revisa backend y websocket antes de reconstruir frontend.