OpenViking Server Operations
This guide provides standard operating procedures for deploying, managing, and maintaining OpenViking servers in production environments.
Table of Content
-
Service Configuration
-
Environment Setup with uv
-
Server Startup with nohup
-
Server Shutdown
-
Data Cleanup Procedure
-
Verification and Troubleshooting
Service Configuration
Default Paths and Structure
OpenViking uses the following standard directory structure under ~/.openviking/ :
~/.openviking/ ├── ov.conf # Server configuration (required) ├── ovcli.conf # CLI client configuration ├── ov-venv/ # Virtual environment (created by uv) ├── log/ # Server log directory │ ├── openviking-server.log # server stdout log │ └── openviking.log # server log └── data/ # Workspace data (configured in ov.conf) ├── ... └── ...
Configuration Files
- Server Config (~/.openviking/ov.conf )
Create the configuration file with at minimum the following configuration. Note 1: Replace the api-key with your own api-key. If you don't have one, ask the user to get one (follow the Volcengine Ark platform guide). Note 2: Replace the root_api_key with your own root-api-key. Ask the user to set one — it will be used for authentication when the CLI connects to the server.
{ "server": { "host": "0.0.0.0", "port": 1933, "root_api_key": "your-root-api-key" }, "storage": { "workspace": "~/.openviking/data/" }, "parsers": { "code": { "gitlab_domains": ["code.byted.org"] } }, "embedding": { "dense": { "model": "doubao-embedding-vision-250615", "api_key": "your-volcengine-api-key", "api_base": "https://ark.cn-beijing.volces.com/api/v3", "dimension": 1024, "input": "multimodal", "provider": "volcengine" } }, "vlm": { "model": "doubao-seed-1-8-251228", "api_key": "your-volcengine-api-key", "api_base": "https://ark.cn-beijing.volces.com/api/v3", "temperature": 0.0, "max_retries": 2, "provider": "volcengine", "thinking": false }, "log": { "level": "INFO", "output": "file", "rotation": true, "rotation_days": 3, "rotation_interval": "midnight" } }
- CLI Config (~/.openviking/ovcli.conf )
For client connections from localhost:
{ "url": "http://localhost:1933", "api_key": "your-root-api-key" }
For remote connections, set the url to the remote server address (for example, the server EIP).
Environment Setup with uv
Step 1: Install uv (if not already installed)
macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Verify installation
uv --version
Step 2: Create Virtual Environment
Create a dedicated virtual environment at ~/.openviking/ov-venv :
Create venv with Python 3.10+
cd ~/.openviking uv venv --python 3.12 ov-venv
Step 3: Activate and Install OpenViking
Activate the virtual environment
source ~/.openviking/ov-venv/bin/activate
Install or upgrade to latest openviking
uv pip install --upgrade openviking --force-reinstall
Verify installation
which openviking-server openviking-server --version openviking-server --help
Step 4: Create Log Directory
mkdir -p ~/.openviking/log
Server Startup with nohup
Standard Startup Procedure
1. Activate the virtual environment
source ~/.openviking/ov-venv/bin/activate
2. Ensure log directory exists
mkdir -p ~/.openviking/log
3. Start server with nohup
nohup openviking-server
> ~/.openviking/log/openviking-server.log 2>&1 &
4. Save PID for later reference
echo $! > ~/.openviking/server.pid
5. Verify startup after 10 secs
sleep 10 curl -s http://localhost:1933/health
Verify Server is Running
Method 1: Check health endpoint
curl http://localhost:1933/health
Expected: {"status": "ok"}
Method 2: Check readiness (includes storage checks)
curl http://localhost:1933/ready
Method 3: Check process
ps aux | grep openviking-server | grep -v grep
Method 4: Check log output
tail -10 ~/.openviking/log/openviking-server.log tail -50 ~/.openviking/log/openviking.log
Server Shutdown
Graceful Shutdown Procedure
1. Find the server process
ps aux | grep openviking-server | grep -v grep
2. Send SIGTERM for graceful shutdown
Option A: Using saved PID
if [ -f ~/.openviking/server.pid ]; then kill $(cat ~/.openviking/server.pid) rm ~/.openviking/server.pid fi
Option B: Using pgrep
pkill -f openviking-server
3. Wait for process to stop
sleep 3
4. Verify it stopped
ps aux | grep openviking-server | grep -v grep || echo "Server stopped successfully"
5. If still running, force kill
if pgrep -f openviking-server > /dev/null; then echo "Force killing server..." pkill -9 -f openviking-server fi
Data Cleanup Procedure
When to Use This Procedure
Perform full data cleanup in these scenarios:
-
Version upgrade with incompatible data format
-
Corrupted or inconsistent data
-
Need to reset to fresh state
-
Storage space reclamation
Standard Cleanup Workflow
CRITICAL: ALWAYS BACKUP BEFORE DELETING DATA
==========================================
STEP 1: STOP THE SERVER FIRST
==========================================
echo "Step 1: Stopping OpenViking Server..." if pgrep -f openviking-server > /dev/null; then pkill -f openviking-server sleep 3 if pgrep -f openviking-server > /dev/null; then pkill -9 -f openviking-server sleep 1 fi fi
Verify server is stopped
if pgrep -f openviking-server > /dev/null; then echo "ERROR: Server still running! Cannot proceed." exit 1 fi echo "✓ Server stopped"
==========================================
STEP 2: CREATE BACKUP (REQUIRED)
==========================================
echo "" echo "Step 2: Creating backup..." BACKUP_DATE=$(date +%Y%m%d_%H%M%S) BACKUP_DIR=~/.openviking/backup_${BACKUP_DATE}
mkdir -p ${BACKUP_DIR}
Backup config files
cp ~/.openviking/ov.conf ${BACKUP_DIR}/ 2>/dev/null || true cp ~/.openviking/ovcli.conf ${BACKUP_DIR}/ 2>/dev/null || true
Backup workspace (if exists)
WORKSPACE=$(python3 -c '
import json
import os
config_path = os.path.expanduser("/.openviking/ov.conf")
if os.path.exists(config_path):
with open(config_path) as f:
cfg = json.load(f)
ws = cfg.get("storage", {}).get("workspace", "./data")
print(os.path.expanduser(ws))
' 2>/dev/null || echo "/.openviking/data")
if [ -d "${WORKSPACE}" ]; then echo "Backing up workspace: ${WORKSPACE}" tar -czf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE}) $(basename ${WORKSPACE}) fi
Backup log
if [ -d ~/.openviking/log ]; then cp -r ~/.openviking/log ${BACKUP_DIR}/ 2>/dev/null || true fi
echo "✓ Backup created at: ${BACKUP_DIR}" ls -lh ${BACKUP_DIR}/
==========================================
STEP 3: CONFIRM DELETION
==========================================
echo "" echo "==========================================" echo "WARNING: ABOUT TO DELETE ALL DATA!" echo "==========================================" echo "Workspace to delete: ${WORKSPACE}" echo "Backup location: ${BACKUP_DIR}" echo "" read -p "Type 'DELETE' to confirm data removal: " CONFIRM
if [ "${CONFIRM}" != "DELETE" ]; then echo "Cleanup cancelled. Backup preserved at ${BACKUP_DIR}" exit 0 fi
==========================================
STEP 4: DELETE DATA
==========================================
echo "" echo "Step 4: Deleting data..."
Delete workspace
if [ -d "${WORKSPACE}" ]; then echo "Deleting workspace: ${WORKSPACE}" rm -rf "${WORKSPACE}" fi
Optional: Delete old log (uncomment if needed)
echo "Deleting old log..."
rm -rf ~/.openviking/log/*
Cleanup any temporary files
rm -f ~/.openviking/server.pid
echo "✓ Data deleted successfully"
==========================================
STEP 5: COMPLETION
==========================================
echo "" echo "==========================================" echo "Cleanup Complete!" echo "==========================================" echo "Backup preserved at: ${BACKUP_DIR}" echo "" echo "Next steps:" echo "1. Reconfigure ov.conf if needed" echo "2. Start the server: openviking-server" echo "3. Verify with: curl http://localhost:1933/health" echo "" echo "To restore from backup:" echo " tar -xzf ${BACKUP_DIR}/workspace_backup.tar.gz -C $(dirname ${WORKSPACE})"
Quick Cleanup (for Development Only)
WARNING: Only use in development!
No backup created - data loss guaranteed!
1. Stop server
pkill -f openviking-server sleep 2 pkill -9 -f openviking-server 2>/dev/null || true
2. Delete workspace (adjust path as needed)
rm -rf ~/.openviking/data
3. Cleanup PID and temp files
rm -f ~/.openviking/server.pid
echo "Quick cleanup complete"
Verification and Troubleshooting
Health Check Verification
Basic health check (always available)
curl http://localhost:1933/health
Expected: {"status": "ok"}
Readiness check (verifies all components)
curl http://localhost:1933/ready
Expected: {"status": "ready", "checks": {"agfs": "ok", "vectordb": "ok", "api_key_manager": "ok"}}
System status via CLI (~/.openviking/ovcli.conf should be configured)
ov status
Common Issues and Solutions
Issue: Server won't start
Check:
1. Check if port is in use
lsof -i :1933 netstat -tulpn | grep 1933
2. Check log for errors
tail -10 ~/.openviking/log/openviking-server.log tail -100 ~/.openviking/log/openviking.log
3. Verify config file is valid JSON
python3 -c 'import json, os; json.load(open(os.path.expanduser("~/.openviking/ov.conf"))); print("Config is valid")'
4. Verify virtual environment
source ~/.openviking/ov-venv/bin/activate which openviking-server pip list | grep openviking
Solution:
If port conflict: kill the process or use different port
lsof -ti :1933 | xargs kill -9 2>/dev/null || true
Or start on different port
nohup openviking-server --port 1934 > ~/.openviking/log/openviking-server.log 2>&1 &
Issue: API Key Errors
Check:
Verify API keys in config
python3 -c ' import json, os cfg = json.load(open(os.path.expanduser("~/.openviking/ov.conf"))) print("Embedding provider:", cfg.get("embedding", {}).get("dense", {}).get("provider")) print("VLM provider:", cfg.get("vlm", {}).get("provider")) print("API keys set:", bool(cfg.get("embedding", {}).get("dense", {}).get("api_key")), bool(cfg.get("vlm", {}).get("api_key"))) '
Solution: Verify API keys are correct and have the required permissions. Check network connectivity to the model provider endpoints. Ensure API keys are not expired.
Prerequisites
-
Python 3.10+ installed
-
uv package manager available
-
Sufficient disk space for workspace and log
-
API keys for embedding and VLM models configured
-
Network access to model providers (if using cloud models)