homelab-infra/apps/openviking/README.md

OpenViking (Docker)

This folder contains a Docker Compose setup for OpenViking using the official image.

What this setup assumes

• VLM provider: openai-codex
• Embedding model family: jina-embeddings-v5-text-small-clustering
• Embedding server: local OpenAI-compatible endpoint powered by llama.cpp CUDA12 image
• Persistent OpenViking data lives in ./data
• Persistent embedding model cache lives in ./models (mounted to Hugging Face cache)
• HTTP API is exposed on 1933
• Console/UI is exposed on 8020
• Local embedding endpoint is exposed on 127.0.0.1:8081

Files

• docker-compose.yml — the container definition
• .env.example — optional port/bot defaults
• ov.conf.example — configuration example using local Jina embeddings + Codex VLM
• ovcli.conf.example — CLI/client config example

Setup

1. Copy the env template:

cp .env.example .env

2. Create the persistent directories and copy the config examples:

mkdir -p data models
cp ov.conf.example data/ov.conf
cp ovcli.conf.example data/ovcli.conf
mkdir -p data/workspace

3. Start the containers:

docker compose up -d

4. If Codex auth is not yet available, complete the login/import step inside the OpenViking container:

docker compose exec -it openviking openviking-server init

5. Verify the server:

docker compose exec -it openviking openviking-server doctor
curl http://localhost:1933/health

Notes

• The embedding service uses the Jina v5 omni small text-matching GGUF model and serves an OpenAI-compatible /v1 API locally.
• provider: "openai" is used in ov.conf because the embedding endpoint is OpenAI-compatible, even though the underlying model is Jina.
• provider: "openai-codex" does not require vlm.api_key once Codex OAuth is available through openviking-server init.
• If you want the bundled VikingBot disabled, set OPENVIKING_WITH_BOT=0 in .env.
• The first startup can take a while because the Jina model must be downloaded into ./models.