ov-server-operate

# 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 #### 1. 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. ```json { "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"], "azure_devops_domains": ["ssh.dev.azure.com", "vs-ssh.visualstudio.com"] } }, "embedding": { "dense": { "model": "doubao-embedding-vision-251215", "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" } } ``` #### 2. CLI Config (`~/.openviking/ovcli.conf`) For client connections from localhost: ```json { "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) ```bash # 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`: ```bash # Create venv with Python 3.10+ cd ~/.openviking uv venv --python 3.12 ov-venv ``` ### Step 3: Activate and Install OpenViking ```bash # 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 ```bash mkdir -p ~/.openviking/log ``` ## Server Startup with nohup ### Standard Startup Procedure ```bash # 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 ```bash # 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 ```bash # 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: 1. Version upgrade with incompatible data format 2. Corrupted or inconsistent data 3. Need to reset to fresh state 4. Storage space reclamation ### Standard Cleanup Workflow **CRITICAL: ALWAYS BACKUP BEFORE DELETING DATA** ```bash # ========================================== # 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!"