Installation Guide

July 1, 2026 · View on GitHub

← Back to README

Prerequisites

Before installing, ensure you have:

Local use (macOS/Windows/Linux): Only Docker Desktop is required. See Local Setup.

For server deployment:

  • Operating System: Ubuntu 20.04+ or Debian 11+ (Ubuntu/Debian derivatives like Zorin OS, Linux Mint, Pop!_OS, elementary, Raspbian, and LMDE are auto-detected via ID_LIKE)
  • Root Access: Required for Docker installation and optional firewall configuration
  • Domain Name: A registered domain with DNS control
  • Server: VPS or dedicated server with public IP address
  • Ports Available: Depends on the selected mode. Integrated Caddy needs 80/tcp, 443/tcp, and 443/udp; OAuth callbacks add 8085, 1455, 54545, 51121, and 11451/tcp. Dashboard-only and external proxy mode should be exposed through your existing reverse proxy.

Preflight Checklist

Complete before running the installer:

  • DNS Records Configured: Set A records for dashboard.yourdomain.com and api.yourdomain.com pointing to your server IP
  • DNS Propagated: Verify records with dig dashboard.yourdomain.com (allow 5-15 minutes)
  • Ports Available: Confirm no services are already using ports 80 and 443 for integrated Caddy mode; OAuth callback ports 8085, 1455, 54545, 51121, and 11451 are only required if OAuth callbacks are enabled
  • Firewall Plan: If you want the installer to manage UFW, know your SSH port and any existing service ports that must stay reachable
  • Root Access: SSH access with sudo or root privileges
  • First Admin Window: Plan to create your admin account immediately after installation completes

DNS Configuration

Configure DNS A records for your domain before installation:

dashboard.example.com  →  YOUR_SERVER_IP
api.example.com        →  YOUR_SERVER_IP

DNS Configuration

Replace example.com with your actual domain and YOUR_SERVER_IP with your server's public IP address.

Critical: DNS records must be live before first start. Caddy requests Let's Encrypt certificates immediately, which requires valid DNS.

Security Note: Until you create the first admin account, the dashboard setup page is accessible to anyone who can reach your domain. Restrict access using firewall rules if needed, or complete setup immediately after installation.

Quick Start (Docker Compose)

The fastest way to get started is using the automated installer:

git clone https://github.com/itsmylife44/cliproxyapi-dashboard.git
cd cliproxyapi-dashboard
sudo ./install.sh

Quick Start

The installer will:

  1. Prompt for domain and subdomain configuration
  2. Install Docker and Docker Compose (if not already installed)
  3. Optionally configure UFW firewall rules with explicit confirmation
  4. Generate secure secrets (JWT_SECRET, MANAGEMENT_API_KEY, POSTGRES_PASSWORD, COLLECTOR_API_KEY, BACKUP_SCHEDULER_KEY)
  5. Pull the pre-built dashboard image from GHCR
  6. Create infrastructure/.env with all required configuration
  7. Create a systemd service for automatic startup on boot
  8. Set up automated usage collection service (cron-based)
  9. Optionally set up automated daily or weekly backups

Post-Installation

After installation completes:

sudo systemctl start cliproxyapi-stack
sudo systemctl status cliproxyapi-stack
cd infrastructure
docker compose logs -f

Verify all services are running:

# Check all containers are healthy
docker compose ps

# Should show 6 services: postgres, cliproxyapi, dashboard, caddy, docker-proxy, usage-collector
# All should show "Up" status and "healthy" where applicable

Access the dashboard at:

  • Dashboard: https://dashboard.yourdomain.com
  • API: https://api.yourdomain.com

Verify Usage Collection

After setup, verify that usage tracking is working:

# Check usage collector service
docker compose ps usage-collector

# View collector logs (should show cron entries every 5 minutes)
docker compose logs usage-collector

The usage collector runs automatically and will begin tracking API requests to display in the Dashboard's Usage page.

Dashboard-Only Install

