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

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)

Service Components

Colanode Server

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

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

Image: minio/minio:RELEASE.2025-04-08T15-41-24Z
Ports: 9000 (API), 9001 (Console)
Purpose: S3-compatible file storage
Storage: Persistent volume minio_data

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

Example Nginx configuration:

# nginx.conf
server {
    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://web:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/ {
        proxy_pass http://server:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

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

Documentation