Merge pull request #498 from kool-dev/docs-heading

Docs Tweaks and Improvements

docs/01-Getting-Started/1-Introduction.md

@@ -1,10 +1,38 @@
-From **development** to **production**, **kool** brings speed and security to software developers working with multiple tech stacks, making their development environments reproducible and easy to set up.
+# What is kool?
 
-**kool** will help you:
+**kool** is a powerful CLI tool designed to streamline the complexities of modern software development environments. It simplifies the use of Docker for local development, making environments lightweight, fast, and reproducible. And when you are ready, it will help you ship any `docker-compose.yml` based app to the cloud with
+an amazing Developer Experience.
 
-* Stop installing different tech stacks on your local machine (e.g. PHP/Ruby/Python, MySQL/MariaDB/PostgreSQL/MongoDB, NGINX/Apache, Redis/Memcached, Node, etc)
-* Stop writing how-to documentation for setting up local development environments
-* Eliminate "it works on my machine" problems caused by different versions / setups
-* Maintain total control of each tech stack on every project
-* Work locally using the very same tech stack and versions as your production environment
-* Work the same way across different tech stacks and projects (e.g. Laravel, Symfony, Next.js, Nuxt.js, AdonisJs, NestJS, Hugo, WordPress, etc)
+# Why would I want to use kool?
+
+Using **kool** offers several advantages:
+
+- **Easier Configuration:** Say goodbye to the learning curve and frustration of configuring Docker flags, fixing user permissions, and managing local and global networks.
+
+- **Simpler Containerization:** **kool** reduces the cognitive overhead of containerizing your stack with an intuitive CLI interface for managing Docker containers and Docker Compose services. Leverage battle-tested presets and configurations so you don't reinvent the wheel everytime.
+
+- **Faster Workflow:** Enjoy the speed of spinning up new local environments, effortlessly switching between projects, sharing local changes with colleagues and clients, and deploying to the cloud—all accomplished in seconds. Collect on the benefits of containers technology like Docker today without the steep leaning curve to do it the right way.
+
+- **Optimized Development:** **kool** provides custom Docker images optimized for local development and deployment. It also includes pre-built Presets with sensible defaults for rapid project setup using popular frameworks.
+
+# Who is kool for?
+
+**kool** caters to a broad audience, making it suitable for:
+
+- **Solo Developers:** Perfect for individual developers seeking a hassle-free way to handle Docker basics and immediately start using containers for development. From newcomers to senior DevOps, it's a friendly tool to anyone that enjoys and values good Developer Experience.
+
+- **Teams of All Sizes:** Ideal for teams, offering a unified approach to Docker while ensuring no loss of control over more specialized Docker environments. Making part of your DevOps needs a no brainer.
+
+# How to get started?
+
+Getting started with **kool** is straightforward:
+
+1. **Installation:** Ensure you have Docker installed and then follow the [installation instructions](/docs/01-Getting-Started/2-Installation.md) to set up **kool**.
+
+2. **Start new Local Environment:** Explore the [Starting new Project](/docs/01-Getting-Started/4-Starting-new-project.md) for a spinning up local environments to kickstart your development journey with **kool**.
+
+3. **Explore Presets:** Check out available [Presets](/docs/03-Presets/0-About-Presets.md) tailored for popular stacks and frameworks, providing a head start for your real-world applications.
+
+4. **Deployment to the Cloud:** Check out [Kool.dev Cloud](https://kool.dev/cloud) to elevate your Developer Experience to new highs - start deploying containerized apps the way you always dreamed should be possible.
+
+Now you're ready to experience a better, more efficient development environment with **kool**!

docs/01-Getting-Started/2-Installation.md

@@ -1,30 +1,30 @@
-## Installation
+# Installation
 
-### Requirements
+## Requirements
 
 **kool** is powered by **Docker**. To use **kool**, you need to **[install the Docker Engine and Docker Compose](https://docs.docker.com/get-docker/)** on your local machine, and make sure they're both running.
 
-Important to notice: `kool` relies on the `docker` and `docker compose` CLI commands - that being said, you can pick any other Docker-compatibable container engine and use it seamlessly, like OrbStack for example.
+Important to notice: `kool` relies on the `docker` and `docker compose` CLI commands - that being said, you can pick any other Docker-compatibable container engine and use it the same way, like **OrbStack** on MacOS or **Podman** on Linux.
 
-> `kool` now requires [Docker Compose V2](https://docs.docker.com/compose/install/), make sure you have it enabled in your system.
+> `kool` now requires [Docker Compose V2](https://docs.docker.com/compose/install/) API. Make sure you have the latest container engine in your .
 
-### For Linux and macOS
+## For Linux and macOS
 
 Install **kool** by running the following script. It will download the latest **kool** binary from [https://github.com/kool-dev/kool/releases](https://github.com/kool-dev/kool/releases), and save it in your `/usr/local/bin` folder.
 
 ```bash
 $ curl -fsSL https://kool.dev/install | bash
 ```
 
-### For Windows
+## For Windows
 
 You must run `kool` on Windows via [WSL - Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) - once you have a WSL environment properly set up, make sure you have [Docker available on it](https://docs.docker.com/desktop/wsl/), then you can install the CLI as you would in any Linux or MacOS (see above).
 
 ### Verification
 
 Verify **kool** is installed correctly by running `kool` in your terminal to see a list of available commands.
 
-## Stay Up-to-Date
+# Stay Up-to-Date
 
 Update **kool** to a newer version using the `self-update` command. This command will compare your local version with the latest release, and, if a newer version is available, automatically download and install it.
 
@@ -34,11 +34,11 @@ $ kool self-update
 
 > Sign up for new release notifications and stay up-to-date on our latest features! [Go to our main GitHub repository](https://github.com/kool-dev/kool), click on "Watch" at the top, select the "Custom" option, check "Releases", and hit Apply.
 
-## Autocompletion
+# Autocompletion
 
 If you want to use **kool** autocompletion in your Unix shell, follow the appropriate instructions below.
 
-### Bash
+## Bash
 
 Temporarily enable autocompletion for your **current session only**:
 
@@ -62,7 +62,7 @@ $ kool completion bash > /usr/local/etc/bash_completion.d/kool
 
 > After running one of the above commands, remember to start a new shell for autocompletion to take effect.
 
-### Zsh
+## Zsh
 
 If Zsh tab completion is not already initialized on your machine, run the following command to turn it on.
 
@@ -78,7 +78,7 @@ $ kool completion zsh > "${fpath[1]}/_kool"
 
 > After running the above command, remember to start a new shell for autocompletion to take effect.
 
-### Fish
+## Fish
 
 Temporarily enable autocompletion for your **current session only**:
 

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

@@ -1,4 +1,8 @@
-**Kool** is a suite of open source dev tools that level up the way you build and deploy modern, cloud native web applications. By using Kool, you'll get a better development environment and a better development workflow, which adds up to **a better developer experience**.
+# How does Kool work?
+
+**Kool** stands as a comprehensive suite of open-source development tools meticulously crafted to enhance the process of building and deploying modern containerized web applications. Leveraging **Kool** doesn't just improve your development environment; it transforms your entire development workflow, resulting in a significantly enhanced developer experience. With Kool, every step of the development journey becomes smoother and more efficient.
+
+The way **Kool** delivers on these promises is by providing a unified and intuitive command-line interface (CLI) that seamlessly integrates with Docker and Kubernetes. **Kool** simplifies the complexities of setting up, configuring, and managing containers, allowing you to focus on your code and application logic. Behind the scenes, **Kool** employs custom Docker images optimized for local development and deployment, ensuring a consistent environment across different projects. Additionally, **Kool** offers pre-configured Presets for various stacks and frameworks, eliminating the need to start from scratch every time. This thoughtful approach streamlines the development process, making it not only powerful but also accessible to developers of all levels of expertise.
 
 <a name="better-development-environment"></a>
 ## A Better Development Environment
@@ -46,20 +50,26 @@ Kool loads environment variables from a **.env** file. If there's a **.env.local
 
 > It's important to keep in mind that **real** environment variables defined inline as `VAR=value kool ...` or via `export VAR=value` will take precedence over the same variables in your **.env** files.
 
-### Kool Snippets
+### Kool Recipes
+
+In the realm of Kool, Recipes serve as concise sets of automated steps to tailor and enhance your project's environment. Typically, these steps involve the addition of new services to the docker-compose.yml file, complemented by companion scripts within kool.yml. These recipes come bundled with clear instructions and learning resources, empowering you to swiftly tweak and set up new functionalities in your development environment.
+
+It's worth noting that Kool Presets are essentially compositions of different recipes. The modular nature of these recipes allows you the flexibility to use them independently, standalone, if you prefer to cherry-pick specific enhancements for your projects. This modular approach adds versatility to your development process, letting you customize your environment based on your project's unique requirements.
 
-Add services to your development environment by copying and pasting code snippets into your project's **docker-compose.yml** file. We just have a couple at the moment, but we'll be adding more soon.
+```bash
+# see a list with all recipes available to pick from
+kool recipe
+```
 
-- [Generate PDFs](https://kool.dev/docs/snippets/generate-pdfs)
-- [Mailhog](https://kool.dev/docs/snippets/mailhog)
+### kool.yml
 
 ### kool.yml
 
-This is your Kool configuration file. It defines scripts (commands) that you execute in your local environment or CI/CD workflows. It should be placed inside your project and committed to version control. Think of **kool.yml** as a super easy-to-use task helper. Instead of writing custom shell scripts, you can add your own scripts to **kool.yml** (under the scripts key), and run them with `kool run SCRIPT`. You can add single line commands (`kool run artisan`), or add a list of commands that will be executed in sequence (`kool run setup`).
+The **kool.yml** file serves as your Kool configuration file, defining scripts (commands) to execute in your local environment or CI/CD workflows. Place it within your project and commit it to version control. Think of **kool.yml** as an exceptionally user-friendly task helper. Rather than crafting custom shell scripts, you can effortlessly add your own scripts to **kool.yml** (under the `scripts` key) and run them with `kool run SCRIPT`. Scripts can be single-line commands (`kool run artisan`) or lists of commands executed sequentially (`kool run setup`).
 
-> Use **environment variables** within your scripts to **parameterize** them, and give them an extra bit of power and flexibility.
+> Harness the power of **environment variables** within your scripts to **parameterize** them, adding an extra layer of versatility and flexibility.
 
-Every **Kool Preset** auto-generates a **kool.yml** file with prebuilt scripts customized for that framework and/or stack. You can then modify this file and add your own custom scripts to facilitate your development process and share knowledge across your team. For example, add scripts to run database migrations, reset local environments, run static analysis tools, and so on. Think about how much easier it will be to onboard a teammate or new developer :)
+Each **Kool Preset** auto-generates a **kool.yml** file with prebuilt scripts tailored for the specific framework or stack. You can modify this file and incorporate your custom scripts to streamline your development process and share knowledge across your team. For instance, include scripts to run database migrations, reset local environments, perform static analysis, and more. Consider the ease with which your team can onboard new members or developers with this organized and standardized approach.
 
 ```yaml
 # ./kool.yml for the Laravel preset
@@ -233,3 +243,21 @@ $ kool start
 Pretty _kool_, right?
 
 > If you like what we're doing, show your support for this new open source project by [**starring us on GitHub**](https://github.com/kool-dev/kool)!
+
+## A Better Cloud Deployment Experience
+
+Elevating your cloud deployment experience is a core aspect of **Kool**. Beyond revolutionizing local development environments, **Kool** seamlessly extends its benefits to the cloud, providing a streamlined and efficient deployment process.
+
+### Kool Cloud Integration
+
+**Kool.dev Cloud** is the gateway to a simplified cloud deployment journey. Seamlessly integrated with **Kool**, it offers a platform where you can effortlessly deploy your containerized applications. By leveraging the power of `kool cloud setup`, you can seamlessly transition from local development to cloud deployment, ensuring consistency and minimizing friction in the process.
+
+### Streamlined Deployments with Kool Presets
+
+Each **Kool Preset** not only optimizes your local development but also facilitates cloud deployment. We are building deploying recipes for each Preset so you can leverage Kool.dev Cloud without the usual hassle and without fighting with Kubernetes.
+
+### Fine-Tuning Deployment Workflows
+
+**Kool** understands that flexibility is key. While **Kool Presets** together with `kool cloud setup` offer out-of-the-box deployment solutions, you have the freedom to fine-tune and customize deployment workflows to match your specific needs. Leverage the capabilities of **kool.yml** to add bespoke scripts that cater to your deployment requirements.
+
+Discover a better way to deploy your containerized applications to the cloud with **Kool**, ensuring a consistent and efficient cloud deployment experience.

docs/03-Presets/0-About-Presets.md

@@ -0,0 +1,32 @@
+# Kool Presets: Streamlining Your Development Experience
+
+Kool Presets are curated configurations tailored to popular stacks and frameworks, designed to jumpstart your projects with efficiency and ease. Whether you're working with Node.js, PHP, JavaScript, or other technologies, Kool Presets provide battle-tested configurations, saving you from the hassle of reinventing the wheel for each new project.
+
+These presets encapsulate best practices, allowing you to focus on your code rather than spending time on intricate setup processes. From popular backend frameworks like Laravel and NestJS to frontend powerhouses like Next.js and NuxtJS, Kool Presets cover a spectrum of technologies, offering you a head start in building robust and scalable applications.
+
+By leveraging Kool Presets, you not only reduce the learning curve associated with configuring different environments but also ensure consistency across your projects. With Kool, enjoy a unified and efficient development experience, whether you're a solo developer seeking a quick setup or a team collaborating on complex projects. Explore the available presets and elevate your development workflow with Kool Presets today.
+
+# Popular Presets
+
+## 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)

docs/25-Upgrade-Guide/0-Upgrading-Kool.md

@@ -0,0 +1,20 @@
+# Upgrade Guide
+
+## Note on Versioning
+
+**Kool** adheres to *Semantic Versioning (SemVer)* and is committed to maintaining backward compatibility, minimizing the potential for disruptive changes and multi-step upgrades.
+
+## Upgrading to 3.x
+
+The release of major version 3.x introduces a few breaking changes. Please review and adjust your projects accordingly.
+
+### Changes to `kool.deploy.yml`: Now `kool.cloud.yml`
+
+It is recommended to rename your configuration file for **Kool.dev Cloud** from `kool.deploy.yml` to `kool.cloud.yml`. Although the old naming convention remains functional, it has been deprecated and will be removed in future releases.
+
+### Building Images for Deployment with `services.<service>.build`
+
+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).