Come Fare Self-Hosting di Jan Server su un VPS (Guida Completa)

Jan Server è la metà self-hostable del progetto Jan: un insieme di microservizi Go che espongono un’API compatibile OpenAI, con integrazione di strumenti MCP, autenticazione Keycloak e un gateway Kong davanti a tutto. Non è un singolo container, e il deployment lo riflette.

La buona notizia è che il progetto include una procedura guidata che scrive la configurazione al posto tuo. La decisione principale da prendere durante il processo è dove far girare l’inferenza.

Prima di iniziare

• Un VPS con almeno 8 GB di RAM — il minimo dichiarato dal progetto, con 12 GB consigliati per l’insieme completo dei servizi
• Un’installazione Linux pulita (Ubuntu 24.04 LTS è una scelta sensata)
• Docker Engine e Docker Compose v2
• make e git
• Un nome a dominio se vuoi il TLS, cosa consigliata per qualsiasi uso oltre il test

La maggior parte dei VPS economici è da 4 GB e non basta. Questi superano la soglia:

Per un’analisi più dettagliata di questi piani, consulta il nostro confronto VPS.

Passo 1: Connettersi e installare le dipendenze

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

Verifica di avere davvero Compose v2, perché il file compose di Jan Server usa la chiave include: che v1 non comprende:

docker compose version

Passo 2: Clonare il repository

A differenza della maggior parte delle app self-hosted, qui non scrivi tu il tuo docker-compose.yml. Il file compose del repository importa frammenti per l’infrastruttura, i servizi API, gli strumenti MCP, la web app e l’inferenza.

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

Passo 3: Avviare la procedura guidata

make quickstart

La procedura guidata scrive un unico .env nella root e poi avvia Compose. Chiede tre cose:

• Provider LLM — vLLM locale, che scarica i modelli e richiede una GPU, oppure un endpoint remoto compatibile OpenAI, che non richiede nessuno dei due. Su un VPS standard, scegli l’endpoint remoto.
• Provider di ricerca MCP — Serper richiede una API key, SearXNG gira in locale senza bisogno di una, oppure puoi disattivare la ricerca mantenendo comunque il servizio degli strumenti MCP.
• Media API — attivala per gli upload, oppure lasciala disattivata per il runtime più leggero.

Se non puoi eseguire la procedura guidata in modo interattivo, copia il template e compilalo manualmente:

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

make setup verifica le dipendenze, crea le directory e scarica le immagini di base senza avviare nulla.

Passo 4: Avviare lo stack

make up-full

Una volta che i container si sono stabilizzati, hai a disposizione:

La documentazione API è servita su http://your-vps-ip:8000/api/swagger/index.html.

Passo 5: Mettere in sicurezza prima di esporre

Questo è il passaggio da non saltare. Due impostazioni predefinite non sono sicure su un server pubblico:

1. La console di Keycloak viene fornita con admin / admin. Cambiala subito sulla porta 8085. Keycloak emette i token che Kong convalida, quindi questa singola credenziale protegge l’intera superficie API.
2. Solo la porta 8000 dovrebbe essere raggiungibile dall’esterno. Kong applica i controlli su JWT e API key; le porte dei servizi dietro di esso no. Vincola le altre a localhost oppure bloccale a livello di firewall.

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

Poi termina il TLS con Caddy, Traefik o Nginx e fai da proxy verso la porta 8000. Lasciare un endpoint LLM non autenticato sull’internet pubblico lo fa trovare e usare da qualcun altro, di solito nel giro di pochi giorni.

Eseguire l’inferenza in locale

Se hai scelto vLLM locale, il frammento di inferenza definisce due profili. Il profilo GPU esegue vllm/vllm-openai:v0.11.2 con janhq/Jan-v1-4B come modello predefinito e riserva un dispositivo NVIDIA, quindi non si avvierà su un VPS tipico. Il profilo CPU funziona senza GPU ed è davvero utilizzabile per i test, ma la generazione dei token su vCPU condivise è abbastanza lenta da sconsigliarlo davanti agli utenti.

Affittare capacità GPU e puntarci Jan Server come endpoint remoto costa di solito meno di un server GPU che resta inattivo tra un prompt e l’altro.

Gestione quotidiana

Aggiornare a una release più recente:

git pull
docker compose pull
make up-full

Esegui il backup del volume Postgres e del tuo .env nella root. Il .env contiene i segreti generati dalla procedura guidata, e ripristinare un database senza di esso lascia sessioni che non puoi decifrare.

Controlla cosa sta facendo un servizio con docker compose logs -f llm-api, sostituendo il servizio che ti interessa.

Problemi comuni

Jan Server chiede di più a un VPS rispetto a una tipica app self-hosted, soprattutto perché porta con sé il proprio gateway, identity provider e database invece di darli per scontati. Dimensiona per 8 GB, metti Kong dietro TLS e cambia la password di Keycloak prima di ogni altra cosa.