Use dashboard-only mode when you already have CLIProxyAPI installed and want this project to provide only the web UI and its dashboard database.

git clone https://github.com/itsmylife44/cliproxyapi-dashboard.git
cd cliproxyapi-dashboard
sudo ./install.sh --dashboard-only

This mode installs:

  • Dashboard
  • PostgreSQL for dashboard data
  • Usage collector and backup scheduler helper containers

It does not install:

  • CLIProxyAPI
  • Caddy
  • Docker socket proxy
  • Perplexity sidecar

During installation you will be prompted for:

  • Existing CLIProxyAPI management URL, for example https://proxy.example.com/v0/management for a remote server or http://host.docker.internal:8317/v0/management for same-host non-Docker installs
  • Existing CLIProxyAPI public API URL, for example https://api.example.com
  • Existing CLIProxyAPI management API key, matching the proxy's management password/key

The dashboard is exposed on 127.0.0.1:3000, so put your existing reverse proxy in front of it. The management URL must be reachable from inside the dashboard container. If your existing CLIProxyAPI runs directly on the same host and publishes port 8317, host.docker.internal is available inside the dashboard container.

Having only the public OpenAI-compatible API URL is not enough for dashboard management features. The dashboard also needs the CLIProxyAPI management endpoint (/v0/management) and its management key.

After installation:

sudo systemctl start cliproxyapi-stack
cd infrastructure
docker compose -f docker-compose.dashboard-only.yml logs -f

Some stack-management features, such as restarting or updating the CLIProxyAPI container from the dashboard, are not available in dashboard-only mode unless you separately provide compatible Docker access and container naming.

Initial Setup Flow

  1. First Visit: Navigate to https://dashboard.yourdomain.com
  2. Automatic Redirect: You'll be redirected to /setup (the setup wizard)
  3. Create Admin Account: Enter your desired username and password
  4. Setup Disabled: After creating the first user, the setup page becomes inaccessible
  5. Login: Use your new credentials to access the dashboard

Important Notes:

  • There are no default credentials
  • The setup page is publicly accessible until the first admin account is created
  • After first user creation, setup is permanently disabled
  • Use the Configuration page to set up API keys and AI providers — no manual file editing required

Local Setup (macOS / Windows / Linux)

Run the full stack locally using Docker Desktop — no server, domain, or TLS required.

Prerequisites

macOS / Linux

git clone https://github.com/itsmylife44/cliproxyapi-dashboard.git
cd cliproxyapi-dashboard
./setup-local.sh
./setup-local.sh --down    # Stop
./setup-local.sh --reset   # Reset (removes all data)

Local Setup macOS

Windows (PowerShell)

git clone https://github.com/itsmylife44/cliproxyapi-dashboard.git
cd cliproxyapi-dashboard
.\setup-local.ps1
.\setup-local.ps1 -Down    # Stop
.\setup-local.ps1 -Reset   # Reset (removes all data)

Local Setup Windows

Dashboard runs on localhost:3000, CLIProxyAPI proxy on localhost:11451.

Note: Local setup builds the dashboard from your checked-out source (build: ./dashboard). If you pull updates, rerun setup (or run docker compose -f docker-compose.local.yml up -d --build) to ensure the latest local changes are baked into the container.

Manual Installation

If you prefer manual setup or need customization:

1. Install Docker

Ubuntu:

# Update packages
sudo apt-get update

# Install prerequisites
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Add Docker GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Enable and start Docker
sudo systemctl enable docker
sudo systemctl start docker

Debian:

# Update packages
sudo apt-get update

# Install prerequisites
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Add Docker GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository (note: debian instead of ubuntu)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Enable and start Docker
sudo systemctl enable docker
sudo systemctl start docker

Note: The automated installer (install.sh) detects your OS via /etc/os-release and uses the correct repository path automatically.

2. Configure Firewall (Optional)

