From 133fc984404f9e589b7a61148ccde75b16a94c8e Mon Sep 17 00:00:00 2001 From: Sienna Meridian Satterwhite Date: Sat, 7 Mar 2026 14:54:29 +0000 Subject: [PATCH] docs: add comprehensive README with professional documentation --- README.md | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..51abff9 --- /dev/null +++ b/README.md @@ -0,0 +1,292 @@ +# Sunbeam CLI + +**Sunbeam CLI** is a powerful local development stack manager for Kubernetes-based applications. It simplifies cluster management, service operations, secret handling, and manifest deployment for development environments. + +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/) +[![Documentation](https://img.shields.io/badge/docs-comprehensive-brightgreen.svg)](docs/) + +## Quick Start + +```bash +# Install Sunbeam CLI +pip install . + +# Start your local cluster +sunbeam up + +# Apply manifests +sunbeam apply + +# Check status +sunbeam status +``` + +## Features + +- **Cluster Management**: Bring up and tear down local Kubernetes clusters with Lima VM +- **Service Operations**: Manage services, view logs, and perform health checks +- **Secret Management**: Secure credential handling with OpenBao integration +- **Manifest Management**: Kustomize-based manifest application with domain substitution +- **User Management**: Identity management for development environments +- **Tool Bundling**: Automatic download and management of required binaries +- **Multi-environment Support**: Local development and production deployment + +## Installation + +### Prerequisites + +- Python 3.11+ +- Docker +- Lima (for local VM management) +- kubectl, kustomize, helm (automatically managed by Sunbeam) + +### Install from Source + +```bash +# Clone the repository +git clone https://github.com/your-org/sunbeam.git +cd sunbeam/cli + +# Install dependencies +pip install . + +# Verify installation +sunbeam --help +``` + +### Install in Development Mode + +```bash +pip install -e . +``` + +## Usage + +### Basic Commands + +```bash +# Start local cluster +sunbeam up + +# Check cluster status +sunbeam status + +# Apply all manifests +sunbeam apply + +# Apply specific namespace +sunbeam apply lasuite + +# View service logs +sunbeam logs ory/kratos + +# Restart services +sunbeam restart ory/kratos + +# Stop cluster +sunbeam down +``` + +### Production Deployment + +```bash +# Set SSH host for production +export SUNBEAM_SSH_HOST=user@your-server.example.com + +# Apply production manifests +sunbeam apply --env production --domain sunbeam.pt --email ops@sunbeam.pt + +# Check production status +sunbeam status --env production +``` + +## Documentation + +Comprehensive documentation is available in the [`docs/`](docs/) directory: + +- **[CLI Reference](docs/cli-reference.md)** - Complete command reference +- **[Core Modules](docs/core-modules.md)** - Detailed module documentation +- **[API Reference](docs/api-reference.md)** - Full API documentation +- **[Usage Examples](docs/usage-examples.md)** - Practical usage patterns +- **[Utility Modules](docs/utility-modules.md)** - Helper function documentation + +## Configuration + +### Environment Variables + +| Variable | Description | Required | +|----------|-------------|----------| +| `SUNBEAM_SSH_HOST` | SSH host for production access | Production only | +| `SUNBEAM_ACME_EMAIL` | ACME email for cert-manager | Optional | + +### Configuration Files + +Sunbeam uses kustomize overlays for environment-specific configuration: + +``` +infrastructure/ +├── base/ # Base manifests +└── overlays/ # Environment overlays + ├── local/ # Local development + └── production/ # Production deployment +``` + +## Architecture + +```mermaid +graph TD + A[Sunbeam CLI] --> B[Kubernetes Interface] + A --> C[Manifest Management] + A --> D[Service Operations] + A --> E[Secret Management] + A --> F[User Management] + A --> G[Image Building] + A --> H[Tool Management] + + B --> B1[kubectl wrapper] + B --> B2[SSH tunnel management] + B --> B3[Domain discovery] + + C --> C1[Kustomize integration] + C --> C2[Webhook handling] + C --> C3[ConfigMap tracking] + + D --> D1[Health monitoring] + D --> D2[Log streaming] + D --> D3[Service restart] +``` + +## Development Workflow + +### Building and Deploying + +```bash +# Build a component +sunbeam build proxy + +# Build and push to registry +sunbeam build proxy --push + +# Build, push, and deploy +sunbeam build proxy --deploy +``` + +### User Management + +```bash +# Create user +sunbeam user create user@example.com --name "User Name" + +# Set password +sunbeam user set-password user@example.com "password123" + +# List users +sunbeam user list +``` + +### Secret Management + +```bash +# Seed all credentials +sunbeam seed + +# Verify VSO + OpenBao integration +sunbeam verify +``` + +## Contributing + +Contributions are welcome! Please follow these guidelines: + +1. **Fork the repository** and create your branch +2. **Follow conventional commits** for commit messages +3. **Add tests** for new features +4. **Update documentation** for changes +5. **Submit a pull request** + +### Development Setup + +```bash +# Clone repository +git clone https://github.com/your-org/sunbeam.git +cd sunbeam/cli + +# Install development dependencies +pip install -e .[dev] + +# Run tests +python -m pytest sunbeam/tests/ +``` + +### Commit Message Format + +``` +(): + + + +