Docker Compose is the recommended deployment method for most users. It provides a simple, reliable way to deploy a Speckle server with minimal configuration and maximum flexibility.

​
Overview

Docker Compose deployment includes:

  • Complete server stack: API, frontend, viewer, and database
  • Easy configuration: Single docker-compose.yml file
  • Production ready: Includes SSL, monitoring, and backup capabilities
  • Scalable: Can be extended for larger deployments

​
Prerequisites

Before deploying, ensure you have:

  • Docker & Docker Compose installed on your server
  • Domain name pointing to your server
  • SSL certificate (Let’s Encrypt recommended)
  • Minimum 4GB RAM and 20GB storage
  • Port 80 and 443 available

​
Quick Start

  1. Clone the repository:
git clone https://github.com/specklesystems/speckle-server.git
cd speckle-server
  1. Configure environment:
cp .env.example .env
# Edit .env with your configuration
  1. Start the server:
docker-compose up -d

Your server will be available at https://your-domain.com

​
Configuration

​
Environment Variables

Key configuration options in your .env file:

# Server Configuration
SPECKLE_SERVER_NAME=My Speckle Server
SPECKLE_SERVER_DESCRIPTION=My organization's Speckle server
SPECKLE_SERVER_URL=https://your-domain.com

# Database
POSTGRES_DB=speckle
POSTGRES_USER=speckle
POSTGRES_PASSWORD=your-secure-password

# Email (for notifications)
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-password

# SSL Configuration
SSL_CERT_PATH=/etc/letsencrypt/live/your-domain.com/fullchain.pem
SSL_KEY_PATH=/etc/letsencrypt/live/your-domain.com/privkey.pem

​
SSL Certificate Setup

For production deployments, SSL certificates are essential:

  1. Install Certbot:
sudo apt-get update
sudo apt-get install certbot
  1. Obtain certificate:
sudo certbot certonly --standalone -d your-domain.com
  1. Update docker-compose.yml to mount certificate paths

​
Production Deployment

version: '3.8'
services:
  speckle-server:
    image: speckle/speckle-server:latest
    restart: unless-stopped
    environment:
      - NODE_ENV=production
    volumes:
      - ./data:/app/data
      - /etc/letsencrypt:/etc/letsencrypt:ro
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:13
    restart: unless-stopped
    environment:
      POSTGRES_DB: speckle
      POSTGRES_USER: speckle
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:6-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

​
Monitoring & Logs

Monitor your deployment:

# View logs
docker-compose logs -f

# Check service status
docker-compose ps

# Monitor resource usage
docker stats

​
Backup Strategy

Set up automated backups:

# Database backup
docker-compose exec postgres pg_dump -U speckle speckle > backup.sql

# Data directory backup
tar -czf speckle-data-backup.tar.gz ./data

​
Troubleshooting

​
Common Issues

Server won’t start:

  • Check Docker and Docker Compose versions
  • Verify all environment variables are set
  • Check port availability

SSL certificate issues:

  • Ensure domain points to your server
  • Verify certificate paths in docker-compose.yml
  • Check certificate expiration

Database connection errors:

  • Verify PostgreSQL credentials
  • Check database container status
  • Ensure proper volume mounting

​
Getting Help

​
Next Steps

After successful deployment:

  1. Configure connectors to use your server
  2. Set up monitoring and alerting
  3. Create backup schedules
  4. Configure user management
  5. Test all functionality

Development vs Production: This guide focuses on production deployment. For development and testing, see the Local Development guide.