diff options
Diffstat (limited to 'test/foundationdb/README.ARM64.md')
| -rw-r--r-- | test/foundationdb/README.ARM64.md | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/test/foundationdb/README.ARM64.md b/test/foundationdb/README.ARM64.md new file mode 100644 index 000000000..88ca292dd --- /dev/null +++ b/test/foundationdb/README.ARM64.md @@ -0,0 +1,134 @@ +# ARM64 Support for FoundationDB Integration + +This document explains how to run FoundationDB integration tests on ARM64 systems (Apple Silicon M1/M2/M3 Macs). + +## Problem + +The official FoundationDB Docker images (`foundationdb/foundationdb:7.1.61`) are only available for `linux/amd64` architecture. When running on ARM64 systems, you'll encounter "Illegal instruction" errors. Apple now publishes official ARM64 Debian packages (starting with 7.4.5), which this repo downloads directly for native workflows. + +## Solutions + +We provide **three different approaches** to run FoundationDB on ARM64: + +### 1. 🚀 ARM64 Native (Recommended for Development) + +**Pros:** Native performance, no emulation overhead +**Cons:** Requires downloading ~100MB of FoundationDB packages on first run + +```bash +# Build and run ARM64-native FoundationDB from source +make setup-arm64 +make test-arm64 +``` + +This approach: +- Downloads the official FoundationDB 7.4.5 ARM64 packages +- Takes ~2-3 minutes on first run (no source compilation) +- Provides native performance +- Uses `docker-compose.arm64.yml` + +### 2. 🐳 x86 Emulation (Quick Setup) + +**Pros:** Fast setup, uses official images +**Cons:** Slower runtime performance due to emulation + +```bash +# Run x86 images with Docker emulation +make setup-emulated +make test-emulated +``` + +This approach: +- Uses Docker's x86 emulation +- Quick setup with official images +- May have performance overhead +- Uses standard `docker-compose.yml` with platform specification + +### 3. 📝 Mock Testing (Fastest) + +**Pros:** No dependencies, always works, fast execution +**Cons:** Doesn't test real FoundationDB integration + +```bash +# Run mock tests (no FoundationDB cluster needed) +make test-mock +make test-reliable +``` + +## Files Overview + +| File | Purpose | +|------|---------| +| `docker-compose.yml` | Standard setup with platform specification | +| `docker-compose.arm64.yml` | ARM64-native setup with source builds | +| `Dockerfile.fdb-arm64` | Multi-stage build for ARM64 FoundationDB | +| `README.ARM64.md` | This documentation | + +## Performance Comparison + +| Approach | Setup Time | Runtime Performance | Compatibility | +|----------|------------|-------------------|---------------| +| ARM64 Native | 2-3 min | ⭐⭐⭐⭐⭐ | ARM64 only | +| x86 Emulation | 2-3 min | ⭐⭐⭐ | ARM64 + x86 | +| Mock Testing | < 1 min | ⭐⭐⭐⭐⭐ | Any platform | + +## Quick Start Commands + +```bash +# For ARM64 Mac users - choose your approach: + +# Option 1: ARM64 native (best performance) +make clean && make setup-arm64 + +# Option 2: x86 emulation (faster setup) +make clean && make setup-emulated + +# Option 3: Mock testing (no FDB needed) +make test-mock + +# Clean up everything +make clean +``` + +## Troubleshooting + +### Build Timeouts +If ARM64 builds timeout, increase Docker build timeout: +```bash +export DOCKER_BUILDKIT=1 +export BUILDKIT_PROGRESS=plain +make setup-arm64 +``` + +### Memory Issues +ARM64 builds require significant memory: +- Increase Docker memory limit to 8GB+ +- Close other applications during build + +### Platform Detection +Verify your platform: +```bash +docker info | grep -i arch +uname -m # Should show arm64 +``` + +## CI/CD Recommendations + +- **Development**: Use `make test-mock` for fast feedback +- **ARM64 CI**: Use `make setup-arm64` +- **x86 CI**: Use `make setup` (standard) +- **Multi-platform CI**: Run both depending on runner architecture + +## Architecture Details + +The ARM64 solution now uses the official FoundationDB 7.4.5 aarch64 packages: + +1. **Builder Stage**: Downloads prebuilt FoundationDB client libraries + - Uses Debian-based Go image for compiling SeaweedFS + - Verifies SHA256 checksums before installing the deb package + +2. **Runtime Stage**: Copies the already-installed artifacts + - SeaweedFS runtime layers reuse the validated libraries + - FoundationDB server containers install the prebuilt server + client packages with checksum verification + +This keeps the setup time short while preserving native ARM64 performance and strong supply-chain guarantees. |