Round Local Development

Round Local Development

This guide explains how to set up and run the Round service locally without Docker.

Quick Start

1. Run Setup Script

The setup script downloads all required dependencies:

./setup-local-dev.sh

This will:

• Download ONNX Runtime v1.23.1 (8-22MB depending on architecture)
• Download tokenizers library (~14MB)
• Create necessary symlinks
• Generate .env.local with environment variables

2. Build the Service

source .env.local
make build

3. Run the Service

Option A: Using the wrapper script (recommended)

./run-local.sh

Option B: Run binary directly with environment

source .env.local
./bin/app

Option C: Full command

LD_LIBRARY_PATH="$(pwd)/.local-deps/onnxruntime-linux-x64-1.23.1/lib:$(pwd)/.local-deps:$LD_LIBRARY_PATH" \
  MODEL_CACHE_DIR="$(pwd)/models" \
  LOG_LEVEL=debug \
  GRPC_PORT=8080 \
  ./bin/app

Testing

Test that the service is running:

# List available models
grpcurl -plaintext localhost:8080 round.v1.RoundService/ListModels

# Test face detection with an image
cat > /tmp/test_request.json << 'EOF'
{
  "model_id": "face-detection",
  "image_base64": "$(base64 -w 0 < your-image.jpg)"
}
EOF

grpcurl -plaintext -d @ localhost:8080 round.v1.RoundService/Infer < /tmp/test_request.json

Running Tests

# Source environment first
source .env.local

# Run unit tests (embeddings tests will fail without tokenizers lib, but that's expected)
make run-tests

# Run embeddings benchmark inside the docker build image (no local CGO deps needed)
make bench-embeddings

# Run linter
make lint

Troubleshooting

Error: onnxruntime.so: cannot open shared object file

Cause: The LD_LIBRARY_PATH is not set correctly.

Solution:

# Make sure to source the environment file
source .env.local

# Or set it manually
export LD_LIBRARY_PATH="$(pwd)/.local-deps/onnxruntime-linux-x64-1.23.1/lib:$(pwd)/.local-deps:$LD_LIBRARY_PATH"

Error: cannot find -ltokenizers

Cause: The tokenizers library is not installed or CGO_LDFLAGS is not set.

Solution:

# Re-run setup script
./setup-local-dev.sh

# Then rebuild
source .env.local
make build

Port Already in Use

Error: address already in use

Solution:

# Check what's using port 8080
lsof -i :8080

# Kill the process or use a different port
export GRPC_PORT=8081
./run-local.sh

Dependencies Structure

After running setup, your directory structure will look like:

apps/round/
├── .local-deps/              # Downloaded dependencies
│   ├── onnxruntime-linux-*/  # ONNX Runtime C libraries
│   │   ├── include/          # Header files for building
│   │   └── lib/              # Shared libraries (.so files)
│   ├── libtokenizers.a       # Static tokenizers library
│   └── libtokenizers.so      # Shared tokenizers library
├── .env.local                # Auto-generated environment file
├── setup-local-dev.sh        # Setup script
├── run-local.sh              # Wrapper to run service
├── models/                   # ONNX model files
└── bin/                      # Built binary (after make build)

Environment Variables

The .env.local file sets these variables automatically:

Variable	Value	Purpose
CGO_ENABLED	1	Enable CGO for C library linking
LD_LIBRARY_PATH	.local-deps/onnxruntime-*/lib:.local-deps	Runtime library search path
CGO_CFLAGS	-I.local-deps/onnxruntime-*/include	C header files path for building
CGO_LDFLAGS	-L... -lonnxruntime -ltokenizers	Linker flags for C libraries
MODEL_CACHE_DIR	./models	Directory containing ONNX models
LOG_LEVEL	debug	Logging verbosity
GRPC_PORT	8080	gRPC server port

Cleaning Up

To remove all downloaded dependencies:

rm -rf .local-deps .env.local

To rebuild from scratch:

# Clean dependencies
rm -rf .local-deps .env.local bin/

# Re-setup
./setup-local-dev.sh

# Rebuild
source .env.local
make build

Development Workflow

1. Make code changes
2. Rebuild: source .env.local && make build
3. Test: make run-tests && make lint
4. Run: ./run-local.sh
5. Test API: Use grpcurl to test endpoints

Notes

• The .local-deps directory is ignored by git (should be in .gitignore)
• Library downloads are cached - setup is fast after first run
• The symlinks (onnxruntime.so) are required because the Go bindings expect files without the “lib” prefix
• Both ONNX Runtime and tokenizers must be in LD_LIBRARY_PATH at runtime