Skip to content

Latest commit

 

History

History
277 lines (204 loc) · 10.2 KB

README.md

File metadata and controls

277 lines (204 loc) · 10.2 KB

Raybeam Documentation

Welcome to the Raybeam documentation! This directory contains comprehensive guides for using, deploying, and developing Raybeam.

Quick Navigation

For Users

  • API Reference - Complete REST API documentation with examples
    • Endpoint specifications
    • Authentication and authorization
    • Request/response formats
    • Common workflows

For Operators

  • Deployment Guide - Deploy Raybeam in any environment

    • Docker and Docker Compose
    • Kubernetes deployment
    • Binary installation with systemd
    • Backup and recovery
    • Monitoring and troubleshooting

  • Security Documentation - Security model and best practices

    • LDAP authentication and authorization
    • Threat model and mitigations
    • Compliance considerations (GDPR, SOC 2)
    • Security hardening checklist

For Developers

  • Development Guide - Contributing to Raybeam

    • Development environment setup
    • Project structure
    • Coding standards
    • Testing practices
    • Pull request process

  • Architecture Documentation - System design and internals

    • Component architecture
    • Request flows
    • Data model
    • Technology stack justification
    • Scalability considerations

Getting Started

Quick Start

  1. Deploy Raybeam:

    docker run -d \
  -p 8080:8080 \
  -v /var/lib/raybeam:/db \
  ghcr.io/netresearch/raybeam:latest \
  raybeam serve \
    -s ldap://ldap.example.com \
    -b "DC=example,DC=com" \
    -u "readonly" \
    -p "password" \
    -g "CN=Admins,DC=example,DC=com"

  2. Upload your SSH key:

    curl -u username:password -T ~/.ssh/id_rsa.pub \
  http://localhost:8080/users/@me/ssh-keys

  3. Retrieve keys:

    curl http://localhost:8080/users/username/ssh-keys

For detailed deployment instructions, see the Deployment Guide.

Documentation Structure

docs/
├── README.md           # This file - documentation index
├── api.md              # REST API reference
├── architecture.md     # System design and architecture
├── security.md         # Security model and best practices
├── deployment.md       # Deployment and operations guide
└── development.md      # Development workflow and contributing

Common Tasks

API Usage

Deployment

Security

Development

Key Concepts

Authentication & Authorization

Raybeam uses LDAP-based authentication with role-based access control:

  • Public: Read-only access to SSH keys (no auth required)
  • User: Self-service key management via LDAP credentials
  • Admin: Manage keys for any user via LDAP group membership

See Security Documentation for details.

Data Storage

Raybeam uses BoltDB for embedded key-value storage:

  • Single file database (db.bolt)
  • ACID transactions
  • SSH keys stored per user (LDAP DN as key)
  • No external database required

See Architecture Documentation for details.

API Design

Raybeam provides a REST API with dual response formats:

  • text/plain (default): SSH authorized_keys format for direct use
  • application/json: Structured responses for programmatic access

See API Reference for details.

Troubleshooting

Common Issues

  1. Authentication Failures

  2. Admin Authorization Issues

  3. Database Errors

For more troubleshooting guidance, see:

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    HTTP Client                           │
│               (curl, scripts, apps)                      │
└────────────────┬────────────────────────────────────────┘
                 │ HTTP Basic Auth
                 ▼
┌─────────────────────────────────────────────────────────┐
│                  Raybeam Server                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Logger → Auth Middleware → Route Handlers       │  │
│  └──────────────────────────────────────────────────┘  │
└─────────┬─────────────────────────────┬─────────────────┘
          │                             │
          ▼                             ▼
  ┌───────────────┐              ┌─────────────┐
  │  LDAP Server  │              │   BoltDB    │
  │  (Auth)       │              │  (Storage)  │
  └───────────────┘              └─────────────┘

For detailed architecture information, see Architecture Documentation.

Security Considerations

Production Deployment Requirements:

  • ✅ Deploy behind HTTPS/TLS reverse proxy
  • ✅ Use ldaps:// for LDAP connections
  • ✅ Configure rate limiting
  • ✅ Enable access logging and monitoring
  • ✅ Implement encrypted backups
  • ✅ Restrict file permissions (BoltDB: 0600)
  • ✅ Follow principle of least privilege for LDAP service account

For comprehensive security guidance, see Security Documentation.

Performance Characteristics

Expected Performance:

  • Read operations: <5ms (BoltDB)
  • Write operations: <10ms (BoltDB)
  • LDAP authentication: 50-200ms (network dependent)
  • Total request time: 100-300ms for authenticated writes

Scalability:

  • Single-writer limitation (BoltDB)
  • Suitable for <10K operations/second
  • Vertical scaling recommended
  • Read replicas possible with file replication

For performance details, see Architecture Documentation.

Contributing

Contributions are welcome! Please read the Development Guide before submitting pull requests.

Quick Start for Contributors:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make changes with tests
  4. Run tests: go test ./...
  5. Commit with conventional commit format
  6. Submit pull request

See Development Guide → Contributing for detailed guidelines.

Resources

External Documentation

Project Links

License

Raybeam is released under the MIT License. See LICENSE for details.

Support

Need help? Start with the API Reference or Deployment Guide, or open a discussion.