Skip this section if your firewall is managed elsewhere. On existing servers, do not enable UFW until you have listed every inbound service port that must remain reachable. If your SSH service does not use port 22, replace 22 below with your actual SSH port before enabling UFW.

sudo apt-get install -y ufw

# Allow SSH first. Change 22 if your server uses a different SSH port.
SSH_PORT=22
sudo ufw limit "${SSH_PORT}/tcp"

# Keep any existing services reachable before enabling UFW
# Examples:
# sudo ufw allow 25/tcp   # SMTP
# sudo ufw allow 587/tcp  # Submission
# sudo ufw allow 8443/tcp # Existing app

# Allow HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp  # HTTP/3

# Allow OAuth callback ports
sudo ufw allow 8085/tcp
sudo ufw allow 1455/tcp
sudo ufw allow 54545/tcp
sudo ufw allow 51121/tcp
sudo ufw allow 11451/tcp

# Enable firewall
sudo ufw enable

3. Generate Secrets

# Generate secure secrets
JWT_SECRET=$(openssl rand -base64 32)
MANAGEMENT_API_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -hex 32)
COLLECTOR_API_KEY=$(openssl rand -hex 32)
BACKUP_SCHEDULER_KEY=$(openssl rand -hex 32)

# Display secrets (save these values)
echo "JWT_SECRET=$JWT_SECRET"
echo "MANAGEMENT_API_KEY=$MANAGEMENT_API_KEY"
echo "POSTGRES_PASSWORD=$POSTGRES_PASSWORD"
echo "COLLECTOR_API_KEY=$COLLECTOR_API_KEY"
echo "BACKUP_SCHEDULER_KEY=$BACKUP_SCHEDULER_KEY"

4. Create Environment File

cat > infrastructure/.env << EOF
DOMAIN=example.com
DASHBOARD_SUBDOMAIN=dashboard
API_SUBDOMAIN=api
DATABASE_URL=postgresql://cliproxyapi:${POSTGRES_PASSWORD}@postgres:5432/cliproxyapi
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
JWT_SECRET=${JWT_SECRET}
MANAGEMENT_API_KEY=${MANAGEMENT_API_KEY}
COLLECTOR_API_KEY=${COLLECTOR_API_KEY}
BACKUP_SCHEDULER_KEY=${BACKUP_SCHEDULER_KEY}
CLIPROXYAPI_MANAGEMENT_URL=http://cliproxyapi:8317/v0/management
INSTALL_DIR=$(pwd)
TZ=UTC
DASHBOARD_URL=https://dashboard.example.com
API_URL=https://api.example.com
EOF

# Secure the environment file
chmod 600 infrastructure/.env

Environment Setup

Replace example.com with your actual domain.

Critical: The infrastructure/.env file is generated by install.sh and must contain all variables shown above. An empty or missing .env file will cause the stack to fail on startup. Do not commit this file to version control.

5. Configure CLIProxyAPI

API keys and AI providers can be configured through the Dashboard UI after first login. Alternatively, you can edit infrastructure/config/config.yaml directly.

6. Create Systemd Service

sudo tee /etc/systemd/system/cliproxyapi-stack.service > /dev/null << 'EOF'
[Unit]
Description=CLIProxyAPI Stack (Docker Compose)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=true
WorkingDirectory=/opt/cliproxyapi/infrastructure
ExecStart=/usr/bin/docker compose up -d --wait
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=300
TimeoutStopSec=120
Restart=on-failure
RestartSec=10s
User=root
Group=root

[Install]
WantedBy=multi-user.target
EOF

# Update WorkingDirectory to match your installation path
sudo sed -i 's|/opt/cliproxyapi|'$(pwd)'|g' \
  /etc/systemd/system/cliproxyapi-stack.service

# Reload systemd and enable service
sudo systemctl daemon-reload
sudo systemctl enable cliproxyapi-stack

7. Start the Stack

sudo systemctl start cliproxyapi-stack

Or manually:

cd infrastructure
docker compose up -d --wait