cloud docs

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

@@ -2,7 +2,7 @@ The [Kool Cloud](https://kool.dev/cloud) supports a wide range of features desig
 
 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 **"Bring your Own Cloud"** offer.
+> **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 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.
 
@@ -28,6 +28,6 @@ The Kool.dev Cloud API was designed with the best developer experience in mind f
 
 ---
 
-Full documentation:
+Reference:
 
-- [`kool.deploy.yml` Reference](/docs/02-Kool-Cloud/10-kool.deploy.yml-Reference.md)
+- [`kool.deploy.yml` Reference](/docs/02-Kool-Cloud/20-kool.deploy.yml-Reference.md)

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

@@ -0,0 +1,50 @@
+This topic is usually the biggest source or 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 tries to help and facilitate container images building, it is a times ultimately an individual and singular process for your web application.
+
+That being said there's no scape from having some knowledge on how to properly build your images to deploy your app to the cloud - or at least seek such knowledgable hands to assist your in this moment.
+
+For the most basic cases - like if you are using one of our presets - you will have a great start point by using our utility along `kool cloud setup` - this command will inquiry you about basic options on building your container images.
+
+### `kool cloud deploy` building images
+
+`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` have a working Docker-like engine running that can process successfully a `docker build ...` command.
+
+The syntax configuration for building your deploy image for a given service on `kool.cloud.yml` is the very same as you use it locally on `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 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 [ping us via email to `[email protected]`]([email protected]) to set it up for you.

docs/02-Kool-Cloud/05-Environment-Variables.md

@@ -0,0 +1,47 @@
+Most application and frameworks nowadays will rely on environment variables to configure important aspects of its functions, mainly providing credentials and other secrets your app need to work and access other resources.
+
+Kool.dev Cloud supports a few different ways you can define your environment variables for a given deploying container, so pick the one that best suits you.
+
+### Using `kool.deploy.env` file for deploy
+
+`kool.deploy.env` should be a `.env` formatted file. You can point to it like this:
+
+```yaml
+services:
+  app:
+    # ...
+    environment: kool.deploy.env
+```
+
+Upong deployment, all of the variables within that file will be parsed, placeholders replaced - if you have any - and then **each variable will become a real environment variables in the running container**.
+
+This option is usually best suited for automated CI routines since you work your way to have a different `kool.deploy.env` file for each of your deploying environments (i.e staging and production).
+
+### Using a plain YAML object for environment variables
+
+```yaml
+services:
+  app:
+    # ...
+    environment:
+      FOO: bar
+```
+
+You can simply use a YAML map of values that will become your environment variables in the running deployed container. This is handy sometimes when you have simple and not sensitive variables you want to add to a container for deploy.
+
+### Build a `.env` file inside the running container
+
+If you application does rely and requires a `.env` file existing in the running container you may achieve so by using the `env:` entry:
+
+```yaml
+services:
+  app:
+    # ...
+
+    # 'env' is a different option that allows you to build a file inside your running container.
+    env:
+      source: kool.deploy.env
+      target: .env
+```
+
+This is useful for apps that have require the .env file, but you do not wish to have that built into your Docker image itself.

docs/02-Kool-Cloud/07-Domains-and-HTTPS.md

@@ -0,0 +1,24 @@
+All deployed environments will run under HTTPS. Kool.dev Cloud will automatically generate certificates for your environment the first time it is deployed using Let'sEncrypt engine.
+
+You always need to provide the environment domain when running a deploy.
+
+```bash
+kool cloud --token="<my token>" deploy --domain="my-app-domain.com"
+```
+
+You can provide those values via environment variables as well if that's easier for you:
+
+- `KOOL_API_TOKEN` for the access token.
+- `KOOL_DEPLOY_DOMAIN` for the domain environment you want to deploy to.
+
+Important to notice: if you deploy to a new domain that doesn't currently exist in your Kool.dev Cloud panel, that is totally fine and will just create a very new environment for that domain.
+
+### Test deployment domains
+
+You are welcome to use a subdomain like `my-super-app.kool.cloud` on your staging or development environments. By using that you will have HTTPS certificates up and running instantly for that environment after first deploy.
+
+### Production and custom domains
+
+When you create an environment to be deployed using your own custom domain name, you will need to check out in the Kool.dev Cloud panel for that environment the instructions to where to point your A/CNAME for that domain.
+
+HTTPS certificates will only be successfully generated once the DNS is correctly pointing your domain to Kool.dev Cloud.

docs/02-Kool-Cloud/08-Managed-Databases.md

@@ -0,0 +1,52 @@
+Most of time the web applications you are going to deploy will usually have its own companying database.
+
+Kool.dev Cloud offers two ways for you do deploy your databases.
+
+1. Deploy databases as regular containers.
+1. Use a managed database on a shared structure.
+1. Use a dedicated Database Custom Resource (i.e RDS dedicated instance).
+
+All of this options come with basic daily backup routines for your safety.
+
+### Deploy Databases as Regular Containers
+
+Deploying a container that is going to run your database is pretty straight forward - just like your have it in your local `docker-compose.yml` for your local environment, you can deploy that very same container. The benefit of this is you have full control at your container configuration and can use any type of database.
+
+#### Caveats of deploying databases on containers are
+
+- **Persistent disk storage**: by default deployed containers are ephemeral and DO NOT have any disk persistent storage. This may cause problems if you deploy a database and upon restart, all your data is lost. **You must make sure to incoude in your container deploy configuration a `persistent` disk storage**, so upon restarts your data is kept safe and is no longer ephemeral.
+- **Environment variables**: your database image may require specific environment variables to determine credentials and other settings. You need to make sure you set them correctly, different than your local ones.
+
+### Managed Database in shared structure
+
+This option is the easiest to get started - but currently only supports MySQL 8 database deployments.
+
+If you have a MySQL database in your `docker-compose.yml`, you can just assign that service the `cloud: true` on your `kool.cloud.yml` and Kool.dev Cloud is going to setup a new database on a running shared RDS instance.
+
+This managed options will provide you with variables placeholders for you to get a hold of the credentials automatically generated as well as the database name/host.
+
+Here is the list of Kool.dev variables placeholders available and how you would use them in your environment variables definition to use the managed database:
+
+```
+DB_HOST="{{KOOL_DATABASE_HOST}}"
+DB_PORT={{KOOL_DATABASE_PORT}}
+DB_DATABASE="{{KOOL_DATABASE_DATABASE}}"
+DB_USERNAME="{{KOOL_DATABASE_USERNAME}}"
+DB_PASSWORD="{{KOOL_DATABASE_PASSWORD}}"
+```
+
+The placeholders always have the `{{PLACEHOLDER}}` syntax. When used anywhere in your `kool.cloud.yml` configuration they are going to be replaced by their managed values when deploying.
+
+#### Caveats of using managed shared database
+
+- Currently **only supports MySQL 8** deployments.
+- Being a shared resource, top performance is not guarenteed (unless you have it running in your own Cloud vendor account in the Enterprise offer).
+- Best suited for development and staging workloads.
+
+### Dedicated Database Resource
+
+You can have any sort of custom resource for your application, including dedicated databases (i.e RDS or ElastiCache).
+
+As this is not yet fully automated you need to [contact our support to set it up](mailto:[email protected]) for you in your account.
+
+One of the benefits is having total control of your set up not only on disk/computing performance, but as well as tailored backup and replication options.

docs/02-Kool-Cloud/10-Persistent-Storage.md

@@ -0,0 +1,32 @@
+Containers were built to be ephemeral - and that is how we like them and how Kubernetes and all other container orchestrators usually work the best with them as well.
+
+But at times we know that tradicional web applications may not be ready to switch to network-based object storage instead of local disk storage.
+
+Kool.dev Cloud does offer you the ability to create persisted paths within your deployed containers.
+
+```yaml
+services:
+  app:
+    # ...
+
+    # Tells your app's root folder so all other paths can be relative (optional).
+    root: /app
+
+    # Containers are ephemeral, that means their filesystem do not persist across restarts.
+    # If you want to persist stuff into the disk across deployments, you can do so by defining persistent paths here.
+    persists:
+      # Total size of the volume you want to attach to the running container.
+      # This can be increased later, but it may take a while to apply the change.
+      size: 10Gi
+      # Paths to persist - within that single volume, you can have one or more paths
+      # that are going to be mounted every time your containers are running. Note that
+      # such mounts will be there for before/after hooks as well as daemon containers.
+      paths:
+        # The path within the container. Must be either aboslute or relative to the 'root' config.
+        - path: /app/some/path/persisted
+          # Tells the Deploy API to sync the folder from your built image to the persisted storage.
+          # This is very helpful to start off with a known folder structure.
+          sync: true
+          # Tells what user and group should own the persisted folder (only used when sync: true)
+          chown: user:group
+```

docs/02-Kool-Cloud/15-Deploy-Lifecycle-Hooks.md

@@ -0,0 +1,25 @@
+You have the ability to define hooks to run before or after every deploy you make.
+
+These hooks will run using the very same image that is being deployed. This is usually needed for common routines, as for example running database migrations, sending alerts of updates to some other service, etc.
+
+To illustrate the options you have on `kool.cloud.yml` file:
+
+```yaml
+services:
+  app:
+    # ...
+
+    # The 'before' hook is a special section where we can define commands to be executed
+    # right before a new deployment happens.
+    before:
+      - [ sh, run-database-migrations.sh, arg1, arg2 ]
+
+    # The 'after' hook is a special section where we can define procedures to be executed
+    # right after a new deployment finishes.
+    after:
+      - [ sh, run-cache-version-update.sh, arg1, arg2 ]
+```
+
+### Failures on lifecycle hooks
+
+Please notice that these lifecycle hooks are required in order for the new deploy to be successfull - this mean that **if any of them fail** - either `before` or `after` new deployed contianer versions are running - **the whole deploy is going to be rolledback**. As you can imagine this poses a challange specially on database migrations since they can be problematic and not backwards compatible with previously running container version.

docs/02-Kool-Cloud/17-Custom-Resources.md

@@ -0,0 +1,5 @@
+Most of real world web applications will go beyond just computing containers with your code - there's a vast myriad of other resources you will eventually need like dedicated database services (i.e RDS), replication, object storage (i.e S3), CDN (i.e CloudFront) just to name a few.
+
+Kool.dev Cloud team is ready to set it up for you when needed - providing you the Infrastructure-as-Code to live close to your application. While this is not built into our panel for self-service usage, you can just [ping us via email with your needs](mailto:[email protected]) and we will work through your request.
+
+If you lack the DevOps expertise to determine your needs, we also have consulting services available to best serve you.

docs/02-Kool-Cloud/10-kool.cloud.yml-Reference.md → docs/02-Kool-Cloud/20-kool.cloud.yml-Reference.md

@@ -35,10 +35,14 @@ Here's an example of `kool.cloud.yml` file showcasing all the features and confi
 services:
   app:
     # Applications usually will require a special image built for deployment.
-    build: Dockerfile
+    # Reference: https://docs.docker.com/compose/compose-file/compose-file-v3/#build
+    build: .
 
     # Tells Kool Cloud that this service is accessible through the deployment URL.
     # Note: only one service can be set to be public.
+    public: true # simply defining true is enough to most cases where your `expose` port will be used for routing incoming HTTP requests.
+
+    # Another option is advanced definition:
     public:
       # Tells the port that should be used for routing incoming HTTP traffic.
       - port: 80
@@ -50,7 +54,7 @@ services:
         path: /ws
 
     # Tells what port the app will listen to (optional).
-    port: 80
+    expose: 80
 
     # Tells your app's root folder so all other paths can be relative (optional).
     root: /app
@@ -74,7 +78,7 @@ services:
 
     # By default, Kool Cloud will rollout new deployments in a blue-green fashion.
     # If you want to disable it and make sure the current running container
-    # stopped before the new one is created, set 'recreate: true'.
+    # is stopped before the new one is created, set 'recreate: true'.
     recreate: false
 
     # Sometimes you may make changes to your app that wouldn't necessarily trigger