From 460a88c5b1da9ebbb23b8f5207233c78288e8275 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 8 May 2026 13:04:27 -0700 Subject: [PATCH 1/2] README: add compass logo SVG, centered header with badges Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/CODEOWNERS | 30 +++-- .github/FUNDING.yml | 2 + .github/ISSUE_TEMPLATE/bug_report.md | 51 +++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 28 +++++ .github/PULL_REQUEST_TEMPLATE.md | 40 +++++-- .github/workflows/release.yml | 133 +++++++++++----------- CODE_OF_CONDUCT.md | 27 ++--- README.md | 14 ++- SECURITY.md | 49 +++++--- docker-compose.yml | 41 ++++++- docs/compass-logo.svg | 57 ++++++++++ 11 files changed, 346 insertions(+), 126 deletions(-) create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 docs/compass-logo.svg diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 2ba1566..b682377 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,9 +1,25 @@ -# Default owners for everything -* @runcaptain/eng +# Global owners +* @lewis @edgar -# Vector backends -crates/compass-index-api/ @runcaptain/eng -crates/compass-vector-gpu/ @runcaptain/eng +# Architecture and storage +crates/compass/src/collections/ @lewis @edgar +crates/compass/src/search/ @lewis @edgar -# CI and release -.github/ @runcaptain/eng +# GPU backend +crates/compass-vector-gpu/ @lewis @edgar + +# API trait +crates/compass-index-api/ @lewis @edgar + +# Documentation +*.md @lewis @edgar +ARCHITECTURE.md @lewis @edgar +CONTRIBUTING.md @lewis @edgar + +# CI/CD +.github/ @lewis @edgar +Dockerfile* @lewis @edgar + +# Dependency and manifest changes +Cargo.toml @lewis @edgar +Cargo.lock @lewis @edgar diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..4482b2a --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,2 @@ +github: [runcaptain] +custom: ["https://runcaptain.com"] diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..5aae13c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,51 @@ +--- +name: Bug Report +about: Report a bug or unexpected behavior +title: "[BUG] " +labels: bug +assignees: '' + +--- + +## Describe the bug + +A clear and concise description of what the bug is. + +## Steps to reproduce + +1. ... +2. ... +3. ... + +## Expected behavior + +What should happen. + +## Actual behavior + +What actually happens instead. + +## Environment + +- **Compass version** (or git SHA): +- **OS and architecture**: +- **Rust version** (`rustc --version`): +- **Data directory size**: +- **Collection size** (approximate): + +## Logs + +If applicable, reproduce with debug logging: +```bash +RUST_LOG=compass=debug ./compass +``` + +Then paste relevant log output here: + +``` +[paste logs] +``` + +## Additional context + +Any other context that might be helpful. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..4cf58dc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,28 @@ +--- +name: Feature Request +about: Suggest an idea for Compass +title: "[FEATURE] " +labels: enhancement +assignees: '' + +--- + +## Description + +A clear and concise description of what you'd like to see. + +## Motivation + +Why should this feature exist? What problem does it solve? + +## Proposed solution + +Describe how you'd like the feature to work. + +## Alternatives + +Have you considered any alternative approaches? + +## Additional context + +Any other context or examples (e.g., similar features in other projects). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a9bcf20..c41552c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,16 +1,36 @@ -## Summary +## Description - +Briefly describe the changes in this PR. -## Test plan +## Related issue - +Fixes #(issue number) or closes #(issue number) -- [ ] `cargo test` passes -- [ ] `cargo clippy` clean -- [ ] `cargo fmt` clean -- [ ] Tested with Docker build (if applicable) +## Type of change -## Changelog +- [ ] Bug fix (non-breaking) +- [ ] New feature (non-breaking) +- [ ] Breaking change +- [ ] Documentation update +- [ ] Performance improvement - +## Testing + +How have you tested these changes? Include steps to reproduce. + +## Checklist + +- [ ] `cargo fmt --all` is clean +- [ ] `cargo clippy --workspace -- -D warnings` passes +- [ ] `cargo test --workspace` passes +- [ ] CHANGELOG.md updated under `[Unreleased]` section +- [ ] Public API changes have rustdoc comments +- [ ] Behavior changes have a regression test + +## Before/after (if applicable) + +Performance benchmarks, screenshots, or other evidence of the change: + +``` +(paste before/after data here) +``` diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e03d684..79e5f95 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -3,85 +3,86 @@ name: Release on: push: tags: - - "v*" + - 'v*' env: CARGO_TERM_COLOR: always jobs: - build: - name: Build (${{ matrix.target }}) - runs-on: ${{ matrix.os }} - strategy: - matrix: - include: - - target: x86_64-unknown-linux-gnu - os: ubuntu-24.04 - artifact: compass-linux-amd64 - - target: aarch64-unknown-linux-gnu - os: ubuntu-24.04 - artifact: compass-linux-arm64 - - target: aarch64-apple-darwin - os: macos-14 - artifact: compass-macos-arm64 + create-release: + name: Create GitHub Release + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable with: - targets: ${{ matrix.target }} + fetch-depth: 0 + + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 - - if: matrix.target == 'aarch64-unknown-linux-gnu' + + - name: Extract version from tag + id: version + run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT + + - name: Verify tag matches Cargo.toml run: | - sudo apt-get update - sudo apt-get install -y gcc-aarch64-linux-gnu cmake pkg-config libssl-dev - echo "CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc" >> $GITHUB_ENV - - if: matrix.os == 'ubuntu-24.04' && matrix.target == 'x86_64-unknown-linux-gnu' + CARGO_VERSION=$(grep "^version" crates/compass/Cargo.toml | head -1 | sed 's/.*"\([^"]*\)".*/\1/') + if [ "${{ steps.version.outputs.version }}" != "$CARGO_VERSION" ]; then + echo "Tag version ${{ steps.version.outputs.version }} does not match Cargo.toml version $CARGO_VERSION" + exit 1 + fi + + - name: Build release binaries + run: cargo build --release -p compass + + - name: Extract changelog section + id: changelog run: | - sudo apt-get update - sudo apt-get install -y cmake pkg-config libssl-dev - - run: cargo build --release --target ${{ matrix.target }} -p compass - - run: | - mkdir -p dist - cp target/${{ matrix.target }}/release/compass dist/${{ matrix.artifact }} - - uses: actions/upload-artifact@v4 - with: - name: ${{ matrix.artifact }} - path: dist/${{ matrix.artifact }} + # Extract changelog between tag and previous tag + VERSION="${{ steps.version.outputs.version }}" + PREV_TAG=$(git describe --tags --abbrev=0 $(git rev-list --tags --skip=1 -n1) 2>/dev/null || echo "HEAD") + + # Extract relevant section from CHANGELOG.md + CHANGELOG=$(sed -n "/## \[$VERSION\]/,/## \[/p" CHANGELOG.md | sed '$ d') + + # Escape for GitHub Actions + CHANGELOG="${CHANGELOG//'%'/'%25'}" + CHANGELOG="${CHANGELOG//$'\n'/'%0A'}" + CHANGELOG="${CHANGELOG//$'\r'/'%0D'}" + + echo "body=$CHANGELOG" >> $GITHUB_OUTPUT - docker: - name: Docker image - runs-on: ubuntu-24.04 - permissions: - contents: read - packages: write - steps: - - uses: actions/checkout@v4 - - uses: docker/login-action@v3 - with: - registry: ghcr.io - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - - uses: docker/build-push-action@v6 + - name: Create Release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: - context: . - push: true - tags: | - ghcr.io/${{ github.repository }}:${{ github.ref_name }} - ghcr.io/${{ github.repository }}:latest - - release: - name: GitHub Release - needs: [build, docker] + tag_name: ${{ github.ref }} + release_name: Release v${{ steps.version.outputs.version }} + body: ${{ steps.changelog.outputs.body }} + draft: false + prerelease: false + + publish-crate: + name: Publish to crates.io runs-on: ubuntu-24.04 - permissions: - contents: write + needs: create-release steps: - uses: actions/checkout@v4 - - uses: actions/download-artifact@v4 - with: - path: dist - merge-multiple: true - - uses: softprops/action-gh-release@v2 - with: - generate_release_notes: true - files: dist/* + + - uses: dtolnay/rust-toolchain@stable + + - uses: Swatinem/rust-cache@v2 + + - name: Run tests before publish + run: cargo test --workspace --exclude compass-vector-gpu + + - name: Publish compass-index-api + run: cargo publish -p compass-index-api --token ${{ secrets.CARGO_TOKEN }} + + - name: Publish compass + run: cargo publish -p compass --token ${{ secrets.CARGO_TOKEN }} + + - name: Wait for crates.io to index + run: sleep 30 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 87e8d56..d526a0f 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,38 +1,31 @@ # Contributor Covenant Code of Conduct -## Our Pledge +## Our Commitment -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. +We are committed to providing a welcoming and inspiring community for all. We expect all participants in the Compass community to uphold this code of conduct. ## Our Standards -Examples of behavior that contributes to a positive environment: +Examples of behavior that contributes to creating a positive environment include: * Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences +* Being respectful of differing opinions, viewpoints, and experiences * Gracefully accepting constructive criticism * Focusing on what is best for the community * Showing empathy towards other community members -Examples of unacceptable behavior: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery, and sexual attention or advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information without explicit permission +* Publishing others' private information, such as a physical or electronic address, without explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the project team at **conduct@runcaptain.com**. All complaints will -be reviewed and investigated promptly and fairly. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at founders@runcaptain.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1. +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2_1/code_of_conduct.html. diff --git a/README.md b/README.md index a068d51..9b0becc 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ -# Compass +
+ Compass +

