Llamatik Server on Llamatik Documentation

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started

This page walks through installing Llamatik Server, running it, and making your first inference request.

Requirements

JVM 21+
A GGUF model file (e.g. tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf)
Docker (optional, for containerised deployment)

Clone and build

git clone https://github.com/ferranpons/Llamatik-Server.git
cd Llamatik-Server
./gradlew build

Run locally

./gradlew run

The server starts on http://localhost:8080 by default.

Minimal environment

export JWT_SECRET="change-me-in-production"
export JDBC_DRIVER="org.h2.Driver"
export JDBC_DATABASE_URL="jdbc:h2:mem:llamatik;DB_CLOSE_DELAY=-1"

JWT_SECRET signs user tokens. JDBC_* configure the user/profile database (H2 in-memory is fine for local development; use PostgreSQL for production). To create the PostgreSQL database and schema, run ./scripts/setup-db.sh from the server repository (idempotent; options -h, -p, -U, -d). See Configuration for all variables.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration

Llamatik Server is configured through environment variables. For local development, local.properties can supply them (see below).

Environment variables

Required

Variable	Description
`JWT_SECRET`	HMAC-512 secret used to sign and verify JWT tokens. Use a long random string in production.
`JDBC_DRIVER`	JDBC driver class, e.g. `org.postgresql.Driver` or `org.h2.Driver`
`JDBC_DATABASE_URL`	Full JDBC connection URL, e.g. `jdbc:postgresql://db:5432/llamatik`

Database (optional)

Variable	Default	Description
`DB_USER`	—	Database username
`DB_PASSWORD`	—	Database password
`DB_MAX_POOL_SIZE`	`3`	HikariCP connection pool size

Network discovery (mDNS)

The server advertises itself on the local network as a _llamatik._tcp service so the Llamatik app can find it from Settings → Connect to Server → Scan.

Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Deployment

Docker

Build the image

git clone https://github.com/ferranpons/Llamatik-Server.git
cd Llamatik-Server
docker build -t llamatik-server .

Run the container

docker run -d \
 --name llamatik \
 -p 8080:8080 \
 -v /srv/models:/models \
 -e JWT_SECRET="change-me" \
 -e JDBC_DRIVER="org.h2.Driver" \
 -e JDBC_DATABASE_URL="jdbc:h2:mem:llamatik;DB_CLOSE_DELAY=-1" \
 -e MODELS_DIR=/models \
 llamatik-server

Mount your model directory to /models inside the container and set MODELS_DIR=/models so path validation works correctly.

Docker Compose (with PostgreSQL)

version: "3.9"

services:
 db:
 image: postgres:16-alpine
 environment:
 POSTGRES_DB: llamatik
 POSTGRES_USER: llamatik
 POSTGRES_PASSWORD: secret
 volumes:
 - pgdata:/var/lib/postgresql/data

 llamatik:
 image: llamatik-server:latest
 ports:
 - "8080:8080"
 volumes:
 - /srv/models:/models
 environment:
 JWT_SECRET: "change-me-in-production"
 JDBC_DRIVER: "org.postgresql.Driver"
 JDBC_DATABASE_URL: "jdbc:postgresql://db:5432/llamatik"
 DB_USER: llamatik
 DB_PASSWORD: secret
 MODELS_DIR: /models
 SESSIONS_DIR: /models/sessions
 depends_on:
 - db

volumes:
 pgdata:

systemd (Linux)

Create /etc/systemd/system/llamatik.service: