Jan Server Zelf Hosten op een VPS (Volledige Gids)

Jan Server is de zelf te hosten helft van het Jan-project: een set Go-microservices die een OpenAI-compatibele API blootstellen, met MCP-toolintegratie, Keycloak-authenticatie en een Kong-gateway ervoor. Het is geen enkele container, en dat zie je terug in de deployment.

Het goede nieuws is dat het project een installatiewizard meelevert die de configuratie voor je schrijft. De belangrijkste beslissing die je daarbij neemt, is waar de inference draait.

Voordat je begint

• Een VPS met minstens 8 GB RAM — het door het project opgegeven minimum, met 12 GB aanbevolen voor de volledige set diensten
• Een schone Linux-installatie (Ubuntu 24.04 LTS is een verstandige standaardkeuze)
• Docker Engine en Docker Compose v2
• make en git
• Een domeinnaam als je TLS wilt, wat je wilt voor alles buiten een test

De meeste goedkope VPS-plannen zijn 4 GB en voldoen niet. Deze halen wel de ondergrens:

Voor een uitgebreider overzicht van deze plannen, zie onze VPS-vergelijking.

Stap 1: Verbinden en dependencies installeren

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

Controleer of je Compose v2 hebt, want het compose-bestand van Jan Server gebruikt de include:-sleutel die v1 niet begrijpt:

docker compose version

Stap 2: Repository klonen

Anders dan bij de meeste zelf-hosted apps schrijf je hier geen eigen docker-compose.yml. Het compose-bestand van de repository trekt fragmenten binnen voor infrastructuur, de API-diensten, MCP-tools, de webapp en inference.

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

Stap 3: Installatiewizard uitvoeren

make quickstart

De wizard schrijft één root-.env en start daarna Compose. Er worden drie dingen gevraagd:

• LLM-provider — lokale vLLM, die modellen downloadt en een GPU verwacht, of een remote OpenAI-compatibel endpoint, waarvoor geen van beide nodig is. Kies op een standaard VPS voor het remote endpoint.
• MCP-zoekprovider — Serper heeft een API-sleutel nodig, SearXNG draait lokaal zonder sleutel, of je schakelt zoeken uit en houdt de MCP-toolsdienst toch actief.
• Media API — schakel hem in voor uploads, of laat hem uit voor de kleinste runtime.

Kun je de wizard niet interactief draaien, kopieer dan de template en vul die zelf in:

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

make setup controleert dependencies, maakt mappen aan en haalt de basisimages op zonder iets te starten.

Stap 4: Stack starten

make up-full

Zodra de containers stabiel draaien, heb je:

API-documentatie is te vinden op http://your-vps-ip:8000/api/swagger/index.html.

Stap 5: Beveiligen voordat je het blootstelt

Dit is de stap die je niet mag overslaan. Twee standaardinstellingen zijn onveilig op een publieke server:

1. De Keycloak-console wordt geleverd met admin / admin. Wijzig dit meteen op poort 8085. Keycloak geeft de tokens uit die Kong valideert, dus deze ene inlog beschermt het hele API-oppervlak.
2. Alleen poort 8000 mag van buitenaf bereikbaar zijn. Kong handhaaft de JWT- en API-key-controles; de poorten van de diensten erachter doen dat niet. Bind de rest aan localhost of blokkeer ze in de firewall.

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

Termineer daarna TLS met Caddy, Traefik of Nginx en proxy naar poort 8000. Een ongeauthenticeerd LLM-endpoint op het publieke internet laten staan, zorgt ervoor dat iemand anders het vindt en gebruikt, meestal binnen een paar dagen.

Inference lokaal draaien

Heb je toch voor lokale vLLM gekozen, dan definieert het inference-fragment twee profielen. Het GPU-profiel draait vllm/vllm-openai:v0.11.2 met janhq/Jan-v1-4B als standaardmodel en reserveert een NVIDIA-device, dus het start niet op een gewone VPS. Het CPU-profiel draait zonder GPU en is echt bruikbaar om te testen, maar token-generatie op gedeelde vCPU’s is traag genoeg dat je het niet voor gebruikers wilt inzetten.

GPU-capaciteit huren en Jan Server daarnaar laten wijzen als remote endpoint is meestal goedkoper dan een GPU-server die tussen prompts door stil staat.

Dagelijks beheer

Bijwerken naar een nieuwere release:

git pull
docker compose pull
make up-full

Maak back-ups van het Postgres-volume en je root-.env. De .env bevat de secrets die de wizard genereerde, en een database terugzetten zonder dat bestand levert sessies op die je niet kunt ontsleutelen.

Bekijk wat een dienst aan het doen is met docker compose logs -f llm-api, en vervang dat door de dienst die je wilt controleren.

Veelvoorkomende problemen

Jan Server vraagt meer van een VPS dan een typische zelf-hosted app, vooral omdat het zijn eigen gateway, identity provider en database meebrengt in plaats van aan te nemen dat je die al hebt. Ga uit van 8 GB, zet Kong achter TLS, en wijzig het Keycloak-wachtwoord voordat je iets anders doet.