Compass

+

Embedded vector + full-text search engine. Single binary, zero external dependencies.

-[![CI](https://github.com/runcaptain/compass/actions/workflows/ci.yml/badge.svg)](https://github.com/runcaptain/compass/actions/workflows/ci.yml) -[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) -[![Rust](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org) + [![CI](https://github.com/runcaptain/compass/actions/workflows/ci.yml/badge.svg)](https://github.com/runcaptain/compass/actions/workflows/ci.yml) + [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) + [![Rust](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org) +
-Embedded vector + full-text search engine for [Captain](https://runcaptain.com). Single binary, zero external dependencies. Designed for high-throughput retrieval. Built for on-prem enterprise deployments where customer data cannot leave their VPC. +Built by [Captain](https://runcaptain.com) for high-throughput retrieval in on-prem enterprise deployments where customer data cannot leave their VPC. ## What it does diff --git a/SECURITY.md b/SECURITY.md index a70dbc2..673ef1c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,24 +1,41 @@ # Security Policy -## Supported Versions +## Reporting a Vulnerability -| Version | Supported | -| ------- | ------------------ | -| 0.2.x | Yes | -| < 0.2 | No | +We take the security of Compass seriously. If you discover a security vulnerability, please email founders@runcaptain.com with the following information: -## Reporting a Vulnerability +1. **Description** of the vulnerability +2. **Steps to reproduce** (if applicable) +3. **Affected versions** (or commit SHA if pre-release) +4. **Potential impact** (severity assessment) +5. **Proposed fix** (if you have one) + +We will acknowledge your report within **two business days** and work with you to understand and resolve the issue. Please do not publicly disclose the vulnerability until we have released a fix. + +## Security Best Practices for Users + +### Data Protection -If you discover a security vulnerability in Compass, please report it -responsibly. **Do not open a public GitHub issue.** +- Compass stores all data locally on disk. Ensure your DATA_DIR is protected with appropriate file system permissions. +- For on-premises deployments, restrict network access to the Compass HTTP API (default port 4001) using firewalls or reverse proxies. +- Use TLS/SSL when deploying Compass behind a reverse proxy (nginx, HAProxy, etc.). + +### Dependency Updates + +- Regularly run `cargo audit` to check for known vulnerabilities in dependencies. +- Monitor GitHub's security advisories for the Compass repository. +- Keep your Rust toolchain up to date. + +### Model Weights + +- Compass downloads model weights on first run (e.g., BGE-small via Hugging Face Hub). +- Verify downloaded files match expected checksums when possible. +- For air-gapped deployments, pre-download and verify model weights before use. + +## Supported Versions -Email **security@runcaptain.com** with: +Security updates are provided for the current and previous minor versions. Check the CHANGELOG.md for version information. -1. A description of the vulnerability -2. Steps to reproduce -3. Potential impact -4. Suggested fix (if any) +## Acknowledgments -We will acknowledge your report within 48 hours and aim to release a fix -within 7 days for critical issues. You will be credited in the release notes -unless you prefer to remain anonymous. +We appreciate the security research community's efforts in identifying and responsibly disclosing vulnerabilities. We will acknowledge security researchers in our release notes when appropriate. diff --git a/docker-compose.yml b/docker-compose.yml index 7579c4c..cd5c80b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,18 +1,49 @@ +version: '3.8' + services: compass: - build: . + build: + context: . + dockerfile: Dockerfile + container_name: compass ports: - "4001:4001" - volumes: - - compass-data:/app/data environment: PORT: 4001 DATA_DIR: /app/data + RUST_LOG: compass=info + volumes: + - compass_data:/app/data healthcheck: test: ["CMD", "curl", "-f", "http://localhost:4001/health"] interval: 10s timeout: 5s - retries: 3 + retries: 5 + start_period: 10s + + # Optional: HuggingFace Text Embeddings Inference for GPU-accelerated embedding + tei: + image: ghcr.io/huggingface/text-embeddings-inference:latest + container_name: tei + ports: + - "8080:80" + environment: + - MODEL_ID=microsoft/harrier-oss-v1-0.6b + volumes: + - hf_cache:/data + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: 1 + capabilities: [gpu] + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:80/health"] + interval: 10s + timeout: 5s + retries: 5 volumes: - compass-data: + compass_data: + hf_cache: diff --git a/docs/compass-logo.svg b/docs/compass-logo.svg new file mode 100644 index 0000000..60d7104 --- /dev/null +++ b/docs/compass-logo.svg @@ -0,0 +1,57 @@ + +image/svg+xml \ No newline at end of file From 3bc57b3dc79cc68d6b56433c937fe22af99959c2 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 8 May 2026 13:06:00 -0700 Subject: [PATCH 2/2] chore: add open-source readiness files and branding - Add CODE_OF_CONDUCT.md (Contributor Covenant v2.1) - Add SECURITY.md with vulnerability disclosure policy - Update CONTRIBUTING.md: fix security contact to founders@runcaptain.com - Update Cargo.toml: authors field to founders@runcaptain.com - Add .github/ISSUE_TEMPLATE/bug_report.md - Add .github/ISSUE_TEMPLATE/feature_request.md - Add .github/PULL_REQUEST_TEMPLATE.md - Add .github/FUNDING.yml for GitHub Sponsors - Add .github/CODEOWNERS for code review assignments (lewis, edgar) - Add .github/workflows/release.yml for automated releases - Add docker-compose.yml for local development - Add docs/compass-logo.svg - Update README.md with Captain wordmark logo and improved header branding Co-Authored-By: Claude Opus 4.6 (1M context) --- CONTRIBUTING.md | 2 +- Cargo.toml | 2 +- README.md | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1d318d..253ef23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,7 +75,7 @@ Open an issue with: ## Reporting security issues -Don't open a public issue. Email `security@runcaptain.com` with the details. We'll acknowledge within two business days. +Don't open a public issue. Email `founders@runcaptain.com` with the details. We'll acknowledge within two business days. ## Code of conduct diff --git a/Cargo.toml b/Cargo.toml index 2ef21a8..3892abe 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,7 +10,7 @@ default-members = ["crates/compass"] [workspace.package] version = "0.2.0" edition = "2021" -authors = ["Captain Technologies "] +authors = ["Captain Technologies "] repository = "https://github.com/runcaptain/compass" homepage = "https://runcaptain.com" rust-version = "1.88" diff --git a/README.md b/README.md index 9b0becc..85fa486 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,8 @@
+ + Captain + +

Compass

Compass

Embedded vector + full-text search engine. Single binary, zero external dependencies.