Prevu

Prevu is a high-performance ephemeral environment orchestrator written in Rust. It automatically deploys application preview instances directly from Pull Requests into Docker, utilizing a built-in dynamic reverse proxy engine.

Key Features

• Zero-Dependency Proxy: An embedded engine powered by Pingora manages HTTP traffic without requiring external tools like Nginx or Caddy.
• Full Automation: Automated building, launching, and cleanup of containers once a Pull Request is closed.
• Security: Network isolation for containers and native TLS/SSL support via the ACME protocol.
• Efficiency: Extremely low resource footprint (minimal RAM usage) thanks to the Tokio asynchronous runtime.
• Seamless Integration: Support for GitHub and GitLab webhooks with HMAC signature verification.

Architecture

The project consists of two main components running within a single process:

1. Control Plane (Axum): An HTTP server that receives webhooks and controls the Docker Engine API via the Bollard library.
2. Data Plane (Pingora): A reverse proxy engine that dynamically routes traffic from subdomains to the respective containers.

Lifecycle Flow

graph TD
    classDef external fill:#4b5563,stroke:#1f2937,stroke-width:2px,color:#fff;
    classDef api fill:#1e3a8a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef docker fill:#065f46,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef proxy fill:#7c2d12,stroke:#f97316,stroke-width:2px,color:#fff;

    subgraph Git_Platforms ["Git Platforms"]
        GH[GitHub / GitLab]:::external
        Dev[Developer / Client]:::external
    end

    subgraph Prevu_Host ["Prevu Self-Hosted Instance"]
        subgraph prevu_api ["prevu-api (Axum HTTP Server)"]
            WH[Webhook Receiver]:::api
            TQ[Async Task Queue <br><i>tokio::sync::mpsc</i>]:::api
            GC[Git Client <br><i>Shallow Clone</i>]:::api
        end

        subgraph prevu_docker ["prevu-docker (Bollard Integration)"]
            DM[Docker Manager]:::docker
            DE[Docker Engine API]:::docker
        end

        subgraph prevu_proxy ["prevu-proxy (Pingora Reverse Proxy)"]
            PR[Pingora Core]:::proxy
            ACME[ACME Engine <br><i>Let's Encrypt</i>]:::proxy
            MR[In-Memory Routing Map <br><i>Arc &lt;RwLock &lt;HashMap&gt;&gt;</i>]:::proxy
            FA[Forward Auth Middleware]:::proxy
        end
    end

    subgraph Isolated_Network ["Isolated Docker Network (prevu_network)"]
        C1[Ephemeral Container: PR #123]:::docker
        C2[Ephemeral Container: PR #124]:::docker
    end

    GH -- "1. Trigger Event <br> (PR Opened/Updated)" --> WH
    WH -- "2. Validate Signature & Push Task" --> TQ
    TQ -- "3. Execute Worker" --> GC
    GC -- "4. Fetch .prevu.toml & Dockerfile" --> DM
    
    DM -- "5. Resource-Limited Build & Run" --> DE
    DE -- "6. Spawn Container in 'prevu_network'" --> C1
    
    DM -- "7. Register Route <br> (Subdomain -> Container IP:Port)" --> MR
    
    Dev -- "8. Access App <br> (pr-123.yourdomain.com)" --> PR
    PR --> ACME
    PR --> FA -- "9. Challenge / Verify Cookie" --> PR
    PR -- "10. Instant Lookup" --> MR
    PR -- "11. Route Proxy Traffic" --> C1

    GH -. "12 PR Closed Webhook" .-> WH
    WH -. "13 Deregister Route" .-> MR
    WH -. "14 Destroy Resource (--rm)" .-> DE
    DE -. "15 Wipe Container" .-> C1

Loading

Project Status

Note

Prevu is currently under active development. See the roadmap below for planned features.

Roadmap

• Workspace structure and modular layout
• Core library implementations (prevu-core)
• Docker orchestration (prevu-docker)
• Reverse proxy engine integration (prevu-proxy)
• GitHub webhook API endpoints (prevu-api)
• Application entry point (prevu binary)
• Docker integration and container lifecycle
• Webhook signature verification
• Preview URL routing logic
• Container cleanup on PR close
• Documentation and deployment guides

Contributing

This project is Open Source. To contribute:

1. Fork the repository.
2. Create a new branch for your feature.
3. Submit a Pull Request with a description of your changes.

License

Distributed under the Apache License 2.0. See the LICENSE file for details.