Docker Service Quickstart

CyborgDB can be deployed as a standalone microservice using Docker. This allows you to run a fully self-contained encrypted vector search service on your own infrastructure with minimal setup. The service exposes a REST API for integration with any stack.

Looking to use the Python service? Check out our Python Quickstart Guide.

Overview

The Docker service is ideal for teams looking to self-host CyborgDB in cloud, on-prem, or containerized environments.

Get an API Key

To use CyborgDB, you need an API key. You can get one from the CyborgDB Admin Dashboard.For quick evaluation, you can generate a temporary demo key using any of the SDKs:

import cyborgdb
print(cyborgdb.get_demo_api_key())

import { getDemoApiKey } from 'cyborgdb';
console.log(await getDemoApiKey());

demoKey, _ := cyborgdb.GetDemoAPIKey("my demo app")
fmt.Println(demoKey)

Then use the printed key as your CYBORGDB_API_KEY when starting the service, and as the api_key when connecting with an SDK client.Make sure to keep your API key secure and do not share it publicly.

Choose Your Database Backend (Optional)

For quick evaluation and testing, you can skip database setup entirely - the service will automatically use a built-in standalone instance.For production deployments or if you have existing database infrastructure, CyborgDB service supports external database backends:

PostgreSQL: Compatible with your existing PostgreSQL infrastructure
- Managed services: AWS RDS, Azure Database for PostgreSQL, Google Cloud SQL, DigitalOcean Managed Databases
- Self-hosted PostgreSQL instances
Redis: Compatible with your existing Redis infrastructure
- Managed services: AWS ElastiCache, Azure Cache for Redis, Google Cloud Memorystore, Redis Cloud
- Self-hosted Redis instances
Amazon S3: Cloud-native object storage for scalable, serverless deployments
- Compatible with AWS S3, MinIO, Cloudflare R2, and any S3-compatible store

All backends provide identical CyborgDB functionality. For more info, refer to this guide.

Standalone is for evaluation and testing only - For production use, configure an external PostgreSQL, Redis, or S3 backend.

Pull the Docker Image

The CyborgDB service is available as a Docker image. You can pull it from Docker Hub:

docker pull cyborginc/cyborgdb-service:latest

This image contains everything you need to run the CyborgDB service, including all dependencies and configurations.

Run with Docker (Quick Start)

Quick Start (Standalone)
PostgreSQL Backend
Redis Backend
S3 Backend

# Minimal configuration - uses built-in standalone
sudo docker run -it --rm --network host \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -v cyborgdb_data:/app/cyborgdb_data \
  cyborginc/cyborgdb-service:latest

# Minimal configuration - uses built-in standalone
sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -v cyborgdb_data:/app/cyborgdb_data \
  cyborginc/cyborgdb-service:latest

Standalone is for evaluation and testing only. For production, use PostgreSQL, Redis, or S3.

sudo docker run -it --network host \
  -e CYBORGDB_DB_TYPE=postgres \
  -e "CYBORGDB_CONNECTION_STRING=host=localhost port=5432 dbname=postgres user=postgres password=your_password" \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=postgres \
  -e 'CYBORGDB_CONNECTION_STRING=host=host.docker.internal port=5432 dbname=postgres user=postgres password=your_password' \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest

sudo docker run -it --network host \
  -e CYBORGDB_DB_TYPE=redis \
  -e "CYBORGDB_CONNECTION_STRING=host:localhost,port:6379,db:0" \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=redis \
  -e 'CYBORGDB_CONNECTION_STRING=host:host.docker.internal,port:6379,db:0' \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  cyborginc/cyborgdb-service:latest

sudo docker run -it --network host \
  -e CYBORGDB_DB_TYPE=s3 \
  -e "CYBORGDB_CONNECTION_STRING=s3://my-bucket?region=us-east-1" \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e AWS_ACCESS_KEY_ID=AKID... \
  -e AWS_SECRET_ACCESS_KEY=... \
  cyborginc/cyborgdb-service:latest

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_DB_TYPE=s3 \
  -e "CYBORGDB_CONNECTION_STRING=s3://my-bucket?region=us-east-1" \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e AWS_ACCESS_KEY_ID=AKID... \
  -e AWS_SECRET_ACCESS_KEY=... \
  cyborginc/cyborgdb-service:latest

For MinIO, add &endpoint=http://...&access_key=...&secret_key=... to the connection string instead of using environment variables.

Platform Differences:

Linux uses --network host because Docker runs natively and can directly access the host network
macOS uses -p 8000:8000 and host.docker.internal because Docker runs in a VM and needs port mapping

Run with Docker Compose (Recommended)

For a complete setup with database included, use Docker Compose:

Quick Start (Standalone)
With PostgreSQL
With Redis
With S3

Create a docker-compose.yml file:

version: '3.8'
services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_API_KEY=${CYBORGDB_API_KEY}
    volumes:
      - cyborgdb_data:/app/cyborgdb_data
      - ./logs:/app/logs

volumes:
  cyborgdb_data:

Then run:

docker-compose up -d

Create a docker-compose.yml file:

version: '3.8'
services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_DB_TYPE: postgres
      - CYBORGDB_CONNECTION_STRING: host=postgres port=5432 dbname=cyborgdb user=cyborgdb password=secure_password
      - CYBORGDB_API_KEY: cyborg_your_api_key_here
    depends_on:
      - postgres
  
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB: cyborgdb
      - POSTGRES_USER: cyborgdb
      - POSTGRES_PASSWORD: secure_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

