Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
392
vendor/ruvector/scripts/deploy/DEPLOYMENT.md
vendored
Normal file
392
vendor/ruvector/scripts/deploy/DEPLOYMENT.md
vendored
Normal file
@@ -0,0 +1,392 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
1. **crates.io API Token**
|
||||
- Visit https://crates.io/me
|
||||
- Generate a new API token
|
||||
- Set as environment variable: `export CRATES_API_KEY="your-token"`
|
||||
|
||||
2. **NPM Authentication Token**
|
||||
- Login to npm: `npm login`
|
||||
- Or create token: `npm token create`
|
||||
- Set as environment variable: `export NPM_TOKEN="your-token"`
|
||||
|
||||
3. **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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
./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:**
|
||||
```bash
|
||||
./scripts/deploy.sh --skip-npm
|
||||
```
|
||||
|
||||
**Publish only to npm:**
|
||||
```bash
|
||||
./scripts/deploy.sh --skip-crates
|
||||
```
|
||||
|
||||
**Quick deployment (skip all checks):**
|
||||
```bash
|
||||
# ⚠️ Not recommended for production
|
||||
./scripts/deploy.sh --skip-tests --skip-checks --force
|
||||
```
|
||||
|
||||
**Test deployment process:**
|
||||
```bash
|
||||
./scripts/deploy.sh --dry-run
|
||||
```
|
||||
|
||||
**Deploy specific version:**
|
||||
```bash
|
||||
./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:
|
||||
|
||||
1. Reads version from workspace `Cargo.toml`
|
||||
2. Updates all `package.json` files
|
||||
3. Ensures consistency across the monorepo
|
||||
|
||||
### Manual Version Update
|
||||
|
||||
To bump version manually:
|
||||
|
||||
```bash
|
||||
# 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](https://semver.org/):
|
||||
- **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"**
|
||||
```bash
|
||||
export CRATES_API_KEY="your-token"
|
||||
```
|
||||
|
||||
**2. "NPM_TOKEN not set"**
|
||||
```bash
|
||||
export NPM_TOKEN="your-token"
|
||||
```
|
||||
|
||||
**3. "Tests failed"**
|
||||
```bash
|
||||
# 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"**
|
||||
```bash
|
||||
# Fix clippy warnings
|
||||
cargo clippy --all-targets --all-features --fix
|
||||
|
||||
# Or skip checks (not recommended)
|
||||
./scripts/deploy.sh --skip-checks
|
||||
```
|
||||
|
||||
**5. "Code formatting issues"**
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# Bump version in Cargo.toml
|
||||
./scripts/deploy.sh --version 0.2.1
|
||||
```
|
||||
|
||||
**7. "WASM build failed"**
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
ls -lt logs/deployment/
|
||||
tail -f logs/deployment/deploy-*.log
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Create `.github/workflows/deploy.yml`:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user