Codakey
Play
← Back to get-convex/convex-backend

How to Deploy & Use get-convex/convex-backend

Convex Backend Deployment and Usage Guide

1. Prerequisites

Required Software

  • Rust toolchain (latest stable version) - for building from source
  • Docker (recommended for self-hosting) - version 20.10+
  • Node.js 18+ and npm - for TypeScript packages and CLI
  • Git - for cloning the repository

Database Requirements

Convex supports multiple storage backends:

  • PostgreSQL (via Neon, RDS, or self-managed)
  • SQLite (for simpler deployments)
  • Compatible with: Neon, Fly.io, Vercel, Netlify, RDS

Platform Requirements

  • Linux (primary platform, battle-tested)
  • macOS (well-supported)
  • Windows (less experience, may encounter issues)
  • Minimum 2GB RAM, 2 CPU cores recommended

2. Installation

Option A: Docker (Recommended)

# Pull the latest Convex image
docker pull convex/convex-backend:latest

# Or build from source using Docker
git clone https://github.com/get-convex/convex-backend.git
cd convex-backend
docker build -t convex-backend .

Option B: Prebuilt Binary

Download the latest release from GitHub Releases:

# Check releases page for latest version
curl -L -o convex-backend.tar.gz https://github.com/get-convex/convex-backend/releases/latest/download/convex-backend-x86_64-unknown-linux-gnu.tar.gz
tar -xzf convex-backend.tar.gz
sudo mv convex-backend /usr/local/bin/

Option C: Build from Source

# Clone repository
git clone https://github.com/get-convex/convex-backend.git
cd convex-backend

# Install Rust if not present
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Build the backend
cargo build --release

# The binary will be at: target/release/convex-backend

3. Configuration

Environment Variables

Create a .env file or set these environment variables:

# Required: Instance secret (CHANGE FROM DEFAULT!)
INSTANCE_SECRET=your-secure-random-string-here

# Required: Admin key (CHANGE FROM DEFAULT!)
ADMIN_KEY=your-admin-key-here

# Database configuration (choose one)
# For PostgreSQL:
DATABASE_URL=postgresql://user:password@localhost:5432/convex

# For SQLite:
DATABASE_URL=sqlite:///path/to/convex.db

# Optional: Disable anonymous beacon
DISABLE_BEACON=true

# Optional: Customize ports
PORT=8080
INTERNAL_PORT=8081

Configuration Files

Create config.toml for advanced configuration:

[server]
port = 8080
host = "0.0.0.0"

[database]
# PostgreSQL configuration
url = "postgresql://user:password@localhost:5432/convex"
pool_size = 10

# OR SQLite configuration
# url = "sqlite:///var/lib/convex/convex.db"

[storage]
# For vector index storage (from source files)
vector_index_soft_limit = 1073741824  # 1GB
multi_segment_full_scan_threshold_kb = 10240  # 10MB

[subscriptions]
# Subscription management (from subscription.rs)
num_managers = 4
worker_queue_size = 1000
invalidation_delay_threshold_ms = 100

API Keys and Secrets

  1. Instance Secret: Generate a secure random string (min 32 characters)
  2. Admin Key: Generate another secure key for administrative access
  3. Database Credentials: Ensure your database user has appropriate permissions

4. Build & Run

Development Mode

# Clone and setup
git clone https://github.com/get-convex/convex-backend.git
cd convex-backend

# Install dependencies
npm install  # For TypeScript packages in npm-packages/

# Build in debug mode (faster iteration)
cargo build

# Run with development configuration
cargo run -- --config dev-config.toml

# Or using Docker Compose for full stack
docker-compose -f docker-compose.dev.yml up

Production Build

# Build optimized release
cargo build --release --features "production"

# Run production binary
./target/release/convex-backend \
  --instance-secret $(cat /run/secrets/instance_secret) \
  --admin-key $(cat /run/secrets/admin_key) \
  --database-url $DATABASE_URL \
  --disable-beacon  # Optional: disable anonymous usage reporting

Running with Docker

# Simple run
docker run -d \
  -p 8080:8080 \
  -e INSTANCE_SECRET=your-secret \
  -e ADMIN_KEY=your-admin-key \
  -e DATABASE_URL=postgresql://user:password@db:5432/convex \
  convex/convex-backend:latest

# With Docker Compose
docker-compose up -d

Example docker-compose.yml:

version: '3.8'
services:
  convex:
    image: convex/convex-backend:latest
    ports:
      - "8080:8080"
    environment:
      - INSTANCE_SECRET=${INSTANCE_SECRET}
      - ADMIN_KEY=${ADMIN_KEY}
      - DATABASE_URL=postgresql://postgres:password@db:5432/convex
    depends_on:
      - db
    volumes:
      - convex_data:/var/lib/convex
  
  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=convex
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  convex_data:
  postgres_data:

5. Deployment

Platform Recommendations

