Docker Compose

Deploy Colanode quickly on your local machine or server using Docker Compose. This method is perfect for development, testing, small teams, or when you want to get started quickly without complex infrastructure.

Get the Docker Compose Configuration

# Option 1: Download directly
curl -o docker-compose.yaml https://raw.githubusercontent.com/colanode/colanode/main/hosting/docker/docker-compose.yaml

# Option 2: Clone the repository
git clone https://github.com/colanode/colanode.git
cd colanode/hosting/docker

Start the Services

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Check service status
docker compose ps

Storage Configuration

The default Docker Compose setup uses file system storage for simplicity. MinIO is available as an optional service for S3-compatible object storage. You can customize the storage backend by modifying environment variables.

Using the Default File System Storage

No changes needed - file system storage is pre-configured in the Docker Compose file with the server_storage volume.

Using MinIO S3 Storage

To enable MinIO, start the services with the S3 profile:

# Start with MinIO enabled
docker compose --profile s3 up -d

Then modify the colanode-server service environment variables in docker-compose.yaml:

services:
  server:
    environment:
      STORAGE_TYPE: "s3"
      STORAGE_S3_ENDPOINT: "http://minio:9000"
      STORAGE_S3_ACCESS_KEY: "minioadmin"
      STORAGE_S3_SECRET_KEY: "your_minio_password"
      STORAGE_S3_BUCKET: "colanode"
      STORAGE_S3_REGION: "us-east-1"
      STORAGE_S3_FORCE_PATH_STYLE: "true"

Using External S3 Storage

Modify the S3 environment variables in the server service:

services:
  server:
    environment:
      STORAGE_TYPE: "s3"
      STORAGE_S3_ENDPOINT: "https://s3.amazonaws.com"
      STORAGE_S3_ACCESS_KEY: "AKIA..."
      STORAGE_S3_SECRET_KEY: "..."
      STORAGE_S3_BUCKET: "my-colanode-bucket"
      STORAGE_S3_REGION: "us-west-2"
      STORAGE_S3_FORCE_PATH_STYLE: "false"

The MinIO service is already optional and won’t start unless you use the --profile s3 flag.

Using Google Cloud Storage

Mount your GCP service account key and configure GCS variables:

services:
  server:
    environment:
      STORAGE_TYPE: "gcs"
      STORAGE_GCS_BUCKET: "my-colanode-bucket"
      STORAGE_GCS_PROJECT_ID: "my-project-123"
      STORAGE_GCS_CREDENTIALS: "/secrets/gcp-key.json"
    volumes:
      - ./gcp-service-account.json:/secrets/gcp-key.json:ro

Using Azure Blob Storage

Configure Azure-specific environment variables:

services:
  server:
    environment:
      STORAGE_TYPE: "azure"
      STORAGE_AZURE_ACCOUNT: "mystorageaccount"
      STORAGE_AZURE_CONTAINER_NAME: "colanode"
      STORAGE_AZURE_ACCOUNT_KEY: "base64key=="

Access Colanode

Once all services are running:

• Colanode Web App: http://localhost:4000
• Colanode Server: http://localhost:3000
• MinIO Console: http://localhost:9001 (admin interface, only when using --profile s3)

Service Components

Colanode Server

• Image: ghcr.io/colanode/server:latest
• Port: 3000
• Purpose: Main server handling client requests
• Dependencies: PostgreSQL, Redis/Valkey, (MinIO optional)

Colanode Web App

• Image: ghcr.io/colanode/web:latest
• Port: 4000 (mapped to 80 internally)
• Purpose: Web client interface
• Access: Main entry point for users

Postgres with pgvector

• Image: pgvector/pgvector:pg17
• Port: 5432
• Purpose: Primary database with vector search capabilities
• Storage: Persistent volume postgres_data

Valkey Redis

• Image: valkey/valkey:8.1
• Port: 6379
• Purpose: Message queuing and caching
• Storage: Persistent volume valkey_data

MinIO S3 Storage (Optional)

