Raspberry Pi Setup¶

Deploy TruSpace on a Raspberry Pi for always-on, low-power edge deployments.

Supported Hardware¶

Model	RAM	Support	Notes
Pi 5	4GB+	Full	Recommended
Pi 4	4GB+	Full	Good performance
Pi 4	2GB	Limited	No AI features
Pi 3	Any	Not supported	Insufficient resources

AI Features on Raspberry Pi

AI features require significant resources. On Pi 4 (4GB), use lightweight models like tinyllama or disable AI entirely with --no-ai.

Prerequisites¶

Raspberry Pi ⅘ with 4GB+ RAM
32GB+ microSD card (64GB recommended)
Raspberry Pi OS (64-bit) or Ubuntu 22.04 ARM64
Ethernet or WiFi connection

Step 1: Prepare the Pi¶

Update System¶

sudo apt update && sudo apt upgrade -y

Install Docker¶

# Install Docker
curl -fsSL https://get.docker.com | sh

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

# Log out and back in, then verify
docker --version

Install Docker Compose¶

# Install compose plugin
sudo apt install docker-compose-plugin -y

# Verify
docker compose version

Step 2: Clone and Configure¶

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

# Create environment file
cp .env.example .env

Configure for Local Network¶

Edit .env to use your Pi's hostname:

# Find your Pi's IP
hostname -I

# Update .env with your domain
nano .env

.env

# Replace localhost with your Pi's hostname or IP
CORS_ORIGIN=http://raspberrypi.local:3000
OI_CORS_ALLOW_ORIGIN=http://raspberrypi.local:3000

Or use the helper script:

sed 's|http://localhost|http://raspberrypi.local|g' .env.example > .env

Step 3: Start TruSpace¶

With AI (4GB+ RAM)Without AI (Recommended for 4GB)

# Use a lightweight model
echo "OLLAMA_MODEL=tinyllama" >> .env
./start.sh

./start.sh --no-ai

First Start Takes Time

The first start will pull Docker images, which can take 10-30 minutes depending on your network speed.

Step 4: Access TruSpace¶

From another device on your network:

URL: http://raspberrypi.local:3000 or http://<pi-ip>:3000

Performance Optimization¶

Enable Swap¶

For better stability with limited RAM:

# Check current swap
free -h

# Increase swap to 2GB
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Set CONF_SWAPSIZE=2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Use External SSD¶

For better IPFS performance, use an external SSD:

# Mount SSD (example)
sudo mkdir /mnt/ssd
sudo mount /dev/sda1 /mnt/ssd

# Move Docker data directory
sudo systemctl stop docker
sudo mv /var/lib/docker /mnt/ssd/docker
sudo ln -s /mnt/ssd/docker /var/lib/docker
sudo systemctl start docker

Resource Limits¶

Create docker-compose.override.yml:

version: '3.8'
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 256M

  ipfs0:
    deploy:
      resources:
        limits:
          memory: 512M
    environment:
      - IPFS_PROFILE=lowpower

  frontend:
    deploy:
      resources:
        limits:
          memory: 256M

Auto-Start on Boot¶

Using Systemd¶

Create a systemd service:

sudo nano /etc/systemd/system/truspace.service

/etc/systemd/system/truspace.service

[Unit]
Description=TruSpace
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/pi/TruSpace
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
User=pi

[Install]
WantedBy=multi-user.target

Enable the service:

sudo systemctl enable truspace
sudo systemctl start truspace

Monitoring¶

Check Resource Usage¶

# Overall system
htop

# Docker containers
docker stats

Check Temperatures¶

# CPU temperature
vcgencmd measure_temp

Thermal Throttling

If temperatures exceed 80°C, consider adding a heatsink or fan. Throttling will impact performance.

Troubleshooting¶

Out of Memory¶

# Check memory usage
free -h

# Restart containers
docker compose down
docker compose up -d

SD Card Issues¶

# Check filesystem
sudo fsck /dev/mmcblk0p2

# Check for errors
dmesg | grep -i error

Network Discovery¶

If raspberrypi.local doesn't work:

# Install mDNS
sudo apt install avahi-daemon -y

# Or use IP directly
hostname -I

Connecting Multiple Pis¶

Perfect use case for TruSpace! Connect multiple Raspberry Pis:

# On Pi 1: Generate connection details
./scripts/fetch-connection.sh -e

# Transfer .connection file to Pi 2

# On Pi 2: Connect
./scripts/connectPeer-automatic.sh .connection .connection.password