dearsky/wifi-densepose

Fork 0

Files

ruv cd5943df23 Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

2026-02-28 14:39:40 -05:00

8.2 KiB

Raw Blame History

RuVector Deployment Guide

This guide covers the comprehensive deployment process for ruvector using the deploy.sh script.

Prerequisites

Required Tools

Rust toolchain (rustc, cargo) - v1.77 or later
Node.js - v18 or later
npm - Latest version
wasm-pack - For WASM builds
jq - For JSON manipulation

Install missing tools:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Node.js and npm (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Install wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Install jq (Ubuntu/Debian)
sudo apt-get install jq

# Install jq (macOS)
brew install jq

Required Credentials

crates.io API Token
- Visit https://crates.io/me
- Generate a new API token
- Set as environment variable: export CRATES_API_KEY="your-token"
NPM Authentication Token
- Login to npm: npm login
- Or create token: npm token create
- Set as environment variable: export NPM_TOKEN="your-token"
GitHub Personal Access Token (Optional, for GitHub Actions)
- Visit https://github.com/settings/tokens
- Generate token with repo and workflow scopes
- Set as environment variable: export GITHUB_TOKEN="your-token"

Quick Start

Full Deployment

# Export required credentials
export CRATES_API_KEY="your-crates-io-token"
export NPM_TOKEN="your-npm-token"

# Run deployment
./scripts/deploy.sh

Dry Run (Test Without Publishing)

./scripts/deploy.sh --dry-run

Usage Options

Command-Line Flags

Flag	Description
`--dry-run`	Test deployment without publishing
`--skip-tests`	Skip test suite execution
`--skip-crates`	Skip crates.io publishing
`--skip-npm`	Skip NPM publishing
`--skip-checks`	Skip clippy and formatting checks
`--force`	Skip confirmation prompts
`--version VERSION`	Set explicit version (default: read from Cargo.toml)
`-h, --help`	Show help message

Common Scenarios

Publish only to crates.io:

./scripts/deploy.sh --skip-npm

Publish only to npm:

./scripts/deploy.sh --skip-crates

Quick deployment (skip all checks):

# ⚠️ Not recommended for production
./scripts/deploy.sh --skip-tests --skip-checks --force

Test deployment process:

./scripts/deploy.sh --dry-run

Deploy specific version:

./scripts/deploy.sh --version 0.2.0

Deployment Process

The script performs the following steps in order:

1. Prerequisites Check

Verifies required tools (cargo, npm, wasm-pack, jq)
Checks for required environment variables
Displays version information

2. Version Management

Reads version from workspace Cargo.toml
Synchronizes version to all package.json files
Updates:
- Root package.json
- crates/ruvector-node/package.json
- crates/ruvector-wasm/package.json
- All other NPM package manifests

3. Pre-Deployment Checks

Test Suite: cargo test --all
Clippy Linter: cargo clippy --all-targets --all-features
Format Check: cargo fmt --all -- --check

4. WASM Package Builds

Builds all WASM packages:

ruvector-wasm
ruvector-gnn-wasm
ruvector-graph-wasm
ruvector-tiny-dancer-wasm

5. Crate Publishing

Publishes crates to crates.io in dependency order:

Core crates:

ruvector-core
ruvector-metrics
ruvector-filter

Cluster crates:

ruvector-collections
ruvector-snapshot
ruvector-raft
ruvector-cluster
ruvector-replication

Graph and GNN:

ruvector-graph
ruvector-gnn

Router:

ruvector-router-core
ruvector-router-ffi
ruvector-router-wasm
ruvector-router-cli

Tiny Dancer:

ruvector-tiny-dancer-core
ruvector-tiny-dancer-wasm
ruvector-tiny-dancer-node

Bindings:

ruvector-node
ruvector-wasm
ruvector-gnn-node
ruvector-gnn-wasm
ruvector-graph-node
ruvector-graph-wasm

CLI/Server:

ruvector-cli
ruvector-server
ruvector-bench

6. NPM Publishing

Publishes NPM packages:

@ruvector/node
@ruvector/wasm
@ruvector/gnn
@ruvector/gnn-wasm
@ruvector/graph-node
@ruvector/graph-wasm
@ruvector/tiny-dancer
@ruvector/tiny-dancer-wasm

7. GitHub Actions Trigger

Triggers cross-platform native builds (if GITHUB_TOKEN set)

Version Management

Automatic Version Sync

The script automatically synchronizes versions across all package manifests:

Reads version from workspace Cargo.toml
Updates all package.json files
Ensures consistency across the monorepo

Manual Version Update

To bump version manually:

# 1. Update workspace Cargo.toml
sed -i 's/^version = .*/version = "0.2.0"/' Cargo.toml

# 2. Run deployment (will sync all packages)
./scripts/deploy.sh

Semantic Versioning

Follow Semantic Versioning:

MAJOR (0.x.0): Breaking changes
MINOR (x.1.0): New features, backward compatible
PATCH (x.x.1): Bug fixes, backward compatible

Troubleshooting

Common Issues

1. "CRATES_API_KEY not set"

export CRATES_API_KEY="your-token"

2. "NPM_TOKEN not set"

export NPM_TOKEN="your-token"

3. "Tests failed"

# Run tests manually to see details
cargo test --all --verbose

# Skip tests if needed (not recommended)
./scripts/deploy.sh --skip-tests

4. "Clippy found issues"

# Fix clippy warnings
cargo clippy --all-targets --all-features --fix

# Or skip checks (not recommended)
./scripts/deploy.sh --skip-checks

5. "Code formatting issues"

# Format code
cargo fmt --all

# Then retry deployment
./scripts/deploy.sh

6. "Crate already published"

The script automatically skips already-published crates. If you need to publish a new version:

# Bump version in Cargo.toml
./scripts/deploy.sh --version 0.2.1

7. "WASM build failed"

# Install wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Build manually to see errors
cd crates/ruvector-wasm
wasm-pack build --target web --release

Logs

Deployment logs are saved to logs/deployment/deploy-YYYYMMDD-HHMMSS.log

View recent logs:

ls -lt logs/deployment/
tail -f logs/deployment/deploy-*.log

CI/CD Integration

GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy

on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install wasm-pack
        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

      - name: Install jq
        run: sudo apt-get install -y jq

      - name: Deploy
        env:
          CRATES_API_KEY: ${{ secrets.CRATES_API_KEY }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: ./scripts/deploy.sh --force

Manual Deployment Checklist

All tests passing locally
Code formatted (cargo fmt --all)
No clippy warnings
Version bumped in Cargo.toml
CHANGELOG updated
Environment variables set
Dry run successful
Ready to publish

Security Best Practices

Credentials Management

Never commit credentials to git!

Use environment variables or secure vaults:

# Use .env file (add to .gitignore)
cat > .env << EOF
CRATES_API_KEY=your-token
NPM_TOKEN=your-token
GITHUB_TOKEN=your-token
EOF

# Source before deployment
source .env
./scripts/deploy.sh

Or use a password manager:

# Example with pass
export CRATES_API_KEY=$(pass show crates-io/api-key)
export NPM_TOKEN=$(pass show npm/token)

Support

For issues or questions:

GitHub Issues: https://github.com/ruvnet/ruvector/issues
Documentation: https://github.com/ruvnet/ruvector
Deployment Logs: logs/deployment/

License

MIT License - See LICENSE file for details

8.2 KiB Raw Blame History