added few docs (livecycle#36)

* added few docs * Update site/docs/intro/under-the-hood.md Co-authored-by: Roy Razon <[email protected]> * Update site/docs/intro/under-the-hood.md Co-authored-by: Roy Razon <[email protected]> * Update site/docs/intro/under-the-hood.md Co-authored-by: Roy Razon <[email protected]> * CR Changes * fix * Update motivation.md * Update motivation.md * fix * more fixes * fix * fix * fix * update * Update site/docs/intro/under-the-hood.md Co-authored-by: Roy Razon <[email protected]> * more CR changes * fix oci image * added light sail configuration * fix * fix * another fix * added link to lightsail * cr changes --------- Co-authored-by: Roy Razon <[email protected]>
josegron · Mar 28, 2023 · fc79285 · fc79285
1 parent 3913488
commit fc79285
Show file tree

Hide file tree

Showing 7 changed files with 174 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -78,7 +78,7 @@ The CLI is a node.js program responsible for:
 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/preview/tunnel-server
+A Docker/OCI image is available on ghcr.io: ghcr.io/livecycle/preevy/tunnel-server
 
 ## CI Integration
 

diff --git a/site/docs/drivers/aws-lightsail.md b/site/docs/drivers/aws-lightsail.md
@@ -0,0 +1,67 @@
+---
+sidebar_position: 1
+title: AWS Lightsail
+---
+
+`preevy` can provision virtual machines on AWS Lightsail using the `aws-lightsail` driver.  
+[AWS lightsail](https://aws.amazon.com/lightsail) is a managed service that provides a simple low-cost solution for running VMs in the cloud.  
+AWS lightsail provisioning time for a VM is usually around 2 minutes and their cost can be as low as $3.50 per month making them suitable for preview environments at scale.
+
+
+### Supported flags
+- `--aws-region` - The AWS region to use.
+
+### Credentials Configuration
+`preevy` uses AWS SDK which supports multiple ways of configuring credentials  according to the [credentials provider chain](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html).  
+The simplest way is to use `aws configure` command or setting the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
+
+In Github actions, you can also use the [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) action to setup credentials in a secure way.
+
+### Required permissions
+
+`preevy` requires the following policy to be able to provision and manage Lightsail VMs:
+```
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "lightsail:*"
+ ],
+ "Resource": "*"
+ }
+ ]
+}
+```
+
+:::note
+When defining fine grained permissions for `preevy`, make sure to add s3 permissions as well when using s3  as profile store.  
+It's recommended to scope the permissions to a specific bucket and prefix if needed:
+```
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+  "Effect": "Allow",
+  "Action": [
+    "s3:HeadBucker",
+    "s3:GetBucketLocation",
+    "s3:ListObjects",
+    "s3:ListObjectsV2",
+    "s3:PutObject",
+    "s3:GetObject",
+    "s3:PutObjectTagging",
+    "s3:DeleteObjectTagging",
+    "s3:DeleteObject",
+    "s3:CreateBucket", //only if bucket doesn't exist
+  ],
+  "Resource": [
+    "arn:aws:s3:::MY_BUCKET",
+    "arn:aws:s3:::MY_BUCKET/*"
+  ]
+ }
+ ]
+}
+```
+:::
diff --git a/site/docs/intro/getting-started.mdx b/site/docs/intro/getting-started.mdx
@@ -17,6 +17,8 @@ title: Getting started
 Use `preevy` to provision your [docker-compose](https://docs.docker.com/compose/) application with minimal configurations, as simple as running `preevy up`.<br/>
 `preevy` will then output a public URL for every service in your configuration.
 
+You can read about the [origin and motivation for preevy](/intro/motivation).
+
 ## Getting Started
 
 Preevy is designed to be easy to use with an API smiliar to `docker compose`.

diff --git a/site/docs/intro/motivation.md b/site/docs/intro/motivation.md
@@ -0,0 +1,24 @@
+---
+sidebar_position: 2
+title: Motivation
+---
+
+Preevy was designed to help development teams improve their PR workflows by providing a simple and cost-effective way to provision ephemeral environments for every Pull Request. (AKA *Preview Environments*)
+
+Our mission at [Livecycle](https://livecycle.io) is to make the development flow more collaborative and free of back and forth communication.  
+We believe that preview environments serve an integral part for accomplishing our mission, and one of our earliest challenges as a startup was to make preview environments more accessible and affordable for all teams.
+
+To give more context, preview environments are ephemeral environments created for every Pull Request, and can be used to test, validate and review changes before merging them to the main branch.  
+To some essence, they are a non-production version of the application that can be accessed by anyone with a link that is automatically attached to every pull request.
+
+During our work, we've seen teams that implemented preview environments for frontend applications by leveraging the power of [Vercel](https://vercel.com/), [Netlify](https://www.netlify.com/) or even our [own solution](https://livecycle.io).
+
+Yet, when it comes to deploying preview environments for a complex application with multiple services, many teams struggle to find the right solution and juggle between the different tradeoffs (fidelity, security, cost, scale, etc...) and complexities, and usually end up with either postponing/giving-up or implementing a complex (and usually costly) solution that doesn't necessarily fit in their development flow.  
+To some degree, these challenges are risen from the inherit complexities and fragmentation presented in the configuration of production (or production-like) of enterprise applications. (e.g. Kubernetes configuration, IaC, scale, compliance/security, etc...)
+
+`preevy` lowers the bar for deploying preview environments, aiming for any developer with a minimal knowledge of Docker and a cloud provider account.
+
+In the tradeoff between fidelity and simplicity, we've chosen simplicity, and we believe that preview environments should be cheap, hackable, and accessible to everyone to provide the most value in development flows.
+
+We've originally planned `preevy` as a side-project allowing our customers to provision preview environments on their infrastructure.
+We've decided to open-source it as we are excited on the potential value that it can bring to the community and the possibility of establishing a ecosystem of standards, practices and tools around preview environments.
diff --git a/site/docs/intro/under-the-hood.md b/site/docs/intro/under-the-hood.md
@@ -2,5 +2,55 @@
 sidebar_position: 4
 title: Under the hood
 ---
+## Provisioning preview environments
 
-# Under the hood
+When provisioning a new environment using the `up` command, `preevy` does the following:
+- Reads for default configuration and relevant keys from the current profile store.
+- Calculates environment name based on git branch or uses the `--id` flag.
+- Uses the local aws configuration to provision a new Lightsail VM.
+- Reads SSH keypair from profile to access the VM, if necessary, generate a new one.
+- Connects to the VM using SSH and setup Docker.
+- Reads the compose file and copies local volume mounts to the VM.
+- Augments the compose deployment with a helper service, `tunnel-agent`, responsible for connecting to the [tunnel server](/tunnel-server/overview.md).
+- Runs the application using Docker Compose with `--build` while using the local build context.
+- The `tunnel-agent` is inspecting the network configuration of all deployed services and create a tunnel for each service.
+- Fetch the urls from tunnel-agent and output them to the end user.
+
+## Profile configuration
+
+`preevy` profile provide a mechanism for storing and sharing configuration and state between different machines. This allows sharing of environments between different CI jobs, or different developers.
+Using a shared profile ensure consistent configuration and stable URLs between different CI runs.
+
+The profile data can be stored on AWS s3 for easy sharing. If for some reason s3 cannot be used, the profile can also be stored on the local filesystem and copied manually.
+
+:::note
+Profile store doesn't contain any cloud provider credentials.  
+The `preevy` CLI always uses the local AWS credential chain (e.g, from environment variables, AWS profile, EC2 role), which needs to have the [appropriate permissions](/drivers/aws-lightsail).
+:::
+
+Profile URLs specify where the profile data is stored, for example: `s3://preevy-config/profile1?region=us-east-1` (refers to a profile stored on a S3 bucket named `preevy-config` in the region `us-east-1` under `profile1` path).
+
+This profile can be imported using `preevy init --from s3://preevy-config/profile1?region=us-east-1`
+All available profiles can be listed using `preevy profile ls` command.
+
+## Components
+
+#### [CLI](packages/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 & accessing profile data. (settings, keys, etc...)
+- Setting up a VM with Docker tooling.
+- Syncing Compose source code and local volumes.
+- Running the application and installing daemon for connecting to the tunneling service.
+
+For usage examples, you can go over the [CLI reference](/cli-reference.md)
+
+#### [Tunnel server](packages/tunnel-server)
+
+The tunnel server is a node.js based 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.
+
+Read more about it: [Tunnel server](/tunnel-server/overview.md)
diff --git a/site/docs/intro/why-preevy.md b/site/docs/intro/why-preevy.md
diff --git a/site/docs/tunnel-server/overview.md b/site/docs/tunnel-server/overview.md
@@ -0,0 +1,29 @@
+
+# Tunnel Server
+
+`preevy` uses a tunnel server to expose the preview environments services to the end user.
+By default, the CLI uses a public tunnel server hosted on `livecycle.run`, but this configuration can be override using the `--tunnel-server` flag.
+The tunnel server can be self hosted and a Docker/OCI image is publicly available on `ghcr.io/livecycle/preevy/tunnel-server`
+
+The tunnel server itself is a node.js server responsible for creating tunnels for http services using SSH.
+The server accept ssh connections in port 2222, http traffic on port 3000.
+Assuming the tunnel server is running on `tunnel-server-host`, creating a tunnel for a http service running on port 5000 is as simple as running:
+```bash
+ssh -I {some_rsa_key} -R /my-tunnel:localhost:5000 tunnel-server-host hello
+```
+The expected output of this command will be something like:
+```
+{"clientId":"5rwpwhy5","tunnels":{"/test":"http://my-tunnel-5rwpwhy5.tunnel-server-host:3000/"}}
+```
+A tunnel from `http://my-tunnel-5rwpwhy5.tunnel-server-host:3000->http://localhost:5000` was created, and can be accessed by anyone who knows the URL (assuming the tunnel server is public).
+
+## Security
+
+For connecting to tunneling server, you must use ssh private-key based authentication.
+Urls for tunnels are derived from the public key of the client (referred as clientId):
+`{tunnel_name}-{clientId}.{tunnel-server}`.
+
+`preevy` support connecting to a tunnel server over TLS which wrap the ssh connection, for these cases the tunnel server need to use an external service for TLS termination (e.g. nginx/haproxy/traefik).
+
+## Observability
+The tunnel server expose operational metrics on port 8888 that can be scraped by Prometheus or similar observability tool.