DOCSEARCHbyAlgolia
Submit Docs

Preevy Documentation

repository·main·Indexed 25 days ago

https://github.com/livecycle/preevy

A CLI tool for creating ephemeral preview environments for Dockerized applications. Preevy enables developers to deploy Pull Requests as live environments on AWS, GCP, Azure, or Kubernetes clusters. It includes a GitHub integration plugin (@preevy/plugin-github) for automatic PR commenting and build cache support, and allows configuration via the x-preevy Docker Compose element.

Tokens
69.3K
Snippets
97
Records
367
Agent score
79%

What's inside Preevy

  1. What is Preevy?

    main
    Preevy is an open-source tool designed to provision, manage, and expose ephemeral preview environments for containerized applications (specifically Docker Compose applications) in the cloud. It is intended to be integrated into pull/merge request workflows to provide inexpensive, customizable, and accessible environments for both technical and non-technical users without requiring deep DevOps knowledge.

  2. Use the GitHub integration plugin

    main

    The @preevy/plugin-github plugin provides GitHub integration for Preevy, allowing it to automatically post or update comments on Pull Requests with environment URLs.

    Automatic PR Comments

    When running preevy up or preevy down in a supported CI environment (like GitHub Actions) where a GITHUB_TOKEN and PR context are detected, Preevy will automatically post a comment to the PR containing the service URLs. When the environment is destroyed, it updates the comment to indicate deletion.

    Manual PR Comments

    You can manually manage PR comments using the following commands:

    • preevy github pr comment: Creates or updates a comment for an existing environment with current URLs.
    • preevy github pr uncomment: Updates the comment to state the environment has been deleted.

  3. Understand the Livecycle Docker Extension features

    main

    The Livecycle Docker Extension is a tool integrated with Docker that provides several features for sharing and managing development environments:

    • Docker Integration: Provides a smoother experience for Docker users compared to generic tunneling tools.
    • Consistent URLs & Private Environments: Supports stable URLs and the ability to restrict access via private URLs.
    • Authentication: Supports Google and GitHub authentication out of the box.
    • Debugging Capabilities: The Livecycle dashboard allows for log inspection, shell access, and container inspection.
    • Preevy CLI Integration: Allows you to create remote ephemeral preview environments for Pull Requests (useful when your local machine is offline or within a CI pipeline).
    • Security: Uses a secure SSH tunnel to expose local environments via Livecycle's tunnel server, which is only accessible via HTTPS.
    • Language Agnostic: Works with any framework or language that can run inside a Docker container.

  4. Preevy System Components

    main

    CLI

    A Node.js program that manages the environment lifecycle. It handles:

    • Provisioning/tearing down VMs.
    • Managing profile data.
    • Setting up Docker tooling on VMs.
    • Syncing Compose source and volumes.
    • Running the application and the tunneling daemon.

    Tunnel Server

    A Node.js-based server that exposes friendly HTTPS URLs for your Compose services.

    • Public Instance: Hosted at livecycle.run.
    • Self-hosted: Can be deployed via Kubernetes.

  5. Use the Livecycle Dashboard to review ephemeral environments

    main

    The Livecycle Dashboard is used to manage and share ephemeral environments created by Preevy. It allows you to:

    • Share code changes: Invite teammates to specific ephemeral environments to review latest changes.
    • Collect feedback: Enable team members to provide feedback in context.
    • Manage projects: Team members can view open projects assigned to them and review changes directly in their browser.

  6. What is the Livecycle Dashboard?

    main

    The Livecycle Dashboard is a web application providing a graphical user interface (GUI) for managing Livecycle environments. It includes features for team collaboration and environment management, such as:

    • Remote Access: Remote terminal access and remote log access.
    • Inspection: Container inspection capabilities.
    • Collaboration: Integrated chat and pointing tools to facilitate teamwork.

  8. How Preevy provisions preview environments

    main

    When you run the preevy up command, Preevy automates the following lifecycle to create a preview environment:

    1. Configuration Loading: Reads Compose files, tunneling keys, and default flags from your profile. It calculates an environment ID (usually based on the current git branch or a provided --id flag).
    2. Target Provisioning: Queries your configured cloud provider (Azure, GCE, etc.) or Kubernetes cluster. If a deployment target (VM or Pod) doesn't exist, Preevy provisions a new one.
    3. Tunnel Setup: Establishes an SSH tunnel to the Docker server on the target machine.
    4. Build Process: Generates an interim build Compose file and runs docker buildx bake. Images are then loaded to the target machine or an image registry.
    5. Deployment: Executes docker compose up on the remote machine. Local volume mounts are synced to the remote machine first.
    6. Proxy Injection: Augments your project with a preevy_proxy helper service that connects to the Tunnel Server.
    7. URL Generation: The preevy_proxy creates tunnels for each service, and Preevy fetches and prints the resulting public HTTPS URLs.

  9. Use the Livecycle Dashboard for collaboration

    main

    The Livecycle Dashboard is a web-based interface accessible via a browser when logged into a Livecycle account. It is used to:

    • Invite teammates to existing preview environments for review and feedback.
    • View open projects assigned to team members.
    • Review the latest changes directly in the browser.

  10. Manage Preevy plugins

    main

    Plugins extend Preevy via NPM packages and can add hooks, commands, or flags. The @preevy/plugin-github plugin is enabled by default.

    Enabling/Disabling Plugins

    1. Via Compose file: Add a plugins section to x-preevy.
    2. Via Environment Variables: Use PREEVY_ENABLE_PLUGINS or PREEVY_DISABLE_PLUGINS with a comma-separated list of package names.
    3. Via CLI Flags: Use --enable-plugin=<module> or --disable-plugin=<module>. CLI flags have the highest priority.
    x-preevy:
  plugins:
    - module: '@preevy/plugin-github'
      disabled: false # optional, set to true to disable