Skip to main content
Deploy Syft Space using Docker for a production-ready containerized environment. This method provides isolation, easy updates, and simplified dependency management.

​
Prerequisites

  • Docker 20.10 or later
  • 4GB RAM minimum (8GB recommended)
  • Docker socket access for vector database provisioning

​
Quick start

Run Syft Space with a single Docker command: 
docker run -d \
    --name syft-space \
    --restart unless-stopped \
    -p 8080:8080 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /dev/null:/root/.docker/config.json \
    -v syft-space-data:/data \
    ghcr.io/openmined/syft-space:latest
Access the application at http://localhost:8080

​
Volume mounts

​
Docker socket

-v /var/run/docker.sock:/var/run/docker.sock
Required for automatic provisioning of vector database containers (ChromaDB).
Mounting the Docker socket gives the container access to your Docker daemon. Only use trusted images and ensure proper network isolation.

​
Data persistence

-v syft-space-data:/data
Stores:
  • SQLite database (/data/app.db)
  • Application logs (/data/logs/)
  • Uploaded documents and datasets

​
Home directory (optional)

-v ${HOME}:/root
Mount your home directory to persist configuration files and access local resources.

​
Environment variables

Configure Syft Space using environment variables:

​
Server configuration

-e SYFT_PORT=8080                    # Server port (default: 8080)
-e SYFT_DEBUG=false                  # Enable debug mode

​
Database configuration

-e SYFT_SQLITE_DB_PATH=/data/app.db  # SQLite database path
-e SYFT_RESET_DB=false               # Reset database on startup (CAUTION)
Setting SYFT_RESET_DB=true will destroy all data. Only use for development or testing.

​
Authentication

-e SYFT_ADMIN_API_KEY=your-secret-key  # Admin API key (empty = no auth)

​
External services

-e SYFT_DEFAULT_ACCOUNTING_URL=https://syftaccounting.centralus.cloudapp.azure.com/
-e SYFT_DEFAULT_MARKETPLACE_URL=https://syfthub.openmined.org
-e SYFT_PUBLIC_URL=https://your-domain.com  # For callbacks/webhooks

​
Multi-tenancy

-e SYFT_ENABLE_MULTI_TENANCY=false
-e SYFT_DEFAULT_TENANT_NAME=root

​
Docker Compose

For more complex deployments, use Docker Compose:

​
Basic setup

Create a docker-compose.yml file: 
services:
  syft-space-server:
    image: ghcr.io/openmined/syft-space:latest
    container_name: syft-space-server
    restart: unless-stopped
    stop_grace_period: 15s

    ports:
      - "${SYFT_PORT:-8080}:8080"

    volumes:
      - syft-space-data:/data
      - ${HOME}:/root
      - ${HOME}/.docker/run/docker.sock:/var/run/docker.sock

    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock
      - SYFT_PORT=8080
      - SYFT_SQLITE_DB_PATH=/data/app.db
      - SYFT_DEBUG=${SYFT_DEBUG:-false}
      - SYFT_RESET_DB=${SYFT_RESET_DB:-false}
      - SYFT_ENABLE_MULTI_TENANCY=${SYFT_ENABLE_MULTI_TENANCY:-false}
      - SYFT_DEFAULT_TENANT_NAME=${SYFT_DEFAULT_TENANT_NAME:-root}
      - SYFT_ADMIN_API_KEY=${SYFT_ADMIN_API_KEY:-}
      - SYFT_DEFAULT_ACCOUNTING_URL=${SYFT_DEFAULT_ACCOUNTING_URL:-https://syftaccounting.centralus.cloudapp.azure.com/}
      - SYFT_DEFAULT_MARKETPLACE_URL=${SYFT_DEFAULT_MARKETPLACE_URL:-https://syfthub.openmined.org}
      - SYFT_PUBLIC_URL=${SYFT_PUBLIC_URL:-}

    extra_hosts:
      - "host.docker.internal:host-gateway"

    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/api/v1/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 2G
        reservations:
          cpus: "0.5"
          memory: 512M

volumes:
  syft-space-data:
    driver: local

networks:
  default:
    name: syft-space-network

​
Environment file

Create a .env file for configuration: 
# Server
SYFT_PORT=8080
SYFT_DEBUG=false

# Database
SYFT_RESET_DB=false

# Authentication
SYFT_ADMIN_API_KEY=

# External services
SYFT_DEFAULT_ACCOUNTING_URL=https://syftaccounting.centralus.cloudapp.azure.com/
SYFT_DEFAULT_MARKETPLACE_URL=https://syfthub.openmined.org
SYFT_PUBLIC_URL=

​
Run with Docker Compose

docker compose up -d

​
Building from source

Build your own Docker image:

​
Build the frontend

cd frontend
bun install
bun run build
cd ..

​
Build the Docker image

docker build -t syft-space-server .

​
Run your custom image

docker run -d \
    --name syft-space \
    -p 8080:8080 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v syft-space-data:/data \
    syft-space-server:latest

​
Health checks

The container includes a built-in health check: 
# Check container health status
docker ps --filter name=syft-space

# View health check logs
docker inspect syft-space | jq '.[0].State.Health'
The health check pings /api/v1/health every 30 seconds with a 10-second timeout.

​
Resource limits

Adjust resource limits based on your workload: 
deploy:
  resources:
    limits:
      cpus: "4.0"      # Maximum CPU cores
      memory: 4G       # Maximum memory
    reservations:
      cpus: "1.0"      # Reserved CPU cores
      memory: 1G       # Reserved memory

​
Networking

​
Host networking

For direct network access without port mapping: 
docker run -d \
    --name syft-space \
    --network host \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v syft-space-data:/data \
    ghcr.io/openmined/syft-space:latest

​
Custom bridge network

Create an isolated network: 
docker network create syft-network

docker run -d \
    --name syft-space \
    --network syft-network \
    -p 8080:8080 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v syft-space-data:/data \
    ghcr.io/openmined/syft-space:latest

​
macOS Docker Desktop

For macOS users, the Docker socket location may differ: 
-v ${HOME}/.docker/run/docker.sock:/var/run/docker.sock
The Docker Compose configuration automatically handles this with the mounted home directory.

​
Troubleshooting

​
Container won’t start

# Check container logs
docker logs syft-space

# Check for port conflicts
lsof -i :8080

​
Docker socket permission denied

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect

​
Database issues

Reset the database (destroys all data): 
docker run -d \
    --name syft-space \
    -p 8080:8080 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v syft-space-data:/data \
    -e SYFT_RESET_DB=true \
    ghcr.io/openmined/syft-space:latest

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us