Building eq-synapse

This guide covers building eq-synapse packages for deployment on ARM64 gateway hardware.

Quick Start

Full Debian Package Build (Recommended for Releases)

Builds complete .deb packages with Rust binaries, Python packages, and web frontend:

cd deployment
./build-in-docker.sh

Output: deployment/dist/eq-synapse_*.deb (plus eq-gateway_*.deb for managed devices)

First build: ~15-20 minutes (builds Docker image) Subsequent builds: ~5-10 minutes (reuses cached image)

Rust Binary Only (Quick Development Testing)

For rapid iteration when working on Rust code:

# Install cross (one-time setup)
cargo install cross

# Build ARM64 binary
cd server
cross build --target aarch64-unknown-linux-gnu --release

Output: server/target/aarch64-unknown-linux-gnu/release/synapse

Build time: ~2-5 minutes (incremental)

Cargo Workspace Structure

The Rust codebase uses a Cargo workspace with default-members to speed up development builds:

# Development build (default members only - faster)
cd server
cargo build --release

# Full build (all members including unified-backend)
cargo build --workspace --release

What’s Included

Excluded from Default Builds

These are built only with --workspace:

• synapse-web/services/unified-backend - Web backend service
• synapse-web/eq-web - Web framework library
• synapse-rag/ingestion_testing - Testing utilities

The Debian package build (build-in-docker.sh) automatically uses --workspace to include all production binaries.

Build Methods Comparison

Detailed Build Instructions

Option 1: Docker Build (Production)

This is the primary method for building release packages. It ensures compatibility with Debian 12 (Bookworm) gateways by building inside a Docker container with the exact same OS and glibc version.

Prerequisites

One-time setup:

# Install Docker (if not already installed)
sudo apt-get update && sudo apt-get install -y docker.io
sudo usermod -aG docker $USER
# Log out and back in for group membership to take effect

# Start Docker service (in WSL2)
sudo service docker start

Building

cd deployment
./build-in-docker.sh

What it does:

1. Builds/reuses Debian 12 (Bookworm) Docker image with:
   • ARM64 cross-compilation toolchain
   • Rust 1.89.0
   • Node.js 18.x
   • Python build tools
   • All system dependencies
2. Compiles Rust binaries for ARM64
3. Builds Python wheel
4. Builds Sight frontend (React/TypeScript)
5. Packages everything into .deb files

Output files:

deployment/dist/
├── eq-synapse_0.3.3~rc14_all.deb     # Core platform (works anywhere)
└── eq-gateway_0.3.3~rc14_all.deb     # Managed device overlay

Build Options

# Skip Rust build (reuse existing binary)
./build-in-docker.sh --skip-cargo

Option 2: Cross (Rust Development)

Use this for quick iteration when working on Rust code. Much faster than full Docker build.

Prerequisites

One-time setup:

cargo install cross

That’s it! No need to install ARM64 toolchains, OpenSSL dev packages, or configure linkers. cross handles everything in Docker.

Building

cd server
cross build --target aarch64-unknown-linux-gnu --release

Output: server/target/aarch64-unknown-linux-gnu/release/synapse

What cross Does

• Automatically downloads Docker image with ARM64 toolchain
• Handles OpenSSL cross-compilation
• Manages all C dependencies
• No host system configuration needed

When to Use

• ✅ Quick Rust testing: Test binary changes without full package build
• ✅ Development iteration: Fast compile-test cycles
• ❌ Production releases: Use Docker build for complete packages

Option 3: Native Build (Not Recommended)

⚠️ WARNING: Building on Ubuntu 24.04 creates binaries with glibc 2.39 dependencies that will not run on Debian 12 gateways (glibc 2.36).

Only use this if:

• You’re on Debian 12 (Bookworm)
• You understand the glibc compatibility issues

# Install dependencies (Debian 12 only!)
sudo apt-get install gcc-aarch64-linux-gnu crossbuild-essential-arm64
sudo dpkg --add-architecture arm64
sudo apt-get install libssl-dev:arm64

# Add Rust target
rustup target add aarch64-unknown-linux-gnu

# Build
cd deployment
./build.sh

Version Management

EQ Synapse uses git tags for versioning:

Creating a Version

# Release candidate
git tag v0.3.3rc14

# Final release
git tag v0.3.3

Version Formats

The build system automatically converts git versions to package-compatible formats:

Version Errors

If you see:

Error: Version 'X.Y.Z+foo+bar' is not PEP 440 compliant (multiple '+' characters)!

Fix: Create a proper git tag:

git tag v0.3.3rc15  # Use next RC number

