Installation

Choose your installation path based on how you want to use the cyber.trackr.live API:

🎯 For API Consumers (Ruby Client)

Prerequisites

• Ruby 3.2+ (check our .ruby-version)
• No additional dependencies (pure Ruby using Faraday/Net::HTTP)

Install the Gem

Option 1: Direct installation

gem install cyber_trackr_live

Option 2: Add to Gemfile

gem 'cyber_trackr_live'

Then run:

bundle install

Verify Installation

require 'cyber_trackr_live'
helper = CyberTrackrHelper.new
puts "✅ Installation successful!"

Ready to start? See the Ruby Client guide for complete examples and workflows, or head to Quick Start to make your first API calls!

🔧 For Developers (Project Contributors)

Prerequisites

• Ruby 3.2+
• Node.js 22+ (for documentation and OpenAPI validation)
• Git

Clone and Setup

# Clone the repository
git clone https://github.com/mitre/cyber-trackr-live.git
cd cyber-trackr-live

# Install Ruby dependencies
bundle install

# Install Node.js dependencies (for docs)
npm install

# Verify setup
bundle exec rake test
npm run docs:validate

Development Workflow

Development Commands

# OpenAPI validation
npm run docs:validate              # Spectral OpenAPI linting
npm run docs:validate-mermaid      # Mermaid diagram validation
npm run docs:validate-all          # Both validations

# Ruby testing  
bundle exec rake test              # Core gem tests
bundle exec rake test:live         # Live API integration tests

# Documentation
npm run docs:dev                   # Start VitePress dev server
npm run docs:build                 # Build static documentation

# Client generation
./scripts/generate_client.sh       # Regenerate Ruby client from OpenAPI

Next: See the Testing Guide to understand our two-tier testing approach.

📚 Documentation Only

No installation required! Use our interactive documentation:

• API Reference - Try all endpoints directly in your browser
• OpenAPI Specification - Download the raw OpenAPI 3.1.1 spec

Generate Your Own Client

Use our OpenAPI specification to generate clients in any language:

# TypeScript/JavaScript
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/mitre/cyber-trackr-live/main/openapi/openapi.yaml \
  -g typescript-fetch \
  -o ./cyber-trackr-client

# Python
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/mitre/cyber-trackr-live/main/openapi/openapi.yaml \
  -g python \
  -o ./cyber-trackr-client

# Go  
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/mitre/cyber-trackr-live/main/openapi/openapi.yaml \
  -g go \
  -o ./cyber-trackr-client

Platform Support

✅ Fully Supported Platforms

Platform	Ruby Versions	CI/CD Status
Ubuntu Linux	3.2, 3.3, 3.4	✅ All tests pass
Windows	3.2, 3.3, 3.4	✅ All tests pass
macOS	3.2, 3.3, 3.4	✅ All tests pass

Why Cross-Platform Works

Our Faraday migration eliminated Windows compatibility issues by using pure Ruby dependencies instead of native libraries.

Troubleshooting

Ruby Version Issues

# Check your Ruby version
ruby --version

# Install Ruby 3.2+ using rbenv (recommended)
rbenv install 3.2.8
rbenv global 3.2.8

# Or using RVM
rvm install 3.2.8
rvm use 3.2.8 --default

Bundle Install Failures

# Clear bundle cache and retry
bundle clean --force
bundle install

# Check for platform-specific issues
bundle lock --add-platform ruby
bundle lock --add-platform x86_64-linux
bundle lock --add-platform x64-mingw32
bundle lock --add-platform arm64-darwin

API Connection Issues

# Test API connectivity
require 'net/http'
require 'json'

uri = URI('https://cyber.trackr.live/api/stig')
response = Net::HTTP.get_response(uri)

if response.code == '200'
  puts "✅ API is accessible"
  data = JSON.parse(response.body)
  puts "📋 Found #{data.size} documents"
else
  puts "❌ API connection failed: #{response.code}"
end

Next Steps

• API Consumer: Continue to Quick Start
• Developer: Review Testing Guide
• Documentation: Explore API Reference
• Architecture: Learn about Development Patterns