ruvector/docker/scripts/README.md

RuVector Docker Publishing Scripts

This directory contains scripts for building, testing, and publishing RuVector Docker images.

Scripts

1. build-all.sh

Builds all 8 RuVector Docker images locally.

Usage:

# Build for single platform (default: linux/amd64)
./build-all.sh

# Build for specific platform
./build-all.sh --platform linux/arm64

# Build for multiple platforms (requires buildx)
./build-all.sh --platform linux/amd64,linux/arm64

# Build with specific version
./build-all.sh --version v0.1.5

# Build with custom registry
./build-all.sh --registry myregistry

Features:

• Builds all 8 images in parallel for single platform
• Sequential build for multi-platform (more stable)
• Automatic tagging with version and latest
• Color-coded output with progress indicators
• Error handling and reporting

Images Built:

• ruvector-core
• ruvector-server
• ruvector-cli
• ruvector-gnn
• ruvector-graph
• ruvector-attention
• ruvector-cluster
• ruvector-sona

2. publish-all.sh

Pushes all built images to Docker Hub.

Usage:

# Set credentials (required)
export DOCKER_USERNAME=ruvnet
export DOCKER_PASSWORD=your-token-here

# Publish with default settings (latest)
./publish-all.sh

# Publish specific version
./publish-all.sh --version v0.1.5

# Dry run to see what would be pushed
./publish-all.sh --dry-run --version v0.1.5

# Use custom registry
./publish-all.sh --registry myregistry

Features:

• Automatic login to Docker Hub
• Pushes both version and latest tags
• Dry-run mode for testing
• Validates images exist locally before pushing
• Automatic logout after completion

Requirements:

• DOCKER_USERNAME environment variable
• DOCKER_PASSWORD environment variable (use Docker Hub access token)
• Images must be built locally first (run build-all.sh)

3. test-images.sh

Tests all Docker images to verify they work correctly.

Usage:

# Test all images
./test-images.sh

# Test specific version
./test-images.sh --version v0.1.5

# Test with custom timeout
./test-images.sh --timeout 60

# Test from custom registry
./test-images.sh --registry myregistry

Features:

• Tests each image with appropriate flags (--help, --version)
• Special health check for server image
• Configurable timeout
• Detailed output and error reporting
• Summary report at the end

Tests Performed:

• Image existence check
• Basic execution test (--help flag)
• Server startup and health check
• Exit code validation

GitHub Actions Workflow

The .github/workflows/docker-publish.yml workflow automates the entire build, test, and publish process.

Triggers

1. Tag Push: Automatically runs when you push a tag matching v*

   git tag v0.1.5
   git push origin v0.1.5
   

2. Manual Dispatch: Run manually from GitHub Actions tab

   • Go to Actions → Docker Publish → Run workflow
   • Enter version (e.g., v0.1.5)

What It Does

1. Build Stage:

   • Builds all 8 images using matrix strategy
   • Supports linux/amd64 and linux/arm64 platforms
   • Uses Docker buildx for multi-platform builds
   • Implements layer caching for faster builds
   • Tags with version and latest

2. Test Stage:

   • Pulls each published image
   • Runs basic functionality tests
   • Validates server startup
   • Checks image sizes

3. Release Stage:

   • Creates GitHub Release with notes
   • Lists all published images
   • Includes usage examples
   • Links to docker-compose.yml

Secrets Required

Configure these in your GitHub repository settings (Settings → Secrets → Actions):

• DOCKER_PASSWORD - Docker Hub access token (or password)

Matrix Strategy

The workflow uses a matrix to build all images in parallel:

strategy:
  matrix:
    image:
      - ruvector-core
      - ruvector-server
      - ruvector-cli
      - ruvector-gnn
      - ruvector-graph
      - ruvector-attention
      - ruvector-cluster
      - ruvector-sona

Complete Publishing Workflow

Local Development

# 1. Build all images
cd /workspaces/ruvector/docker/scripts
./build-all.sh --version v0.1.5

# 2. Test images
./test-images.sh --version v0.1.5

# 3. Publish (requires credentials)
export DOCKER_USERNAME=ruvnet
export DOCKER_PASSWORD=your-docker-hub-token
./publish-all.sh --version v0.1.5

CI/CD (Recommended)

# 1. Commit your changes
git add .
git commit -m "Release v0.1.5"

# 2. Create and push tag
git tag v0.1.5
git push origin v0.1.5

# 3. GitHub Actions automatically:
#    - Builds all images for amd64 and arm64
#    - Tests all images
#    - Publishes to Docker Hub
#    - Creates GitHub Release

Platform Support

All images are built for:

• linux/amd64 - Intel/AMD 64-bit
• linux/arm64 - ARM 64-bit (Apple Silicon, AWS Graviton, etc.)

Docker Hub Repository

Published images are available at:

• https://hub.docker.com/r/ruvnet/ruvector-core
• https://hub.docker.com/r/ruvnet/ruvector-server
• https://hub.docker.com/r/ruvnet/ruvector-cli
• https://hub.docker.com/r/ruvnet/ruvector-gnn
• https://hub.docker.com/r/ruvnet/ruvector-graph
• https://hub.docker.com/r/ruvnet/ruvector-attention
• https://hub.docker.com/r/ruvnet/ruvector-cluster
• https://hub.docker.com/r/ruvnet/ruvector-sona

Troubleshooting

Build Failures

# Check Docker buildx
docker buildx ls

# Create new builder if needed
docker buildx create --name ruvector-builder --use

# Inspect builder
docker buildx inspect --bootstrap

Login Issues

# Use access token instead of password
# Create at: https://hub.docker.com/settings/security

# Test login
echo $DOCKER_PASSWORD | docker login -u $DOCKER_USERNAME --password-stdin

Multi-platform Build Issues

# Install QEMU
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify platforms
docker buildx inspect --bootstrap

Best Practices

1. Always test locally before publishing
2. Use semantic versioning for tags (v0.1.5, v1.0.0)
3. Use access tokens instead of passwords
4. Enable 2FA on Docker Hub account
5. Review changes in dry-run mode first
6. Monitor image sizes to keep them optimized
7. Use CI/CD for consistent, automated releases

Version Management

The scripts automatically handle version formatting:

• Input: v0.1.5 or 0.1.5
• Output: 0.1.5 (v prefix stripped)
• Tags created: 0.1.5 and latest

Support

For issues or questions:

• GitHub Issues: https://github.com/ruvnet/ruvector/issues
• Documentation: https://github.com/ruvnet/ruvector