Skip to main content

Frequently Asked Questions (FAQ)

General Questions​

What is Rippler?​

Rippler is a comprehensive PR impact analysis tool for microservice-based systems. It performs automated impact analysis on code changes and notifies stakeholders of potential downstream effects across your microservices architecture.

Who should use Rippler?​

  • Engineering teams working with microservices architectures
  • Organizations wanting to understand the impact of code changes
  • Teams looking to improve code review processes with AI-powered insights

What languages/frameworks does Rippler support?​

Rippler's services are built with:

  • Backend Services: Java (Spring Boot), Python (FastAPI)
  • Frontend: Next.js (React/TypeScript)
  • AI/ML: Integration with OpenAI, Anthropic, and local Ollama models

Rippler can analyze code changes in repositories using any programming language, as the analysis is based on Git diffs and LLM-powered insights.

Setup & Configuration​

How do I set up Rippler?​

  1. Clone the repository with submodules: git clone --recurse-submodules https://github.com/Citi-Rippler/rippler.git
  2. Configure your environment: cp .env.example .env and edit with your API keys
  3. Start services: make up or docker-compose up
  4. Access the UI at http://localhost:18000

See the Docker Setup Guide for detailed instructions.

What environment variables do I need to configure?​

Required configuration in .env:

  • GITHUB_TOKEN - For GitHub API access and webhook verification
  • OPENAI_API_KEY or ANTHROPIC_API_KEY - For LLM-powered analysis (or use local Ollama)
  • DATABASE_URL - PostgreSQL connection string
  • REDIS_URL - Redis connection string

See the Getting Started Guide for complete configuration details.

Rippler Usage​

How does Rippler analyze pull requests?​

When a PR is opened in a monitored repository:

  1. GitHub sends a webhook to Rippler's API Gateway
  2. The Launchpad service processes the webhook and extracts PR information
  3. The Dependency Graph Engine identifies affected services
  4. The LLM Service provides AI-powered impact analysis
  5. Results are posted back to the GitHub PR as comments
  6. Stakeholders are notified of potential impacts

How do I configure which repositories Rippler monitors?​

Configure monitored repositories in the Rippler UI or via the API Gateway. You'll need to:

  1. Add the repository to Rippler's database
  2. Configure a GitHub webhook pointing to your Rippler instance
  3. Set up proper authentication tokens

Security​

How are security vulnerabilities detected?​

Multiple layers:

  1. CodeQL: Static analysis of source code
  2. Dependabot: Scans dependencies for known vulnerabilities
  3. Secret scanning: Detects committed secrets

How do I respond to a security alert?​

  1. Review the alert details
  2. Assess the impact
  3. Update the vulnerable dependency
  4. Test thoroughly
  5. Deploy the fix

What should I do if I accidentally commit a secret?​

  1. Immediately revoke/rotate the compromised secret
  2. Remove it from Git history using git filter-branch or BFG
  3. Force push the cleaned history (coordinate with team)
  4. Update the secret in all environments

How often should I update dependencies?​

  • Security updates: Immediately
  • Minor updates: Weekly (automated by Dependabot)
  • Major updates: Monthly or quarterly (requires testing)

Docker​

How are Rippler services containerized?​

All Rippler services are containerized using Docker:

  • Each service has its own Dockerfile
  • Services are orchestrated using Docker Compose
  • Images can be built locally or pulled from container registry

How do I rebuild a specific service?​

# Rebuild and restart a specific service
docker-compose up -d --build launchpad

# Or using Make
make rebuild SERVICE=launchpad

Where can I find service logs?​

# View logs for all services
docker-compose logs -f

# View logs for a specific service
docker-compose logs -f launchpad

Troubleshooting​

Rippler services are not starting​

Common causes:

  1. Port conflicts (check if ports 18000-18010, 5432, 6379 are available)
  2. Missing environment variables in .env
  3. Docker daemon not running

Solution: Check logs with docker-compose logs and verify your configuration.

GitHub webhooks are not being received​

Common causes:

  1. Webhook URL is incorrect or not accessible
  2. Webhook secret mismatch
  3. Firewall blocking incoming requests

Solution: Verify webhook configuration in GitHub repository settings and check API Gateway logs.

LLM Service is not responding​

Common causes:

  1. Missing or invalid API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY)
  2. Rate limiting from LLM provider
  3. Network connectivity issues

Solution: Check LLM service logs and verify API key configuration.

Database connection errors​

Common causes:

  1. PostgreSQL container not running
  2. Incorrect DATABASE_URL in .env
  3. Database not initialized

Solution: Run docker-compose up -d postgres and check connection string.

Contributing​

Best Practices​

How should I configure my microservices for Rippler?​

  • Ensure each service has clear ownership and boundaries
  • Document service dependencies explicitly
  • Use semantic versioning for service releases
  • Tag PRs with service identifiers for better tracking
  • Keep service documentation up to date

How can I improve the accuracy of impact analysis?​

  • Provide detailed PR descriptions
  • Use conventional commit messages
  • Maintain accurate service dependency mappings
  • Configure custom analysis rules if needed
  • Review and update the dependency graph regularly

Contributing​

How do I contribute to Rippler?​

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a PR with clear description

See Contribution Guide for detailed instructions.

What makes a good contribution?​

  • Solves a real problem or adds valuable features
  • Well documented with clear code comments
  • Includes tests where applicable
  • Follows existing code patterns and architecture
  • Doesn't introduce security vulnerabilities

Getting Help​

Where can I get help?​

  1. Check this FAQ
  2. Review the Documentation
  3. Search existing issues
  4. Open a new issue with the question label
  5. Check the Architecture Overview for system understanding

How do I report a bug?​

Open an issue on GitHub and include:

  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Docker version, etc.)
  • Relevant logs or screenshots

How do I request a feature?​

Open an issue on GitHub and explain:

  • The problem it solves
  • Proposed solution
  • Use cases and benefits
  • Any alternative approaches considered

Can't find your question? Open an issue with the question label.