Preevy

Provision preview environments with minimal configuration • made by Livecycle

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

Preevy-demo.mp4

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/

Contents

• What
• Why
• Getting started
• Under the hood
  • CLI
  • Tunnel server
• CI Integration
  • Faster builds in CI
• Security
  • Private environments
  • Notice on preview environments exposure
  • 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

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 and 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

To start using the Preevy CLI you will need:

• Docker for desktop/Docker CLI
• Node 18
• A Docker-Compose application (examples can be found here)
• A cloud provider for provisioning VMs (AWS/GCP/Azure), or a Kubernetes cluster (local, remote or managed)

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 and follow the instructions below.

For provisioning a VM, configure your provider:

• In AWS, it could be done by using aws configure
• In GCP, it could be done by using gcloud auth application-default login
• In Azure, it could be done by using az login

For provisioning a Pod on Kubernetes, make sure a kubeconfig file exists and that you can run kubectl commands locally (e.g. kubectl get pod)

Running Preevy:

1. Install the CLI using npm:npm install -g preevy , or use it directly using: npx preevy <command>
2. Set up a profile by using: preevy init
3. Use the preevy up command to provision a new VM with your application.
4. Access and share your new preview environment at the *.livecycle.run link provided in the command output.
5. Code changed? Re-run preevy up to quickly sync the preview environment with your changes on the existing VM.
6. Remove the environment by using: preevy down.

Under the hood

Preevy has two main components:

CLI

The CLI is a Node.js program responsible for:

• Provisioning and tearing down VMs.
• Exposing environments' state and URLs to the end user.
• Storing and accessing profile data (settings, keys, etc).
• Setting up a VM with Docker tooling.
• Syncing Compose source code and local volumes.
• Running the Compose app, augmented with a daemon for connecting to the tunneling service.

Tunnel server

The tunnel server is a Node.js base server responsible for exposing friendly HTTPS URLs for the Compose services.

A free public instance is hosted on livecycle.run, and it can be self-hosted as well.

A Docker/OCI image is available on ghcr.io: ghcr.io/livecycle/preevy/tunnel-server

CI Integration

Preevy is designed to work seamlessly with your CI, allowing you to easily import a shared preview profile in AWS S3 and Google Cloud Storage (GCS).

Profiles are created using preevy init. Choose a S3/GCS URL for storing the profile - Preevy will create a bucket if one doesn't exist.

If you already have a locally stored Preevy Profile, it can be migrated to remote storage using preevy profile cp

Once the profile is created, it can be imported to the CI runtime using preevy init --from <profile-url>

Examples

Faster builds in CI

Check out our documentation to find out how to speed up your builds and reduce the costs of your preview environments by running Preevy with BuildKit Builders in CI.

Security

In case you find a security issue or have something you would like to discuss, refer to our security policy.

Private environments

Preevy can add an authentication layer to your provisioned environments. When you configure your service as private the Tunnel Server restricts access based on a pre-shared secret or a Livecycle login (SSO via Google/Microsoft/GitHub).

Notice on preview environments exposure

Services on provisioned environments are not exposed directly, but rather via a tunnel created by the tunneling server.

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.

• env-id can be specified using the --id flag of the preevy up command, or automatically generated by git context.
• client-id is a random identifier based on the profile's public tunneling SSH key (generated in preevy init).
• tunnel-service-domain is where the tunnel service is hosted. It can be specified using the --tunnel-url flag of the preevy up command, and defaults to our free service at *.livecycle.run.

Network isolation

The Tunnel Server can be deployed on your private network (e.g. VPC), which access to your environments at the network level.

Configuration

Preevy loads its configuration from the following sources, in order:

• The Preevy Profile
• Compose files (Preevy-specific, then project)
• Command-line arguments

Preevy Profile

The Preevy profile is created by the init command and can be stored locally or remotely on your cloud provider. A profile is required to create environments. The profile includes the following:

• A tunneling key, that is used to identify your services when connecting to the Tunnel Server.
• The default driver to use for provisioning environments.
• Default driver options to use per driver (e.g. AWS region, K8s namespace).
• Driver state whose contents depend on the specific driver.

Profiles can be migrated to a different storage location using preevy profile cp.

The default profile can be overridden using the global command line argument --profile.

_{^{Note: The profile currently combines context and state, and some changes are planned.}}

Compose files

Preevy extracts its runtime settings from the Compose file.

Project Compose files

Just like with the docker compose CLI, you can use the global --file | -f command line argument to specify the path(s) for the Compose file. If not specified, the default loading order is used. Multiple files are supported.

Preevy-specific Compose file

In addition to the project compose files, an optional Preevy-specific Compose file can be used. Preevy attempts to load files named compose.preevy.yaml, compose.preevy.yml, docker-compose.preevy.yaml or docker-compose.preevy.yml. If one of these exists, it is loaded BEFORE the project composes file(s). The name of the Preevy-specific compose file can be overridden by specifying the argument --system-compose-file.

x-preevy: Preevy-specific configuration in the Compose file(s)

A x-preevy top-level element can be added to the Compose file(s).

services:
  ...
x-preevy:
  driver: lightsail
  drivers:
    lightsail:
      region: eu-central-1
    kube-pod:
      context: dev-cluster
  plugins:
    ...

The following properties are supported, all of them optional:

driver

Override the default driver to use for this Compose project. Available values: lightsail, gce, azure, kube-pod.

This value can be overridden per command execution using the --driver CLI flag.

drivers

Override the default options per driver for this Compose project. See the specific driver documentation.

These values can be overridden per command execution using the specific driver CLI flags, e.g. --lightsail-bundle-id=2xlarge_2_0

Example:

x-preevy:
  drivers:
    lightsail:
      bundle-id: large_2_0
    kube-pod:
      context: dev-cluster

plugins

See Plugins below.

Plugins

Plugins are a way to extend Preevy's functionality via externally-published NPM packages.

A plugin can add hooks that execute code in response to events. It can also define new commands, and add flags to existing commands to customize their behavior.

Default plugins

The GitHub integration plugin packaged as @preevy/plugin-github is bundled with Preevy and enabled by default.

Enabling or disabling plugins

From the Docker Compose file

Plugins can be configured in the Preevy configuration section of your Compose file. Add a plugins section to the x-preevy top-level element:

services:
  ...
x-preevy:
  plugins:
    - module: '@preevy/plugin-github'
      disabled: false # optional, set to true to disable plugin
      # ...additional plugin-specific configuration goes here

See the included GitHub integration plugin for a detailed example.

From the environment

Plugins can be enabled or disabled by setting the PREEVY_ENABLE_PLUGINS and PREEVY_DISABLE_PLUGINS environment variables to a comma-separated list of packages.

Example: To disable the default GitHub integration plugin, set PREEVY_DISABLE_PLUGINS=@preevy/plugin-github.

From the CLI flags

Specify the global --enable-plugin=<module> and --disable-plugin=<module> flags to enable or disable plugins per command execution. CLI flags take priority over the Docker Compose and environment configuration.

Docs and support

Read about Preevy's components and learn how to use them in our documentation.

Ask a question or join our Livecycle Community to get support.

Telemetry

The Preevy CLI collects telemetry data to help us understand product usage and direct future development.

The data collected is anonymous and cannot be used to uniquely identify a user. Access to the data is limited to Livecycle's employees and not shared with 3rd parties.

To see the collected data, set the environment variable PREEVY_TELEMETRY_FILE to a filename.

We appreciate the usage data sent to us as - it's the most basic and raw type of feedback we get from our users. However, if you are concerned about sending out data, you may choose to disable telemetry.

Telemetry collection can be disabled by setting the environment variable PREEVY_DISABLE_TELEMETRY to 1 or true.