Development Workflow

Typical Development Cycle

# 1. Make code changes
vim server/crates/synapse-cli/src/main.rs

# 2. Quick test with cross
cd server
cross build --target aarch64-unknown-linux-gnu --release

# 3. Test binary on device or locally
scp target/aarch64-unknown-linux-gnu/release/synapse gateway:~/

# 4. When ready for full package
cd system
git add -A && git commit -m "feature: add new capability"
git tag v0.3.3rc15
./build-in-docker.sh

# 5. Deploy package
scp dist/eq-synapse_*.deb dist/eq-gateway_*.deb gateway:~/

Release Workflow

# 1. Finalize changes
git add -A && git commit -m "chore: prepare v0.3.3 release"

# 2. Create release tag
git tag v0.3.3

# 3. Build production packages
cd deployment
./build-in-docker.sh

# 4. Test on gateway
scp dist/eq-synapse_0.3.3_all.deb dist/eq-gateway_0.3.3_all.deb gateway:~/
ssh gateway "sudo apt install ~/eq-synapse_0.3.3_all.deb ~/eq-gateway_0.3.3_all.deb"

# 5. Push release
git push origin main --tags

Troubleshooting

Docker Image Won’t Build

# Force rebuild with legacy builder (WSL2)
export DOCKER_BUILDKIT=0
docker rmi synapse-builder-jammy:latest
./build-in-docker.sh

“Cargo not installed” in Docker

The build script sources cargo environment automatically. If this fails:

# Check if cargo is in PATH inside container
docker run --rm synapse-builder-jammy:latest cargo --version

Should output: cargo 1.89.0

OpenSSL Cross-Compilation Errors

If using native cargo build (not cross):

# Verify ARM64 OpenSSL is installed
dpkg -l | grep libssl-dev:arm64

# Set required environment variables
export PKG_CONFIG_ALLOW_CROSS=1
export PKG_CONFIG_PATH="/usr/lib/aarch64-linux-gnu/pkgconfig"
export AARCH64_UNKNOWN_LINUX_GNU_OPENSSL_DIR="/usr"

Better solution: Use cross instead - it handles this automatically.

glibc Version Mismatch on Gateway

Error:

/usr/bin/synapse: /lib/aarch64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found

Cause: Binary was built on Ubuntu 24.04 (glibc 2.39) but gateway runs Debian 12 (glibc 2.36)

Fix: Use Docker build method - it builds with Debian 12 (Bookworm) environment

Build System Architecture

Docker Build (build-in-docker.sh)

┌─────────────────────────────────────────┐
│  build-in-docker.sh (Host)              │
│  ├─ Builds/reuses Docker image          │
│  ├─ Mounts syntropy repo as /workspace  │
│  └─ Runs build.sh inside container      │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│  Docker Container (Debian 12 Bookworm)  │
│  ├─ Rust 1.89.0 + ARM64 target          │
│  ├─ Node.js 18.x                        │
│  ├─ Python 3.11 + build tools           │
│  ├─ ARM64 cross-toolchain               │
│  └─ Executes build.sh                   │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│  build.sh (Inside Container)            │
│  ├─ Gets version from git tags          │
│  ├─ Updates Cargo.toml version          │
│  ├─ Builds Rust binaries (cargo)        │
│  ├─ Builds Python wheel                 │
│  ├─ Builds Sight frontend (npm)         │
│  └─ Packages with debuild               │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│  Output: .deb packages                  │
│  deployment/dist/                       │
│  ├─ eq-synapse_*.deb (core platform)    │
│  └─ eq-gateway_*.deb (managed overlay)  │
└─────────────────────────────────────────┘

Why Docker?

Problem: Building on Ubuntu 24.04 creates binaries that don’t run on Debian 12 gateways

Solution: Docker container with Debian 12 (Bookworm) ensures binary compatibility

Benefits:

• ✅ Consistent build environment
• ✅ No host system pollution
• ✅ glibc 2.36 compatibility guaranteed
• ✅ Reproducible builds
• ✅ Works on any Linux distribution

CI/CD Integration (Future)

The Docker build system is designed for CI/CD integration:

# Example GitHub Actions workflow
name: Build Packages
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build packages
        run: |
          cd deployment
          ./build-in-docker.sh
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: packages
          path: deployment/dist/*.deb

Additional Resources

• Server README: server/README.md - Rust crate structure
• System README: deployment/README.md - Debian packaging details
• Gateway Architecture: docs/developer/server/gateway-architecture.md - Data pipeline and systemd services
• Release Scripts: deployment/release.sh - Version management