<h1 align="center"> <a href="https://preevy.dev" target="_blank" rel="noopener noreferrer"> <picture> <source media="(prefers-color-scheme: dark)" srcset="site/static/img/logo-dark.svg"> <img width="80" src="site/static/img/logo-light.svg"> </picture> </a> <br /> Preevy </h1> <p align="center"> <em>Provision preview environments with minimal configuration</em> <span>&#8226;</span> <b>made by <a href="https://livecycle.io/">Livecycle</a></b> </p> <div align="center">

</div> <br />

We recently launched the Livecycle Docker Extension. Now you can share local environments instantly. Get feedback while your code is still in flight. Check it out here

https://github.com/Pradumnasaraf/preevy/assets/51878265/a699a356-f524-48fc-9b6d-49f2e42e7ec7

<!--lint disable no-multiple-toplevel-headings-->

Preevy

Preevy is a Command Line Interface (CLI) tool designed to simplify the process of creating ephemeral preview environments from Dockerized applications. Integrate Preevy into your CI flow to deploy Pull Requests as preview environments, using your existing cloud provider or Kubernetes cluster.

Preevy makes use of affordable VMs from AWS Lightsail, Google Cloud, Microsoft Azure, or any Kubernetes cluster.

Preevy can deploy your app with public or protected access, on the public internet or inside your existing private network.

Deploying a preview environment per Pull Request offers a range of benefits:

• 🌍 Universal Access: Just by sharing a URL, you can allow anyone to try your product revision on any device.

• 📩 Effortless Asynchronous Updates: Keep non-technical stakeholders in the loop without coordinating synchronous meetings.

• 🎨 Hassle-free Design Reviews: Designers can verify implementation independently, minimizing interruptions.

• 🚀 Parallel E2E Tests: Use external test agents against preview environments to expedite the testing process.

• 💡 Streamlined Feedback Cycle: Preview environments let your team engage with and feedback on new features early in the pipeline.

• 🧪 Non-production Experimentation: Develop and share unique versions of your product for presentations, examples, or tests.

• 🔐 Secure Collaboration: Generate private sandboxes to share with external stakeholders, ensuring secure collaborative efforts.

Visit The full documentation here: https://preevy.dev/

<!-- omit from toc -->

Contents

<!--lint disable double-link-->

• What
• Why
• Getting started
  • Prerequisites
  • Install the Preevy CLI
  • Set up a profile
  • Deploy your first environment
  • Update your environment
  • List and remove your environment
• Service URLs
• Under the hood
  • CLI
  • Tunnel server
• CI Integration
  • Faster builds in CI
  • Example repos
• Security
  • Private environments
  • Exposure of preview environments
  • Livecycle access to data
  • Network isolation
• Configuration
  • Preevy Profile
  • Compose files
  • x-preevy: Preevy-specific configuration in the Compose file(s)
• Plugins
  • Default plugins
  • Enabling or disabling plugins
• Docs and support
• Telemetry

<!--lint enable double-link-->

What

Preevy can take any Docker-Compose application definition and with a single up command perform the following:

• Provision and configure a virtual machine (VM) on your cloud, or a Pod on your Kubernetes cluster.
• Build your application on the VM/Pod or on any BuildKit builder (optional)
• Deploy your application on the VM/Pod.
• Expose each service of your application to the web with a user-friendly public HTTPS URL without any DNS/Certificate configuration.

These environments can be managed using the Preevy command-line interface (CLI) and can be easily updated or destroyed when necessary. While Preevy can be used for sharing local environments with your team, its primary goal is to implement preview environments for pull requests. Therefore, it's designed to be easily integrated into CI/CD flows.

Why

At Livecycle, we believe that preview environments are an integral part of any development flow, in any engineering team. These non-production, ephemeral environments, created for every Pull Request, can significantly improve PR workflows. In recent years, preview environments have become increasingly popular, with some PaaS providers even offering deeply integrated preview environments. However, setting up preview environments can be a complex and costly task, which is why many teams have been hesitant to implement them. Preevy is designed to simplify this task and provide a framework for provisioning and utilizing preview environments to optimize the PR flow. You can read more about the story and philosophy behind Preevy here.

Getting started

Prerequisites

Required software

• Node.js v18 or greater on Mac, Linux or Windows.
• Docker CLI with the default Docker Compose and BuildX plug ins. The Docker CLI is included with the Docker Engine installation and can also be installed separately.
• To use Kubernetes as a deploy runtime: kubectl.

Your Docker Compose app

If you don't have an existing Docker Compose app, check out Awesome Compose - a curated list of Compose samples, from React to Minecraft.

Your cloud provider or Kubernetes cluster

<!--lint disable double-link-->

Preevy deploys your app to one of the supported deploy runtimes.

<!--lint enable double-link-->

Choose the cloud provider or Kubernetes cluster you're going to use and configure access credentials for it:

• For AWS: use aws configure. See AWS lightsail credentials configurations.
• For GCP: use gcloud auth application-default login. See GCP credentials configuration
• For Azure: use az login. See Azure credentials configuration
• For Kubernetes: See Kubernetes credentials configuration

Note Preevy only uses your credentials when you run the Preevy CLI to set up and connect to your environments. Your credentials are not sent or stored anywhere outside of your computer.

Local Kubernetes server using Docker Desktop

If you don't have an existing cloud account or prefer to try Preevy first locally, you can use the Docker Desktop Kubernetes server. Go to: Docker Settings -> Kubernetes -> Enable Kubernetes.

Install the Preevy CLI

npm install -g preevy

Or use npx to run the CLI without installing it:

npx preevy <command>

Set up a profile

preevy init

Preevy will ask you to select a deploy target and a storage location for your profile. You can start by storing the profile locally.

Deploy your first environment

From the same directory where your docker-compose.yml or compose.yml file is located, run the command below:

preevy up

Note: Preevy uses the git repo at the current directory to calculate a stable environment ID for your project. Make sure a git repo is initialized (with at least one commit), or add the --id flag to explicitly specify the environment ID.

Access and share your new preview environment at the *.livecycle.run links provided in the command output.

Update your environment

Code changed? Re-run preevy up to quickly sync the preview environment with your changes on the existing VM or Kubernetes Pod.

List and remove your environment

Run preevy ls to show all environments in your deploy target which are linked to your profile.

Run preevy down to remove your environment. Preevy will delete the VM or Kubernetes Pod.

Service URLs

Every Compose service is exposed individually with a generated URL in the following format: https://{service}-{[port]}-{env-id}-{client-id}.{tunnel-server-domain}. If the service exposes a single port, the port part is omitted. See here for a more detailed explanation.

<!--lint disable awesome-list-item-->

• env-id is automatically generated from the Compose project and Git branch, or can be explicitly specified using the --id flag of the preevy up command.
• `client-id