Skip to content

CONFIGURATION.md

Latest commit

 

History

History
185 lines (131 loc) · 7.75 KB

CONFIGURATION.md

File metadata and controls

185 lines (131 loc) · 7.75 KB

Configuration

← Back to README

Configuration is managed through infrastructure/.env.

Environment Variables

Infrastructure (set in infrastructure/.env)

Variable Required Description Default / Example
DOMAIN Yes Base domain for your installation example.com
DASHBOARD_SUBDOMAIN Yes Dashboard subdomain dashboard
API_SUBDOMAIN Yes API subdomain api
DASHBOARD_URL Yes Full dashboard URL (used for OAuth callbacks, Telegram links) https://dashboard.example.com
API_URL Yes Full API URL (used for proxy model config) https://api.example.com
DATABASE_URL Yes PostgreSQL connection string postgresql://user:pass@host:5432/db
POSTGRES_PASSWORD Yes PostgreSQL password Generated by installer
JWT_SECRET Yes JWT signing secret (min 32 chars) Generated by installer
MANAGEMENT_API_KEY Yes CLIProxyAPI management API key (min 16 chars) Generated by installer
INSTALL_DIR Yes Absolute path to project root Set by installer
TZ No Server timezone UTC

Dashboard (set in infrastructure/.env or container environment)

Variable Required Description Default
CLIPROXYAPI_MANAGEMENT_URL No Internal management API URL http://cliproxyapi:8317/v0/management
NODE_ENV No Runtime environment development
JWT_EXPIRES_IN No JWT token expiration time 7d
LOG_LEVEL No Pino log level (fatal, error, warn, info, debug, trace) info
LOG_DIR No Directory for log file storage <cwd>/logs
CLIPROXYAPI_CONTAINER_NAME No Docker container name for CLIProxyAPI cliproxyapi
DOCKER_HOST No Docker socket proxy URL (for container management) tcp://docker-proxy:2375
GITHUB_REPO No GitHub repo for update checks itsmylife44/cliproxyapi-dashboard
SYNC_TOKEN_MAX_AGE_DAYS No Config sync token expiration in days 90
COLLECTOR_API_KEY No API key for automated usage collection cron service (64-char hex) Generated by installer
BACKUP_SCHEDULER_KEY No API key for the backup scheduler cron service (64-char hex) Generated by installer
ALLOW_LOCAL_PROVIDER_URLS No Permit custom providers to target localhost / RFC1918 (Ollama, LM Studio, llama.cpp). Cloud metadata (169.254.169.254, 100.100.100.200) stays blocked. false

Perplexity Sidecar

Variable Required Description Default
PERPLEXITY_SIDECAR_SECRET No Shared secret for sidecar authentication (min 16 chars) —
PERPLEXITY_COOKIES No Perplexity Pro session cookies —

Webhook / Deploy (optional, for CI/CD)

Variable Required Description Default
WEBHOOK_HOST No Webhook server URL for deploy triggers http://localhost:9000
DEPLOY_SECRET No Secret for deploy webhook authentication —

CLIProxyAPIPlus Configuration

CLIProxyAPIPlus configuration lives in infrastructure/config/config.yaml. The dashboard provides a structured UI for editing it, but you can also edit the file directly:

api-keys:
  - "sk-your-api-key-here"

providers:
  - name: "claude"
    type: "claude"
    # Provider-specific configuration...
  
  - name: "gemini"
    type: "gemini"
    api-key: "YOUR_GEMINI_API_KEY"
    # Provider-specific configuration...

Dashboard Settings

Dashboard-specific settings are managed through the Settings page in the UI:

  • User management (admin password)
  • Config Sync token management
  • Theme preferences

Config Sync

The dashboard can automatically sync your OpenCode configurations to your local machine using the companion plugin.

How It Works

  1. Generate a Sync Token: Navigate to Settings -> Config Sync in the dashboard
  2. Install the Plugin: Add opencode-cliproxyapi-sync to your OpenCode plugins
  3. Configure: Create ~/.config/opencode-cliproxyapi-sync/config.json with your dashboard URL and sync token
  4. Auto-Sync: On every OpenCode startup, the plugin checks for config changes and updates your local opencode.json and oh-my-openagent.json

Plugin Installation

npx opencode install opencode-cliproxyapi-sync

Or add manually to your opencode.json:

{
  "plugin": [
    "opencode-cliproxyapi-sync",
    "oh-my-openagent@latest"
  ]
}

The plugin supports OCX profiles — each profile can have its own sync config.

For full plugin documentation, see opencode-cliproxyapi-sync.

Usage Collection

The dashboard automatically collects usage statistics from CLIProxyAPIPlus every 5 minutes using a dedicated cron service.

How It Works

  1. Usage Collector Service: Runs as a Docker container with cron job
  2. Collection Endpoint: POST /api/usage/collect fetches data from CLIProxyAPI
  3. Data Storage: Usage records stored in PostgreSQL with deduplication
  4. Dashboard Display: View statistics on the Usage page

Required Configuration

  • COLLECTOR_API_KEY: Authentication key for the cron service (automatically generated during installation)

Troubleshooting

If usage data isn't appearing in your dashboard:

  1. Check collector service: docker compose ps usage-collector
  2. Verify API key: grep COLLECTOR_API_KEY infrastructure/.env
  3. View logs: docker compose logs usage-collector
  4. Manual trigger: Click "Refresh" on Usage page (admin only)

For detailed troubleshooting and advanced configuration, see infrastructure/docs/USAGE_COLLECTION.md.

Scheduled Backups

The dashboard can create scheduled database backups via a dedicated cron service that mirrors the usage collector. Configure the schedule under Settings → Backup.

How It Works

  1. Backup Scheduler Service: backup-scheduler container ticks every 5 minutes
  2. Scheduled Endpoint: POST /api/admin/backup/scheduled is idempotent — it only creates a backup when the configured cron time has elapsed
  3. Retention: Old SCHEDULED backups are removed according to the retention setting (days)
  4. Time Zone: The cron expression is evaluated using the container's TZ (falls back to UTC on invalid TZ)

Required Configuration

  • BACKUP_SCHEDULER_KEY: Bearer token for the scheduler service (auto-generated during installation)
  • At least one admin user must exist; backups are attributed to the oldest admin

Upgrading Existing Deployments

Installs that predate the scheduler need the new key and service added manually:

# Add the key if missing
grep -q '^BACKUP_SCHEDULER_KEY=' infrastructure/.env || \
  echo "BACKUP_SCHEDULER_KEY=$(openssl rand -hex 32)" >> infrastructure/.env

# Start the new container
cd infrastructure && docker compose up -d backup-scheduler

Troubleshooting

  1. Scheduler running? docker compose ps backup-scheduler
  2. Key present? grep BACKUP_SCHEDULER_KEY infrastructure/.env
  3. Logs: docker compose logs backup-scheduler and dashboard logs for BACKUP_SCHEDULED_TICK
  4. Schedule enabled? Settings → Backup — verify "Enabled" and the next run timestamp

Config Sharing

Share your configuration with others:

  • Publish: Generate a unique share code (format: XXXX-XXXX) for your config
  • Subscribe: Enter a share code to sync with a publisher's model selection
  • Automatic Sync: Subscribers see publisher's models on page reload
  • Subscriber Isolation: Subscribers keep their own MCP servers and plugins
  • Mutual Exclusivity: Users can be either publisher OR subscriber, not both