• Image: minio/minio:RELEASE.2025-04-08T15-41-24Z
• Ports: 9000 (API), 9001 (Console)
• Purpose: S3-compatible file storage
• Storage: Persistent volume minio_data
• Profile: Only starts with --profile s3 flag

Configuration Customization

Environment Variables

The default configuration includes all necessary environment variables. For more details about environment variables read configuration docs. Key settings you might want to customize:

# In docker-compose.yaml under server.environment
SERVER_NAME: "Your Company Colanode"
SERVER_AVATAR: "https://company.com/logo.png"
ACCOUNT_VERIFICATION_TYPE: "manual" # or 'email' with SMTP
USER_STORAGE_LIMIT: "21474836480" # 20GB per user

Ports Configuration

Change exposed ports by modifying the ports section:

services:
  server:
    ports:
      - "8080:3000" # Change server port to 8080
  web:
    ports:
      - "8081:80" # Change web port to 8081

Volume Persistence

Data is stored in Docker volumes:

# List volumes
docker volume ls

# Backup a volume
docker run --rm -v colanode_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz -C /data .

# View volume details
docker volume inspect colanode_postgres_data

Using a Reverse Proxy

For production deployments, use a reverse proxy like Nginx or Traefik:

# docker-compose.prod.yaml
version: "3.8"
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/ssl/certs
    depends_on:
      - web
      - server
    networks:
      - colanode_network

  web:
    networks:
      - colanode_network

  server:
    environment:
      SERVER_PATH_PREFIX: "api"
    networks:
      - colanode_network

networks:
  colanode_network:
    external: false

Important: When exposing Colanode behind a path such as /api, the web client needs the server to report the same prefix. Set SERVER_PATH_PREFIX on the server container and make sure your reverse proxy forwards /api/* without stripping it. If the prefix is missing, the client falls back to the root path and the server will appear unavailable.

Example Nginx configuration:

# nginx.conf
events {}

http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }

    upstream colanode_web {
        server web:80;
    }

    upstream colanode_server {
        server server:3000;
    }

    server {
        listen 80;
        listen 443 ssl;
        server_name colanode.yourcompany.com;

        ssl_certificate /etc/ssl/certs/cert.pem;
        ssl_certificate_key /etc/ssl/certs/key.pem;

        location / {
            proxy_pass http://colanode_web;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }

        location /api/ {
            proxy_pass http://colanode_server;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

Starting and Stopping

# Start services
docker compose up -d

# Stop services
docker compose down

# Restart a specific service
docker compose restart server

# Pull latest images
docker compose pull

Monitoring and Logs

# View all logs
docker compose logs -f

# View specific service logs
docker compose logs -f server
docker compose logs -f postgres

# Monitor resource usage
docker stats

# Check service health
docker compose ps

Database Management

# Access PostgreSQL directly
docker compose exec postgres psql -U colanode_user -d colanode_db

# Create database backup
docker compose exec postgres pg_dump -U colanode_user colanode_db > backup.sql

# Restore from backup
docker compose exec -T postgres psql -U colanode_user colanode_db < backup.sql

Troubleshooting

Services Not Starting

# Check logs for errors
docker compose logs

# Verify all images are pulled
docker compose pull

# Check available disk space
df -h

# Check port conflicts
netstat -tlnp | grep :3000

Database Connection Issues

# Check PostgreSQL logs
docker compose logs postgres

# Verify database is ready
docker compose exec postgres pg_isready -U colanode_user

# Test connection manually
docker compose exec postgres psql -U colanode_user -d colanode_db -c "SELECT version();"

File Storage Issues

# Check MinIO logs
docker compose logs minio

# Access MinIO console
# Visit http://localhost:9001
# Login: minioadmin / your_minio_password

# Verify buckets exist
docker compose exec minio mc ls local/

Upgrading

# Pull latest images
docker compose pull

# Restart with new images
docker compose up -d

# Check logs for any migration messages
docker compose logs server

Version-Specific Updates

# Use specific version
# Edit docker-compose.yaml
server:
  image: ghcr.io/colanode/server:v0.3.0

web:
  image: ghcr.io/colanode/web:v0.3.0