docs tweaks

fabriciojs · fabriciojs · commit 97bab0255b58 · 2024-01-26T22:25:23.000-03:00
diff --git a/docs/02-Kool-Cloud/07-Domains-and-HTTPS.md b/docs/02-Kool-Cloud/07-Domains-and-HTTPS.md
@@ -1,6 +1,10 @@
-All deployed environments will run under HTTPS. Kool.dev Cloud will automatically generate certificates for your environment the first time it is deployed using the Let'sEncrypt engine.
+# Managing domains and HTTPS
 
-You always need to provide the environment domain when running a deploy.
+All deployed environments will run under HTTPS. Kool.dev Cloud will automatically generate certificates for your environment the first time it is deployed using the Let'sEncrypt engine (via K8S `certmanager`).
+
+## Environment domain
+
+You always need to provide the environment domain when running a deploy. The domain is going to be the key identifier of your environment when accessing it via the Kool CLI.
 
 ```bash
 kool cloud --token="<my token>" deploy --domain="my-app-domain.com"
@@ -13,12 +17,28 @@ You can provide those values via environment variables as well if that's easier
 
 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
+## Using multiple domains
+
+Some applications may require serving more than just one domain. This can be easily achieve with Kool.dev Cloud.
+
+When deploying via the CLI, you can specify any number of extra domains that should point to your application:
+
+```bash
+kool cloud --token="<my token>" deploy --domain="my-app-domain.com" --domain-extra="another-domain.com"
+```
+
+## Using a test deployment domain - `*.kool.cloud`
 
 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 the first deploy.
 
-### Production and custom domains
+## Custom domains - DNS records
 
-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.
+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 DNS records for that domain.
 
 HTTPS certificates will only be successfully generated once the DNS is correctly pointing your domain to Kool.dev Cloud.
+
+## HTTPS certificates
+
+As stated above for all environments Kool.dev Cloud will trigger LetsEncrypt routines to generate a valid TLS certificate for your environment domain. All that is required for that to succeed is that the used domain points properly to Kool.dev Cloud IP addresses.
+
+That is why it's important to notice that when deploying a custom domain (not a `*.kool.cloud`) your will only work properly after the DNS records point properly to Kool.dev Cloud and the LetsEncrypt process had time to perform the HTTP01 Acme challenge process.
diff --git a/docs/02-Kool-Cloud/08-Access-Running-Containers.md b/docs/02-Kool-Cloud/08-Access-Running-Containers.md
@@ -0,0 +1,11 @@
+# Access cloud containers
+
+You can run new commands on a running container deployed to Kool.dev Cloud.
+
+For that you should use the CLI command:
+
+```bash
+kool cloud exec <service> -c <container> -- bash
+```
+
+For more details how to use [check out the command documentation]().
diff --git a/docs/02-Kool-Cloud/09-Managed-Databases.md b/docs/02-Kool-Cloud/09-Managed-Databases.md
diff --git a/docs/02-Kool-Cloud/15-Deploy-Lifecycle-Hooks.md b/docs/02-Kool-Cloud/15-Deploy-Lifecycle-Hooks.md
@@ -1,7 +1,11 @@
+# Hooks
+
 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, such as running database migrations, sending alerts of updates to some other service, etc.
 
+# Before and After
+
 To illustrate the options you have in the `kool.cloud.yml` file:
 
 ```yaml
@@ -11,6 +15,7 @@ services:
 
     # The 'before' hook is a special section where we can define commands to be executed
     # right before a new deployment happens.
+    # ATTENTION: current limitation - can only have a 'before' hook after a first deploy has created the environment.
     before:
       - [ sh, run-database-migrations.sh, arg1, arg2 ]
 
@@ -20,6 +25,10 @@ services:
       - [ sh, run-cache-version-update.sh, arg1, arg2 ]
 ```
 
-### Failures on lifecycle hooks
+## Failures on lifecycle hooks
 
 Please notice that these lifecycle hooks are required for the new deploy to be successful—this means that **if any of them fail**—either `before` or `after` newly deployed container versions are running—**the whole deploy is going to be rolled back**. As you can imagine, this poses a challenge, especially on database migrations since they can be problematic and not backwards compatible with the previously running container version.
+
+## Limitations
+
+The `before` hook can only be used after a first deploy has succeded for your environment - that is a limitation that should be lifted in the future, but currently can halt your first deploy if it includes a `before` hook.
diff --git a/docs/02-Kool-Cloud/17-Custom-Resources.md b/docs/02-Kool-Cloud/17-Custom-Resources.md
@@ -1,5 +1,13 @@
-Most 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.
+# Custom Resources
 
-The 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 [contact us via email with your needs](mailto:contact@kool.dev), and we will work through your request.
+Most 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.
+
+The 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 yet, you can just [contact us via email with your needs](mailto:contact@kool.dev), and we will work through your request.
+
+## Bring Your Own Cloud
+
+Important to notice - current cloud scenario is flexible enough where you can use Kool.dev Shared cloud, or hire a dedicated stack fully managed by Kool.dev, or even better - if you want total control and access we can set up the Kool.dev Cloud cluster and resources on your own AWS account. [Contact us](mailto:contact@kool.dev) to learn more about this possibility.
+
+## Consulting
 
 If you lack the DevOps expertise to determine your needs, we also have consulting services available to best serve you.
diff --git a/docs/02-Kool-Cloud/20-kool.cloud.yml-Reference.md b/docs/02-Kool-Cloud/20-kool.cloud.yml-Reference.md
@@ -110,6 +110,9 @@ services:
     #
     # The 'before' hook is a special section where we can define commands to be executed
     # right before a new deployment happens.
+    # ATTENTION: this hook can only be used after a first successful deploy happened to
+    # create the environment in the first place. If used on first deploy, will halt the deploy.
+    # This limitation should be lifted hopefully soon.
     before:
       - script_to_run.sh
     # The 'after' hook is a special section where we can define procedures to be executed
diff --git a/docs/25-Upgrade-Guide/0-Upgrading-Kool.md b/docs/25-Upgrade-Guide/0-Upgrading-Kool.md
@@ -18,3 +18,9 @@ Version 3.x introduces two significant changes:
 
 - The YAML syntax for `services.<service>.build` in the `kool.cloud.yml` file must now align with the official Docker Compose reference for the `service.<service>.build` entry.
 - Image building now occurs in your local environment—specifically, on the host where you execute `kool cloud deploy`. Therefore, ensure that the environment from which you run this command has a properly configured Docker-image build engine (that means Kool to be able to run `docker build` command).
+
+### Github Action `kool-dev/action`
+
+There's a new version of our official installation GH action `kool-dev/action@v3` - that will always install the latest v3 series release.
+
+The first and now legacy `kool-dev/action@v1` has been updated and froze to its past behavior of installing the latest version regardless of the major version mismatch. That is why `kool-dev/action@v1` will for now on always install the latest v2 series release - currently `2.2.0`.
