Merge pull request #495 from kool-dev/docs

Cloud Documentation

README.md

@@ -15,7 +15,7 @@
 
 **Kool** is a CLI tool that brings the complexities of modern software development environments down to earth - making these environments lightweight, fast and reproducible. It reduces the complexity and learning curve of _Docker_ containers for local environments, and offers a simplified interface for using _Kubernetes_ to deploy staging and production environments to the cloud.
 
-**Kool** gets your local development environment up and running easily and quickly, so you have more time to build a great application. When the time is right, you can then use Kool Cloud to deploy and share your work with the world!
+**Kool** gets your local development environment up and running easily and quickly, so you have more time to build a great application. When the time is right, you can then use Kool.dev Cloud to deploy and share your work with the world!
 
 **Kool** is suitable for solo developers and teams of all sizes. It provides a hassle-free way to handle the Docker basics and immediately start using containers for development, while simultaneously guaranteeing no loss of control over more specialized Docker environments.
 
@@ -49,18 +49,18 @@ To help you start building real-world applications, we've created Kool Presets a
 
 #### Popular stacks and frameworks
 
-- **Node**: [NestJS](docs/2-Presets/NestJS.md), [AdonisJs](docs/2-Presets/AdonisJs.md), [Express.js](/docs/2-Presets/ExpressJS.md)
-- **PHP**: [Laravel](docs/2-Presets/Laravel.md), [Laravel Octane](docs/2-Presets/Laravel+Octane.md), [Symfony](docs/2-Presets/Symfony.md), [CodeIgniter](docs/2-Presets/CodeIgniter.md)
-- **Javascript**: [Next.js](docs/2-Presets/NextJS.md), [NuxtJS](docs/2-Presets/NuxtJS.md)
-- **Others**: [Hugo](docs/2-Presets/Hugo.md), [WordPress](docs/2-Presets/WordPress.md)
+- **Node**: [NestJS](docs/03-Presets/NestJS.md), [AdonisJs](docs/03-Presets/AdonisJs.md), [Express.js](/docs/03-Presets/ExpressJS.md)
+- **PHP**: [Laravel](docs/03-Presets/Laravel.md), [Laravel Octane](docs/03-Presets/Laravel+Octane.md), [Symfony](docs/03-Presets/Symfony.md), [CodeIgniter](docs/03-Presets/CodeIgniter.md)
+- **Javascript**: [Next.js](docs/03-Presets/NextJS.md), [NuxtJS](docs/03-Presets/NuxtJS.md)
+- **Others**: [Hugo](docs/03-Presets/Hugo.md), [WordPress](docs/03-Presets/WordPress.md)
 
 #### Monorepo structures
 
 It's a common challange mixing up different frameworks for the frontned and a backend API. Working with containers and having them both working an communicating properly can be a huge differential for good development experience and productivity.
 
 Check out our pre-shaped [mono-repo structures](https://monorepo.tools/#what-is-a-monorepo) in a single preset:
 
-- [Monorepo NestJS + Next.js](docs/2-Presets/2-Monorepo-NestJS-with-NextJS.md) with Typescript on both the frontend and the backend.
+- [Monorepo NestJS + Next.js](docs/03-Presets/2-Monorepo-NestJS-with-NextJS.md) with Typescript on both the frontend and the backend.
 
 > If you don't see your favorite framework in the list above, please let us know by creating a GitHub issue, or, better yet, feel free to submit a PR!
 

commands/cloud.go

@@ -48,8 +48,8 @@ func AddKoolCloud(root *cobra.Command) {
 func NewCloudCommand(cloud *Cloud) (cloudCmd *cobra.Command) {
 	cloudCmd = &cobra.Command{
 		Use:     "cloud COMMAND [flags]",
-		Short:   "Interact with Kool Cloud and manage your deployments.",
-		Long:    "The cloud subcommand encapsulates a set of APIs to interact with Kool Cloud and deploy, access and tail logs from your deployments.",
+		Short:   "Interact with Kool.dev Cloud and manage your deployments.",
+		Long:    "The cloud subcommand encapsulates a set of APIs to interact with Kool.dev Cloud and deploy, access and tail logs from your deployments.",
 		Example: `kool cloud deploy`,
 		//	add cobra usage help content
 		DisableFlagsInUseLine: true,
@@ -85,7 +85,7 @@ func NewCloudCommand(cloud *Cloud) (cloudCmd *cobra.Command) {
 			// if no token is set, we try to get it from the environment
 			if cloud.flags.Token == "" && cloud.env.Get("KOOL_API_TOKEN") == "" {
 				if requiredFlags {
-					err = fmt.Errorf("missing Kool Cloud API token - please set it via --token or KOOL_API_TOKEN environment variable")
+					err = fmt.Errorf("missing Kool.dev Cloud API token - please set it via --token or KOOL_API_TOKEN environment variable")
 					return
 				}
 			} else if cloud.flags.Token != "" {
@@ -96,7 +96,7 @@ func NewCloudCommand(cloud *Cloud) (cloudCmd *cobra.Command) {
 		},
 	}
 
-	cloudCmd.PersistentFlags().StringVarP(&cloud.flags.Token, "token", "", "", "Token to authenticate with Kool Cloud API")
+	cloudCmd.PersistentFlags().StringVarP(&cloud.flags.Token, "token", "", "", "Token to authenticate with Kool.dev Cloud API")
 	cloudCmd.PersistentFlags().StringVarP(&cloud.flags.DeployDomain, "domain", "", "", "Environment domain name to deploy to")
 
 	return

commands/cloud_deploy.go

@@ -47,7 +47,7 @@ type KoolDeploy struct {
 func NewDeployCommand(deploy *KoolDeploy) (cmd *cobra.Command) {
 	cmd = &cobra.Command{
 		Use:   "deploy",
-		Short: "Deploy a local application to a Kool Cloud environment",
+		Short: "Deploy a local application to a Kool.dev Cloud environment",
 		RunE:  DefaultCommandRunFunction(deploy),
 		Args:  cobra.NoArgs,
 

commands/cloud_deploy_destroy.go

@@ -20,7 +20,7 @@ type KoolDeployDestroy struct {
 func NewDeployDestroyCommand(destroy *KoolDeployDestroy) *cobra.Command {
 	return &cobra.Command{
 		Use:   "destroy",
-		Short: "Destroy an environment deployed to Kool Cloud",
+		Short: "Destroy an environment deployed to Kool.dev Cloud",
 		Args:  cobra.NoArgs,
 		RunE:  DefaultCommandRunFunction(destroy),
 

commands/cloud_deploy_exec.go

@@ -27,8 +27,8 @@ type KoolDeployExecFlags struct {
 func NewDeployExecCommand(deployExec *KoolDeployExec) (cmd *cobra.Command) {
 	cmd = &cobra.Command{
 		Use:   "exec SERVICE [COMMAND] [--] [ARG...]",
-		Short: "Execute a command inside a running service container deployed to Kool Cloud",
-		Long: `After deploying an application to Kool Cloud using 'kool deploy',
+		Short: "Execute a command inside a running service container deployed to Kool.dev Cloud",
+		Long: `After deploying an application to Kool.dev Cloud using 'kool deploy',
 execute a COMMAND inside the specified SERVICE container (similar to an SSH session).
 Must use a KOOL_API_TOKEN environment variable for authentication.`,
 		Args: cobra.MinimumNArgs(1),

commands/cloud_deploy_logs.go

@@ -28,8 +28,8 @@ type KoolDeployLogsFlags struct {
 func NewDeployLogsCommand(deployLogs *KoolDeployLogs) (cmd *cobra.Command) {
 	cmd = &cobra.Command{
 		Use:   "logs [OPTIONS] SERVICE",
-		Short: "See the logs of running service container deployed to Kool Cloud",
-		Long: `After deploying an application to Kool Cloud using 'kool deploy',
+		Short: "See the logs of running service container deployed to Kool.dev Cloud",
+		Long: `After deploying an application to Kool.dev Cloud using 'kool deploy',
 you can see the logs from the specified SERVICE container.
 Must use a KOOL_API_TOKEN environment variable for authentication.`,
 		Args: cobra.ExactArgs(1),

docs.go

@@ -5,6 +5,7 @@ package main
 
 import (
 	"bytes"
+	"errors"
 	"fmt"
 	"kool-dev/kool/commands"
 	"kool-dev/kool/core/shell"
@@ -14,22 +15,17 @@ import (
 	"regexp"
 	"strings"
 
+	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
 )
 
 func main() {
 	var (
 		err        error
 		koolOutput *bytes.Buffer
-		cmdFile    *os.File
 		koolFile   *os.File
 	)
 
-	linkHandler := func(filename string) string {
-		base := strings.TrimSuffix(filename, filepath.Ext(filename))
-		return strings.ToLower(base)
-	}
-
 	fmt.Println("Going to generate cobra docs in markdown...")
 
 	koolOutput = new(bytes.Buffer)
@@ -43,42 +39,19 @@ func main() {
 	koolMarkdown := koolOutput.String()
 
 	for _, childCmd := range commands.RootCmd().Commands() {
-		var cmdName string
-
-		if cmdName = strings.Replace(childCmd.CommandPath(), " ", "_", -1); cmdName == "kool_deploy" || cmdName == "kool_help" {
-			continue
-		}
-
-		newName := strings.Replace(childCmd.CommandPath(), " ", "-", -1)
-		koolMarkdown = strings.Replace(koolMarkdown, cmdName, newName, -1)
-
-		cmdOutput := new(bytes.Buffer)
-
-		err = doc.GenMarkdownCustom(childCmd, cmdOutput, linkHandler)
-
-		if err != nil {
-			log.Fatal(err)
-		}
-
-		cmdFile, err = CreateFile(newName, "docs/4-Commands")
-
-		if err != nil {
-			log.Fatal(err)
-		}
-
-		defer cmdFile.Close()
-
-		_, err = cmdOutput.WriteTo(cmdFile)
-
-		if err != nil {
-			log.Fatal(err)
+		if err = exportCmdDocs(childCmd, &koolMarkdown); err != nil {
+			if strings.HasPrefix(err.Error(), "skip") {
+				log.Println(err)
+			} else {
+				log.Fatal(err)
+			}
 		}
 	}
 
 	re := regexp.MustCompile("(?m)[\r\n]+^.*kool_deploy.*$")
 	koolMarkdown = re.ReplaceAllString(koolMarkdown, "")
 
-	koolFile, err = CreateFile("0-kool", "docs/4-Commands")
+	koolFile, err = CreateFile("0-kool", "docs/05-Commands-Reference")
 
 	if err != nil {
 		log.Fatal(err)
@@ -106,3 +79,51 @@ func CreateFile(filename string, dir string) (file *os.File, err error) {
 
 	return
 }
+
+func exportCmdDocs(childCmd *cobra.Command, koolMarkdown *string) (err error) {
+	var (
+		cmdName string
+		cmdFile *os.File
+	)
+
+	if cmdName = strings.Replace(childCmd.CommandPath(), " ", "_", -1); cmdName == "kool_help" {
+		err = errors.New("skip kool_help")
+		return
+	}
+
+	newName := strings.Replace(childCmd.CommandPath(), " ", "-", -1)
+	*koolMarkdown = strings.Replace(*koolMarkdown, cmdName, newName, -1)
+
+	cmdOutput := new(bytes.Buffer)
+
+	if err = doc.GenMarkdownCustom(childCmd, cmdOutput, linkHandler); err != nil {
+		return
+	}
+
+	if cmdFile, err = CreateFile(newName, "docs/05-Commands-Reference"); err != nil {
+		return
+	}
+
+	defer cmdFile.Close()
+
+	if _, err = cmdOutput.WriteTo(cmdFile); err != nil {
+		return
+	}
+
+	for _, subCmd := range childCmd.Commands() {
+		if err = exportCmdDocs(subCmd, koolMarkdown); err != nil {
+			if strings.HasPrefix(err.Error(), "skip") {
+				log.Println(err)
+			} else {
+				return
+			}
+		}
+	}
+
+	return
+}
+
+func linkHandler(filename string) string {
+	base := strings.TrimSuffix(filename, filepath.Ext(filename))
+	return strings.ToLower(base)
+}

docs/1-Getting-Started/3-How-it-works.md → docs/01-Getting-Started/3-How-it-works.md

@@ -15,18 +15,18 @@ Out of the box, Kool ships with a collection of Presets that will help you quick
 
 > As an example of the Preset developer experience, check out the [Laravel preset](https://kool.dev/docs/presets/laravel).
 
-- [AdonisJs](/docs/2-Presets/AdonisJs.md)
-- [CodeIgniter](/docs/2-Presets/CodeIgniter.md)
-- [Express.js](/docs/2-Presets/ExpressJS.md)
-- [Hugo](/docs/2-Presets/Hugo.md)
-- [Laravel](/docs/2-Presets/Laravel.md)
-- [NestJS](/docs/2-Presets/NestJS.md)
-- [Next.js](/docs/2-Presets/NextJS.md)
-- [Node.js](/docs/2-Presets/NodeJS.md)
-- [Nuxt.js](/docs/2-Presets/NuxtJS.md)
-- [PHP](/docs/2-Presets/PHP.md)
-- [Symfony](/docs/2-Presets/Symfony.md)
-- [WordPress](/docs/2-Presets/WordPress.md)
+- [AdonisJs](/docs/03-Presets/AdonisJs.md)
+- [CodeIgniter](/docs/03-Presets/CodeIgniter.md)
+- [Express.js](/docs/03-Presets/ExpressJS.md)
+- [Hugo](/docs/03-Presets/Hugo.md)
+- [Laravel](/docs/03-Presets/Laravel.md)
+- [NestJS](/docs/03-Presets/NestJS.md)
+- [Next.js](/docs/03-Presets/NextJS.md)
+- [Node.js](/docs/03-Presets/NodeJS.md)
+- [Nuxt.js](/docs/03-Presets/NuxtJS.md)
+- [PHP](/docs/03-Presets/PHP.md)
+- [Symfony](/docs/03-Presets/Symfony.md)
+- [WordPress](/docs/03-Presets/WordPress.md)
 
 ### Docker and Docker Compose
 

docs/02-Kool-Cloud/01-Getting-Started.md

@@ -0,0 +1,33 @@
+The [Kool.dev Cloud](https://kool.dev/cloud) supports a wide range of features designed to suit your needs for deploying containerized web applications. It includes features such as **persisting folders** across deployments, running **daemons** as extra containers, scheduling commands like **cron jobs**, adding **hooks to run before or after** deployment, **viewing logs** of running containers, accessing the running container **interactively**, and much more.
+
+The Kool.dev Cloud API was designed with the best developer experience in mind for deploying containers to the cloud. By leveraging your existing local environment structure in `docker-compose.yml` and adding a sane and intuitive configuration layer that will feel familiar from the first sight, our goal is to provide a best-in-class offering for cloud platform engineering. This platform allows you to leverage Kubernetes and orchestrate your web applications in the cloud without all the hassle.
+
+> **Enterprise**: You can use Kool.dev Cloud to deploy workloads to your own cloud vendor to keep things compliant - [contact us](mailto:[email protected]) for the **"Bring your Own Cloud"** offer.
+
+**Kool.dev Cloud** is the CLI suite of commands that allows you to configure, deploy, access, and tail logs from the applications to the cloud via the Kool.dev Cloud API.
+
+## Deploy Docker Compose-based, containerized apps in just a few simple steps
+
+1. [Sign up for Kool.dev Cloud](https://kool.dev/register) and get your access token.
+	- You can store your token in your `.env` file if you are using one:
+		- `echo "KOOL_API_TOKEN=<my-token>" >> .env`
+	- Or you can store your token in a real environment variable:
+		- `export KOOL_API_TOKEN="<my token>"`
+1. Configure your deployment with files directly in your application root folder. For that, you can use [`kool cloud setup`](/docs/commands-reference/kool-cloud-setup) to help guide you in creating the following files:
+	- `kool.deploy.yml` - a "mirror" of your `docker-compose.yml` file, with extra pieces of data for customizing your cloud deployment.
+	- `Dockerfile` - usually, you are going to need to build your app for deployment if you haven't already.
+	- Make sure you set up the necessary [environment variables](/docs/kool-cloud/environment-variables) for your app to run in the cloud.
+1. Deploy your application
+	- Run `kool cloud deploy --domain=<your domain>` - this will validate and deploy your application.
+	- Wait for it to finish and then access the provided deployment URL!
+1. Doing more
+	- **View logs**
+		- `kool cloud logs` - you can check the logs of your deployed containers.
+	- **Access running containers (like SSH-ing in)**
+		- `kool cloud exec` - you can execute commands, including interactive TTY sessions, within your cloud-deployed containers. For example, `kool cloud exec app bash` to open a bash in my running container in the cloud.
+
+---
+
+Reference:
+
+- [`kool.deploy.yml` Reference](/docs/kool-cloud/kool.deploy.yml-reference)

docs/02-Kool-Cloud/03-Building-Images-to-Deploy.md

@@ -0,0 +1,52 @@
+This topic is usually the biggest source of problems and trial-and-error frustrations when deploying cloud-native applications for the first time.
+
+As much as the Kool.dev project and the whole community try to help and facilitate container image building, it is at times ultimately an individual and singular process for your web application.
+
+That being said, there's no escape from having some knowledge of how to properly build your images to deploy your app to the cloud—or at least seek such knowledgeable hands to assist you in this moment.
+
+For the most basic cases — like if you are using one of our presets — you will have a great starting point by using our utility along with `kool cloud setup`. This command will inquire about basic options for building your container images.
+
+
+### `kool cloud deploy` building images
+
+The `kool` CLI is going to handle the build of your images locally—in your own host system. That means it's required that the environment where you are going to run `kool cloud deploy` has a working Docker-like engine running that can successfully process a `docker build ...` command.
+
+The syntax configuration for building your deploy image for a given service in `kool.cloud.yml` is the very same as you use it locally in `docker-compose.yml`:
+
+Check out the [Docker Compose `build` Documentation](https://docs.docker.com/compose/compose-file/compose-file-v3/#build) for reference.
+
+```yaml
+services:
+  app:
+    # ...
+    build: . # this uses the root folder as context, and expects a Dockerfile to exist on it
+```
+
+or
+
+```yaml
+services:
+  app:
+    # ...
+    build:
+      context: ./dir # changes the context folder
+      dockerfile: Dockerfile-alternate # name a different file than default 'Dockerfile'
+      args:
+        buildno: 1 # define values for ARGS used in your Dockerfile
+```
+
+Your image will be built locally when running the `kool` CLI for a deploy and then pushed securely to the Kool.dev Cloud registry to a repository dedicated to your app environment.
+
+### Using a Private Registry
+
+You may already have or use your own private registry for handling images. You are welcome to hold the build process apart from the `kool cloud deploy` step and just use the already built images in your `kool.cloud.yml` file:
+
+```yaml
+services:
+  app:
+    # ...
+    image: myrepo-registry/my-built-image
+```
+
+If that registry is private, you need to provide Kool.dev Cloud with credentials to read from that repo. As this is not yet fully automated, you can [contact us via email at `[email protected]`]([email protected]) to set it up for you.
+