> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](./quickstart-python).
## Overview
The Docker service is ideal for teams looking to self-host CyborgDB in cloud, on-prem, or containerized environments.
To use CyborgDB, you need an API key. You can get one from the [CyborgDB Admin Dashboard](https://cyborgdb.co/).
For quick evaluation, you can generate a temporary demo key using any of the SDKs:
```python Python theme={null}
import cyborgdb
print(cyborgdb.get_demo_api_key())
```
```javascript JavaScript theme={null}
import { getDemoApiKey } from 'cyborgdb';
console.log(await getDemoApiKey());
```
```go Go theme={null}
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.
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](../../../intro/backing-stores).
**Standalone is for evaluation and testing only** - For production use, configure an external PostgreSQL, Redis, or S3 backend.
The CyborgDB service is available as a Docker image. You can pull it from Docker Hub:
```bash theme={null}
docker pull cyborginc/cyborgdb-service:latest
```
This image contains everything you need to run the CyborgDB service, including all dependencies and configurations.
```bash Linux theme={null}
# 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
```
```bash macOS theme={null}
# 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.
```bash Linux theme={null}
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
```
```bash macOS theme={null}
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
```
```bash Linux theme={null}
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
```
```bash macOS theme={null}
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
```
```bash Linux theme={null}
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
```
```bash macOS theme={null}
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
For a complete setup with database included, use Docker Compose:
Create a `docker-compose.yml` file:
```yaml theme={null}
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:
```bash theme={null}
docker-compose up -d
```
Create a `docker-compose.yml` file:
```yaml theme={null}
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:
```bash theme={null}
docker-compose up -d
```
Create a `docker-compose.yml` file:
```yaml theme={null}
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:
```bash theme={null}
docker-compose up -d
```
Create a `docker-compose.yml` file:
```yaml theme={null}
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:
```bash theme={null}
docker-compose up -d
```
For local development with MinIO, see the [MinIO quickstart](https://min.io/docs/minio/container/index.html) to spin up a local S3-compatible store, then use `&endpoint=http://minio:9000` in the connection string.
Once the service is running, verify it's working correctly:
**Health Check:**
```bash theme={null}
curl http://localhost:8000/v1/health
```
**API Documentation:**
Navigate to [http://localhost:8000/v1/docs](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.
For production deployments, consider these additional configurations:
| 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](../advanced/env-vars).
For production deployments, configure HTTPS by providing SSL certificates:
**Environment Variables:**
```bash theme={null}
SSL_CERT_PATH=/path/to/certificate.crt
SSL_KEY_PATH=/path/to/private.key
```
**Docker Run Example:**
```bash theme={null}
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:**
```yaml theme={null}
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.
Now that your CyborgDB service is running, you can interact with it using client SDKs:
**Install Client SDKs:**
```bash Python icon="python" theme={null}
pip install cyborgdb
```
```bash JavaScript icon="js" theme={null}
npm install cyborgdb
```
```bash TypeScript icon="code" theme={null}
npm install cyborgdb
```
```bash Go icon="golang" theme={null}
go get github.com/cyborginc/cyborgdb-go
```
Learn how to use the REST API for direct integration
Learn how to use the Python SDK for direct integration
Learn how to use the JavaScript/TypeScript SDK for direct integration
Learn how to use the Go SDK for direct integration
* **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
| 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.