Docker Deployment¶

The standard way to deploy TruSpace using Docker Compose.

Prerequisites¶

Docker 20.10+
Docker Compose 2.0+
Git
4 GB RAM minimum (8 GB recommended with AI)

Quick Installation¶

# Clone repository
git clone git@github.com:openkfw/TruSpace.git
cd TruSpace

# Start TruSpace
./start.sh

That's it! TruSpace will be available at http://localhost:3000.

Custom Configuration¶

Using Environment Variables¶

# Copy and edit environment file
cp .env.example .env
nano .env  # or your preferred editor

# Then start
./start.sh

Interactive Configuration¶

Use the configuration script for guided setup:

./scripts/configure-env.sh

This will prompt you for:

Domain configuration
Port settings
AI model selection
CORS origins

Docker Compose Files¶

TruSpace uses multiple compose files:

File	Purpose
`docker-compose.yml`	Core services (IPFS, backend)
`docker-compose-frontend.yml`	Frontend service
`docker-compose-ai.yml`	AI services (Ollama, Open Web UI)
`docker-compose.build.yml`	Local image building
`docker-compose.pull.yml`	Pre-built images

Starting Specific Services¶

All ServicesWithout AIOnly Infrastructure

./start.sh

./start.sh --no-ai

docker compose up ipfs0 cluster0 -d

Container Management¶

View Running Containers¶

docker ps

View Logs¶

# All containers
docker compose logs -f

# Specific container
docker compose logs -f backend
docker compose logs -f ipfs0

Restart Services¶

# Restart all
docker compose restart

# Restart specific service
docker compose restart backend

Stop Services¶

# Stop all (keep data)
docker compose down

# Stop and remove volumes (⚠️ deletes data)
docker compose down -v

Data Persistence¶

TruSpace stores data in Docker volumes:

Volume	Purpose
`truspace_ipfs_data`	IPFS datastore
`truspace_cluster_data`	IPFS Cluster config
`truspace_sqlite_data`	SQLite database
`truspace_ollama_data`	AI models

Backup Volumes¶

# Backup IPFS data
docker run --rm -v truspace_ipfs_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/ipfs-backup.tar.gz -C /data .

# Backup SQLite
docker run --rm -v truspace_sqlite_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/sqlite-backup.tar.gz -C /data .

Restore Volumes¶

# Restore IPFS data
docker run --rm -v truspace_ipfs_data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/ipfs-backup.tar.gz -C /data

Updating TruSpace¶

# Pull latest changes
git pull origin main

# Rebuild and restart
docker compose down
docker compose build --no-cache
./start.sh

Resource Limits¶

For constrained environments, you can limit container resources in a docker-compose.override.yml:

version: '3.8'
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M

  ipfs0:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G

  ollama:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 4G

Health Checks¶

Check service health:

# Backend health
curl http://localhost:8000/health

# IPFS health
curl http://localhost:5001/api/v0/id

# Frontend health
curl http://localhost:3000

Troubleshooting¶

Container Won't Start¶

# Check logs
docker compose logs <service-name>

# Check resource usage
docker stats

Network Issues¶

# Inspect network
docker network inspect truspace_default

# Recreate network
docker compose down
docker network prune
docker compose up -d

Permission Issues¶

# Fix volume permissions
sudo chown -R 1000:1000 ./data