Como instalar o Hoppscotch em um VPS

Pré-requisitos

Prepare o Ubuntu 22.04 ou 24.04 com SSH, um IP público, pelo menos 2 GB de RAM e um domínio como api-tools.example.com. Uma instalação completa inclui interface, back-end e serviços de persistência, então confira os requisitos oficiais atuais antes de escolher o VPS.

Você precisa do Docker Compose, de um destino externo para backups e de um banco de dados PostgreSQL (versão 14 ou superior) acessível pelo VPS. Defina também uma política para as chaves de API que os usuários podem salvar nas coleções. Nunca use um servidor de demonstração público com credenciais reais de produção.

Etapa 1, Conectar ao servidor

Atualize o servidor e crie um diretório acessível apenas pelo administrador:

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

Mantenha as portas 80 e 443 disponíveis para o proxy. Não exponha publicamente portas de banco de dados, e-mail ou APIs internas.

Etapa 2, Instalar o Docker e o Docker Compose

Instale o Docker Engine e o Compose seguindo as instruções atuais do Docker para Ubuntu:

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

Confira os recursos disponíveis e use as versões de Node, banco de dados e imagens compatíveis com a versão do Hoppscotch escolhida.

Etapa 3, Executar a pilha mantida do Hoppscotch

Use a documentação oficial de hospedagem própria e o repositório para obter os arquivos Compose atuais. Coloque-os em /opt/hoppscotch, leia o exemplo de ambiente e substitua todos os valores de segredo de exemplo. A pilha pode ganhar serviços ou variáveis entre versões, então não a reduza a um arquivo Compose apenas com a interface para uso em produção.

Crie um arquivo .env com pelo menos as variáveis a seguir:

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

DATA_ENCRYPTION_KEY deve ter exatamente 32 caracteres. Gere-o com openssl rand -hex 16.

NÃO coloque os valores das variáveis de ambiente entre aspas. O Hoppscotch os lê literalmente e as aspas serão consideradas parte do valor.

A imagem AIO inclui um servidor Caddy integrado na porta 80, portanto talvez não seja necessário um proxy reverso externo em configurações básicas.

Use os nomes exatos das variáveis da versão e não inclua .env no Git. Valide o projeto fornecido:

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

Depois de iniciar, execute as migrações do Prisma:

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

Execute as etapas de preparação documentadas antes de abrir o cadastro. Inspecione separadamente os logs da interface e do back-end.

Segurança: Nunca exponha a porta 3100 (interface de administração) à internet pública. Mantenha-a atrás de um firewall ou restrinja-a às redes internas.

Etapa 4, Configurar o proxy reverso

Direcione o nome de host público do Hoppscotch para a porta de serviço definida no arquivo Compose oficial. Use Caddy ou Nginx para HTTPS, preserve os cabeçalhos encaminhados e configure o encaminhamento de WebSocket se a versão o utilizar. Mantenha o PostgreSQL e as APIs internas privados.

Teste o login, uma solicitação de API feita pela interface web e qualquer retorno usado pelo fluxo de autenticação. Confirme que os cookies estão marcados como seguros e que o navegador não informa conteúdo misto.

Etapa 5, Primeiro acesso e configuração inicial

Abra o nome de host HTTPS e crie um administrador ou uma organização. Cadastre um usuário de teste, crie uma coleção e envie uma solicitação para uma API descartável. Verifique se a coleção continua disponível após uma reinicialização e se as permissões de acesso funcionam para um segundo usuário.

Configure o e-mail somente depois de proteger as credenciais SMTP. Antes de habilitar espaços de trabalho compartilhados, avalie se os corpos das solicitações e respostas podem conter tokens ou informações pessoais.

Manutenção

Faça backup do banco de dados, dos dados das coleções e dos segredos de ambiente. Teste a restauração em um servidor limpo. Atualize a pilha oficial depois de ler as notas de migração e teste a autenticação, as coleções e a execução de solicitações após cada versão.

Monitore a memória, as conexões com o banco de dados, os erros do proxy e as tarefas com falha. Se a interface web carregar, mas a sincronização falhar, inspecione o back-end e o caminho WebSocket antes de reconstruir a interface.