Como Fazer Self-Hosting do Jan Server num VPS (Guia Completo)

Jan Server é a metade self-hostable do projeto Jan: um conjunto de microsserviços em Go que expõe uma API compatível com OpenAI, com integração de ferramentas MCP, autenticação via Keycloak e uma gateway Kong à frente. Não é um único contentor, e a implementação reflete isso.

A boa notícia é que o projeto disponibiliza um assistente de configuração que escreve a configuração por si. A principal decisão que toma durante o processo é onde corre a inferência.

Antes de começar

• Um VPS com pelo menos 8 GB de RAM — o mínimo indicado pelo projeto, com 12 GB recomendados para o conjunto completo de serviços
• Uma instalação Linux limpa (o Ubuntu 24.04 LTS é uma escolha sensata por predefinição)
• Docker Engine e Docker Compose v2
• make e git
• Um nome de domínio se quiser TLS, o que é necessário para qualquer coisa além de um teste

A maioria dos planos VPS baratos tem 4 GB e não chega. Estes cumprem o mínimo:

Para uma análise mais completa destes planos, veja a nossa comparação de VPS.

Passo 1: Ligar-se e instalar as dependências

ssh user@your-vps-ip

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io docker-compose-v2 make git
sudo systemctl enable --now docker

Confirme que obteve o Compose v2, porque o ficheiro compose do Jan Server usa a chave include:, que a v1 não entende:

docker compose version

Passo 2: Clonar o repositório

Ao contrário da maioria das apps self-hosted, aqui não escreve o seu próprio docker-compose.yml. O ficheiro compose do repositório importa fragmentos para a infraestrutura, os serviços de API, as ferramentas MCP, a app web e a inferência.

git clone https://github.com/janhq/server.git
cd server

Passo 3: Correr o assistente de configuração

make quickstart

O assistente escreve um único .env na raiz e depois arranca o Compose. Pergunta três coisas:

• Fornecedor de LLM — vLLM local, que transfere modelos e espera uma GPU, ou um endpoint remoto compatível com OpenAI, que não precisa de nenhuma. Num VPS normal, escolha o endpoint remoto.
• Fornecedor de pesquisa MCP — o Serper precisa de uma chave de API, o SearXNG corre localmente sem nenhuma, ou pode desativar a pesquisa e manter mesmo assim o serviço de ferramentas MCP.
• Media API — ative-a para uploads, ou deixe-a desligada para o runtime mais pequeno.

Se não conseguir correr o assistente de forma interativa, copie o modelo e preencha-o em vez disso:

cp .env.template .env
nano .env
make setup

O make setup verifica as dependências, cria as pastas e descarrega as imagens base sem arrancar nada.

Passo 4: Arrancar a stack

make up-full

Assim que os contentores estabilizarem, tem:

A documentação da API é servida em http://your-vps-ip:8000/api/swagger/index.html.

Passo 5: Proteger antes de expor

Este é o passo a não saltar. Duas predefinições são inseguras num servidor público:

1. A consola do Keycloak vem com admin / admin. Altere isto imediatamente na porta 8085. O Keycloak emite os tokens que o Kong valida, por isso esta única credencial protege toda a superfície da API.
2. Só a porta 8000 deve ser acessível a partir do exterior. O Kong aplica as verificações de JWT e de chave de API; as portas dos serviços por trás dele não. Vincule as restantes a localhost ou bloqueie-as na firewall.

sudo ufw allow OpenSSH
sudo ufw allow 443/tcp
sudo ufw enable

Depois termine o TLS com Caddy, Traefik ou Nginx e faça proxy para a porta 8000. Deixar um endpoint de LLM sem autenticação na internet pública leva a que seja encontrado e usado por outra pessoa, normalmente em poucos dias.

Correr a inferência localmente

Se optou pelo vLLM local, o fragmento de inferência define dois perfis. O perfil de GPU corre vllm/vllm-openai:v0.11.2 com janhq/Jan-v1-4B como modelo predefinido e reserva um dispositivo NVIDIA, por isso não arranca num VPS típico. O perfil de CPU corre sem GPU e é genuinamente utilizável para testes, mas a geração de tokens em vCPUs partilhadas é lenta o suficiente para não o querer à frente de utilizadores.

Alugar capacidade de GPU e apontar o Jan Server para ela como endpoint remoto costuma sair mais barato do que um servidor de GPU parado entre pedidos.

Operação do dia a dia

Atualizar para uma versão mais recente:

git pull
docker compose pull
make up-full

Faça cópia de segurança do volume do Postgres e do .env na raiz. O .env guarda os segredos que o assistente gerou, e restaurar uma base de dados sem ele deixa-o com sessões que não consegue decifrar.

Verifique o que um serviço está a fazer com docker compose logs -f llm-api, substituindo pelo serviço que lhe interessa.

Problemas comuns

O Jan Server exige mais de um VPS do que uma app self-hosted típica, sobretudo porque traz a sua própria gateway, o seu próprio fornecedor de identidade e a sua própria base de dados, em vez de assumir que já os tem. Dimensione para 8 GB, coloque o Kong atrás de TLS e altere a palavra-passe do Keycloak antes de tudo o resto.