Merge pull request #64 from paynejacob/issue-46

move package tutorial out of readme.

Author: paynejacob

README.md

@@ -1,24 +1,8 @@
 # Corral
-Corral is a CLI tool for creating and packaging reproducible development environments.  Corral allows developers to manage multiple environments, called corrals, and provision them consistantly using shared packages.
+Corral is a CLI tool for creating and packaging reproducible development environments.  Corral allows developers to manage multiple environments, called corrals, and provision them consistently using shared packages.
 
-# Available Packages
-- `ghcr.io/rancherlabs/corral/k3s:latest`: Create a single node k3s cluster in Digitalocean.
-- `ghcr.io/rancherlabs/corral/k3s-ha:latest`: Create a highly available k3s cluster in Digitalocean.
-- `ghcr.io/rancherlabs/corral/rke2:latest`: Create a single node rke2 cluster in Digitalocean.
-- `ghcr.io/rancherlabs/corral/rke2-ha:latest`: Create a highly available rke2 cluster in Digitalocean.
-- `ghcr.io/rancherlabs/corral/rancher:latest`: Create a single node rancher in Digitalocean.
-- `ghcr.io/rancherlabs/corral/rancher-ha:latest`: Create a HA rancher in Digitalocean.
-
-This repo contains a few packages to get started! These packages share some common variables between them.
-
-`digitalocean_token`: Used to provision Digitalocean resources.
-`digitalocean_domain`: Used to generate dns records.
-
-`aws_access_key` `aws_access_secret` are used to provision AWS resources.
-
-# Usage
-
-To get started with corral lets create and connect to a k3s cluster in Digitalocean.
+# Installation
+To install corral download the latest binary from the [releases](https://github.com/rancherlabs/corral/releases).
 
 ## First Time Setup
 
@@ -71,134 +55,4 @@ A corral is a collection of resources in a remote environment. Think of it as a
 A corral package is a description of an environment.   A package consists of one terraform module and filesystem overlay.  The terraform module is used to provision cloud resources. Once the resources are created corral will upload the files in the overlay folder to any nodes generated by terraform and call the commands defined in the manifest.
 
 # How do I create a package?
-Packages consist of 3 components, a terraform module, overlay, and a manifest. The terrform module can define node pools via an output.  Node pools are a collection of hosts for corral to run commands on.  Overlay files are files copied onto the nodes in the node pools. For linux hosts they are copied to `/`. The manifest describes the package and what commands should be run on the nodes to provision the corral.  Commands are executed sequentially however they will be run concurrently on all nodes within the specified node pools. Packages should describe a specific environment and not offer too much configuration. A good package produces consistent environments and requires little to no input.
-
-To get started create the package's folder structure.
-
-```
-mypkg/
-    terraform/
-        module/
-            main.tf
-            corral.tf
-    overlay/
-        /opt
-            /corral
-                hello-world.sh
-    manifest.yaml
-```
-
-We can define values a user can set or read by defining values in the manifest. In this manifest we define a variable for our Digitalocean token.  Variables are json schemas so we can define some validation to help the user. Variables can also be marked as sensitive, this prevents corral from returning them when the `vars` command is called.  Manifests may also define variables with `readOnly`, this indicates that the package will set the value for this variable and the user should not attempt to change it.
-
-```yaml
-name: mypkg
-variables:
-    digitalocean_token:
-      sensitive: true
-      type: string
-      optional: false
-      description: "A Digitalocean API token with write permission. https://docs.digitalocean.com/reference/api/create-personal-access-token/"
-```
-
-In our terraform module we start with `corral.tf`. This file can be named anything you like but there are a few special
-terraform variables and outputs for interacting with corral.  All these objects are completely optional.
-
-```terraform
-variable "corral_name" {} # The name of this corral.
-variable "corral_user_id" {} # A string to identify who created theses resources.
-variable "corral_user_public_key" {} # A public key the user has access to that can be used to grant access to generated resources.
-variable "corral_public_key" {} # The public key corral uses to run scripts. Required if node pools are defined.
-
-output "corral_node_pools" { # A map of node pool names to nodes.  Nodes must define name, user, and address. Optionally a bastion_address can be defined to route connections through.
-  value = {
-    pool1 = [for droplet in [digitalocean_droplet.hello_world] : {
-      name = droplet.name
-      user = "root"
-      address = droplet.ipv4_address # Address are in the format [host]:[port], if no port is defined 22 will be used.
-    }]
-  }
-}
-```
-
-Now let's define the node we referenced in our node pools in `mypkg/terraform/module/main.tf`.
-
-```terraform
-terraform {
-  required_version = ">= 0.13"
-  required_providers {
-    digitalocean = {
-      source  = "digitalocean/digitalocean"
-      version = "~> 2.0"
-    }
-  }
-}
-
-variable "digitalocean_token" {}
-
-provider "digitalocean" {
-  token = var.digitalocean_token
-}
-
-resource "digitalocean_ssh_key" "corral_key" {
-  name       = "corral-${var.corral_user_id}-${var.corral_name}"
-  public_key = var.corral_public_key
-}
-
-resource "digitalocean_droplet" "hello_world" {
-  name = "${var.corral_user_id}-${corral_name}"
-  image    = "ubuntu-20-04-x64"
-  region   = "sfo3"
-  size     = "s-1vcpu-2gb"
-  tags = [var.corral_user_id, var.corral_name]
-  ssh_keys = [digitalocean_ssh_key.corral_key.id]
-}
-```
-
-Now let's add a script called `mypkg/overlay/opt/corral/hello-world.sh` to install our user public key and get the node's hostname. To do this we can read the user public key from the environment.  All corral variables are available as `CORRAL_<variable name>`.  If you want to set additional variables for the next script or future reference you can use the `corral_set` command by writing to standard out.
-
-```shell
-#!/bin/bash
-
-echo "$CORRAL_corral_user_public_key" >> /$(whoami)/.ssh/authorized_keys
-
-echo "corral_set hostname=$(hostname)"
-```
-
-To tell corral to use our script we can add a command to the manifest.
-
-```yaml
-name: mypkg
-variables:
-    digitalocean_token:
-      sensitive: true
-      type: string
-      optional: false
-      description: "A Digitalocean API token with write permission. https://docs.digitalocean.com/reference/api/create-personal-access-token/"
-commands:
-  - command: /opt/corral/hello-world.sh
-    node_pools:
-      - pool1
-```
-
-We can check our work with the `validate` command.
-
-```yaml
-corral pacakge validate ./mypkg
-```
-
-Finally, we can use our package by calling create.
-
-```shell
-corral create test ./mypkg
-```
-
-If you want to distribute your package you can push it to any OCI compatible registry.
-
-```shell
-corral package login ghcr.io
-corral package publish ./mypkg ghcr.io/myghaccount/mypkg:latest
-```
-
-
-# Installation
-To install corral download the latest binary from the [releases](https://github.com/rancherlabs/corral/releases). 
+[See the tutorial here.](docs/packages/tutorial.md)