Fly.io (Recommended for simplicity)

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Launch Convex
fly launch --image convex/convex-backend:latest
fly secrets set INSTANCE_SECRET=your-secret ADMIN_KEY=your-admin-key
fly volumes create convex_data --size 10
fly deploy

Vercel/Netlify with External Database

  1. Deploy Convex backend to a cloud provider (AWS, GCP, Azure)
  2. Use Neon (PostgreSQL) or RDS for database
  3. Connect your frontend via Convex client libraries

Kubernetes

# convex-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: convex-backend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: convex
  template:
    metadata:
      labels:
        app: convex
    spec:
      containers:
      - name: convex
        image: convex/convex-backend:latest
        ports:
        - containerPort: 8080
        env:
        - name: INSTANCE_SECRET
          valueFrom:
            secretKeyRef:
              name: convex-secrets
              key: instance-secret
        - name: ADMIN_KEY
          valueFrom:
            secretKeyRef:
              name: convex-secrets
              key: admin-key
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: convex-secrets
              key: database-url

Traditional VPS (DigitalOcean, AWS EC2, Linode)

# Setup systemd service
sudo tee /etc/systemd/system/convex.service << EOF
[Unit]
Description=Convex Backend
After=network.target postgresql.service

[Service]
Type=simple
User=convex
WorkingDirectory=/opt/convex
Environment=INSTANCE_SECRET=your-secret
Environment=ADMIN_KEY=your-admin-key
Environment=DATABASE_URL=postgresql://convex:password@localhost:5432/convex
ExecStart=/usr/local/bin/convex-backend
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable convex
sudo systemctl start convex

Database Setup

-- PostgreSQL setup
CREATE DATABASE convex;
CREATE USER convex WITH ENCRYPTED PASSWORD 'secure-password';
GRANT ALL PRIVILEGES ON DATABASE convex TO convex;

-- SQLite setup (automatic, ensure directory is writable)
mkdir -p /var/lib/convex
chown convex:convex /var/lib/convex

Scaling Considerations

  • Vector Indexes: Monitor VECTOR_INDEX_SIZE_SOFT_LIMIT from source files
  • Subscriptions: Adjust NUM_SUBSCRIPTION_MANAGERS based on concurrent users
  • Memory: Increase DOCUMENTS_IN_MEMORY knob for better caching
  • Storage: Use SSD for better vector index performance

6. Troubleshooting

Common Issues

Database Connection Issues

# Test database connection
psql $DATABASE_URL -c "SELECT 1"

# Check if Convex can create tables
CONNECTION_TIMEOUT=30s convex-backend --check-db

Permission Errors

# Ensure proper permissions for SQLite
sudo chown -R convex:convex /var/lib/convex
sudo chmod 755 /var/lib/convex

Port Already in Use

# Check what's using port 8080
sudo lsof -i :8080

# Or change Convex port
export PORT=8081
./convex-backend

Memory Issues with Vector Indexes

If experiencing OOM errors with vector search:

  1. Reduce VECTOR_INDEX_SIZE_SOFT_LIMIT in configuration
  2. Increase system memory
  3. Monitor crates/database/src/vector_index_worker/flusher.rs metrics

Subscription Performance Problems

From crates/database/src/subscription.rs:

  • Increase SUBSCRIPTIONS_WORKER_QUEUE_SIZE if seeing queue full errors
  • Adjust SUBSCRIPTION_INVALIDATION_DELAY_THRESHOLD for notification timing
  • Monitor subscription manager count with NUM_SUBSCRIPTION_MANAGERS

Build Failures on Windows

# Install Windows build tools
rustup default stable-x86_64-pc-windows-msvc
cargo install cargo-make  # For build scripts

# Or use WSL2 for Linux-like environment

Anonymous Beacon Concerns

The beacon sends minimal anonymous data:

  • Random deployment identifier
  • Database migration version
  • Git revision
  • Backend uptime

To disable:

./convex-backend --disable-beacon
# Or set environment variable
export DISABLE_BEACON=true

Logging and Monitoring

# View logs
docker logs convex-backend
journalctl -u convex.service -f

# Health check endpoint
curl http://localhost:8080/health

# Metrics endpoint (if enabled)
curl http://localhost:8080/metrics

Getting Help

  1. Check logs for specific error messages
  2. Consult #self-hosted channel on Discord
  3. Review source files for configuration knobs:
    • crates/database/src/vector_index_worker/flusher.rs - vector index settings
    • crates/database/src/subscription.rs - subscription management
    • crates/database/src/table_iteration.rs - query performance
  4. File issues on GitHub

Performance Tuning

# In config.toml
[performance]
# From table_iteration.rs
documents_in_memory = 10000
table_iterator_max_retries = 3

# From subscription.rs
subscription_invalidation_delay_multiplier = 2.0
subscription_advance_log_tracing_threshold = 1000

# From vector index configuration
multi_segment_full_scan_threshold_kb = 5120  # 5MB default
← Project overviewView alternatives to get-convex/convex-backend →