Then run:

docker-compose up -d

Create a docker-compose.yml file:

version: '3.8'
services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_DB_TYPE: redis
      - CYBORGDB_CONNECTION_STRING: host:redis,port:6379,db:0
      - CYBORGDB_API_KEY: cyborg_your_api_key_here
    depends_on:
      - redis
  
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  redis_data:

Then run:

docker-compose up -d

Create a docker-compose.yml file:

version: '3.8'
services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_DB_TYPE=s3
      - CYBORGDB_CONNECTION_STRING=s3://my-bucket?region=us-east-1
      - CYBORGDB_API_KEY=cyborg_your_api_key_here
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}

Then run:

docker-compose up -d

For local development with MinIO, see the MinIO quickstart to spin up a local S3-compatible store, then use &endpoint=http://minio:9000 in the connection string.

Verify Installation

Once the service is running, verify it’s working correctly:Health Check:

curl http://localhost:8000/v1/health

API Documentation: Navigate to http://localhost:8000/v1/docs to explore the interactive API documentation.You should see a response indicating the service is healthy and ready to accept requests.

Advanced Configuration

For production deployments, consider these additional configurations:

Environment Variables
HTTPS Configuration

Variable	Description	Required	Example
`CYBORGDB_API_KEY`	Your CyborgDB API key	✅	`cyborg_abc123...`
`CYBORGDB_DB_TYPE`	Database backend type	⚠️ Optional (defaults to standalone)	`standalone`, `postgres`, `redis`, `s3`, or `memory`
`CYBORGDB_CONNECTION_STRING`	Database connection details	⚠️ Optional (defaults to standalone)	See connection formats
`PORT`	Service port	❌	`8000`
`SSL_CERT_PATH`	Path to SSL certificate file	❌	`/etc/ssl/certs/server.crt`
`SSL_KEY_PATH`	Path to SSL private key file	❌	`/etc/ssl/private/server.key`

If CYBORGDB_DB_TYPE and CYBORGDB_CONNECTION_STRING are not set, the service uses a built-in standalone database for evaluation. For production, configure an external database. For more information, refer to this guide.

For production deployments, configure HTTPS by providing SSL certificates:Environment Variables:

SSL_CERT_PATH=/path/to/certificate.crt
SSL_KEY_PATH=/path/to/private.key

Docker Run Example:

sudo docker run -it -p 8000:8000 \
  -e CYBORGDB_API_KEY=cyborg_your_api_key_here \
  -e CYBORGDB_DB_TYPE=postgres \
  -e CYBORGDB_CONNECTION_STRING="host=host.docker.internal port=5432 dbname=postgres user=postgres password=your_password" \
  -e SSL_CERT_PATH=/certs/server.crt \
  -e SSL_KEY_PATH=/certs/server.key \
  -v /host/path/to/certs:/certs \
  cyborginc/cyborgdb-service:latest

Docker Compose with SSL:

version: '3.8'
services:
  cyborgdb:
    image: cyborginc/cyborgdb-service:latest
    ports:
      - "8000:8000"
    environment:
      - CYBORGDB_DB_TYPE=postgres
      - CYBORGDB_CONNECTION_STRING=host=postgres port=5432 dbname=cyborgdb user=cyborgdb password=secure_password
      - CYBORGDB_API_KEY=cyborg_your_api_key_here
      - SSL_CERT_PATH=/certs/server.crt
      - SSL_KEY_PATH=/certs/server.key
    volumes:
      - ./certs:/certs
    depends_on:
      - postgres

The server automatically switches to HTTPS when both certificate files are provided and exist. Without certificates, it starts in HTTP mode.

Next Steps

Now that your CyborgDB service is running, you can interact with it using client SDKs:Install Client SDKs:

pip install cyborgdb

npm install cyborgdb

npm install cyborgdb

go get github.com/cyborginc/cyborgdb-go

REST API Reference

Learn how to use the REST API for direct integration

Python SDK Reference

Learn how to use the Python SDK for direct integration

JS/TS SDK Reference

Learn how to use the JavaScript/TypeScript SDK for direct integration

Go SDK Reference

Learn how to use the Go SDK for direct integration

Technical Specifications

Base Image: python:3.11-slim
Python Version: 3.11
PyTorch: CPU-optimized for maximum compatibility
Docker Image Size: ~1.8GB
Platform: linux/amd64, linux/arm64
Default Port: 8000

Comparison with Python Service

Aspect	Python Service	Docker Service
Installation	`pip install`	`docker run`
Dependencies	Managed by pip/conda	Bundled in container
Resource Usage	Lower overhead	Higher overhead
Environment Isolation	Python virtualenv	Container isolation
Deployment Complexity	Simple Python deployment	Container orchestration
Configuration	Environment variables/files	Environment variables
Best For	Development, Python-heavy workflows	Production, cloud deployment

Both approaches provide identical CyborgDB functionality. Choose based on your deployment preferences and infrastructure requirements.

CyborgDB Service

Encrypted Indexes

Data Operations

Advanced

Docker Service Quickstart

Overview

REST API Reference

Python SDK Reference

JS/TS SDK Reference

Go SDK Reference

​Overview

REST API Reference

Python SDK Reference

JS/TS SDK Reference

Go SDK Reference

Overview