kool

The kool cloud subcommand provides a suite of APIs to interact with Kool.dev Cloud. It allows you to deploy applications, access running services, and tail logs from your cloud-deployed environments.

Common operations include:

• Deploying a local application to the cloud.
• Destroying a cloud environment.
• Executing commands inside a running service container.
• Viewing logs for running service containers.
• Setting up local configuration files for deployment.

kool cloud deploy

The daemons configuration allows you to define processes that run as additional containers using the same image as your main service. This is ideal for queue workers or background tasks.

Daemons can also expose specific ports using the expose key, which can then be routed via the public.path configuration.

services:
  app:
    daemons:
      - command: [ start-queues, arg1, arg2 ]
      - command: [ run-websocker-server, --port=3000 ]
        expose: 3000

Kool Presets are curated, battle-tested configurations designed to jumpstart development for specific technology stacks and frameworks. Instead of manually configuring environments, you can use a preset to encapsulate best practices for your chosen stack. This ensures consistency across projects and reduces the time spent on intricate setup processes.

Presets are available for various backend frameworks (e.g., Laravel, NestJS), frontend frameworks (e.g., Next.js, NuxtJS), and other technologies (e.g., Hugo, WordPress).

The kool.yml file acts as a task helper. Instead of writing custom shell scripts, you can define scripts under the scripts key and execute them using kool run <SCRIPT_NAME>.

Example kool.yml structure:

scripts:
  mysql: kool exec -e MYSQL_PWD=$DB_PASSWORD database mysql -u $DB_USERNAME $DB_DATABASE
  npm: kool exec app npm
  npx: kool exec app npx
  php: kool exec app php
  wp: kool exec app wp

Usage:

• To run the WordPress CLI: kool run wp --info (which executes kool exec app wp --info).
• To run database commands: kool run mysql.

All Kool.dev Cloud environments run under HTTPS. Kool.dev Cloud automatically manages TLS certificates using the Let'sEncrypt engine (via K8S certmanager).

For any domain to receive a valid certificate, the domain must point to the Kool.dev Cloud IP addresses. This requirement is particularly critical for custom domains, as the Let'sEncrypt process relies on the HTTP01 Acme challenge, which requires successful DNS resolution to the Kool.dev Cloud infrastructure.

Hooks allow you to execute commands in standalone containers using your deployment image either before or after a deployment.

• before: Commands executed right before a new deployment. Note: This can only be used after at least one successful deployment has occurred.
• after: Commands executed right after a new deployment finishes (e.g., running database migrations).

services:
  app:
    before:
      - script_to_run.sh
    after:
      - [ run-database-migrations, arg1, arg2 ]

CPU and Memory Resources

Kool.dev Cloud uses a simple scaling model for container resource allocation. Each size doubles the limits of the previous one:

Persistent Storage

Kool.dev Cloud supports persisting folders across deployments, which is useful for migrating legacy applications that rely on local file storage into a containerized environment.

The kool.yml file acts as a task runner. You can define single-line commands or sequences of commands under the scripts key and execute them using kool run <SCRIPT_NAME>.

A typical NestJS kool.yml includes:

• setup: A sequence to prepare the environment (copying .env, installing deps).
• npm / npx: Helpers to run commands inside the app service.
• nest: A helper to run the NestJS CLI via npx inside the app container.
• mysql / psql: Helpers to open a database client session directly in the database container.

# Example kool.yml structure
scripts:
  setup:
    - cp .env.dist .env
    - kool docker kooldev/node:20 npm install

  npm: kool exec app npm
  npx: kool exec app npx
  nest: kool run npx @nestjs/cli
  mysql: kool exec database mysql
  psql: kool exec database psql

The kool.yml file acts as a task helper, allowing you to define and run custom scripts instead of writing manual shell scripts. Scripts can be single-line commands or sequences of commands.

Defining scripts

In kool.yml, add your commands under the scripts key.

• Single-line command: Maps a name to a specific command (e.g., composer: kool exec app composer).
• Sequence of commands: Uses a list format to execute multiple commands in order.

Running scripts

Use the kool run <SCRIPT_NAME> command to execute your defined tasks.

Example kool.yml structure:

scripts:
  composer: kool exec app composer
  php: kool exec app php

  setup:
    - kool start
    # - add more setup commands

The kool preset command generates a kool.yml file in your project root. This file acts as a task helper, allowing you to define and run custom scripts instead of writing manual shell scripts.

Running Scripts

Use the kool run <SCRIPT_NAME> command to execute a script defined in kool.yml.

• Single-line commands: Defined as a string (e.g., adonis: kool exec app adonis).
• Multi-line sequences: Defined as a list of commands executed in order (e.g., the setup script).

Default AdonisJs Scripts

Your kool.yml will typically include:

scripts:
  adonis: kool exec app adonis
  npm: kool exec app npm
  npx: kool exec app npx

  setup:
    - kool docker kooldev/node:20 npm install
    - kool start

To run the initial setup (installing dependencies and starting the environment), use:

kool run setup

The kool.yml file acts as a task helper. Instead of writing custom shell scripts, you can define commands under the scripts key and execute them using kool run <SCRIPT_NAME>.

The setup script

When using the Laravel Octane preset, kool run setup performs the following sequence:

1. Copies .env.example to .env.
2. Starts the Docker environment.
3. Installs Composer dependencies.
4. Generates the APP_KEY in .env.
5. Builds Node packages and assets.

CAUTION: Running kool run setup will reset your .env file by overwriting it with the contents of .env.example.

kool run setup
kool run artisan --help