This is an automated email from the ASF dual-hosted git repository.
tsato pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
The following commit(s) were added to refs/heads/main by this push:
new f8f1b0f doc(cli): add documentation for kamel local subcommands
f8f1b0f is described below
commit f8f1b0f59af4f54b90704007c1b28697394dcdf0
Author: Tadayoshi Sato <sato.tadayo...@gmail.com>
AuthorDate: Tue Feb 22 17:25:31 2022 +0900
doc(cli): add documentation for kamel local subcommands
Fix #2490
---
docs/modules/ROOT/nav.adoc | 1 +
docs/modules/ROOT/pages/running/local.adoc | 172 +++++++++++++++++++++++++++
docs/modules/ROOT/pages/running/running.adoc | 7 +-
3 files changed, 179 insertions(+), 1 deletion(-)
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 4e13dfe..5add886 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -25,6 +25,7 @@
* xref:running/running.adoc[Run an Integration]
** xref:running/dev-mode.adoc[Developer mode]
** xref:running/run-from-github.adoc[Run from GitHub]
+** xref:running/local.adoc[Run Locally]
** xref:tutorials/tutorials.adoc[Examples]
* xref:configuration/configuration.adoc[Configuration]
** xref:configuration/build-time-properties.adoc[Build time properties]
diff --git a/docs/modules/ROOT/pages/running/local.adoc
b/docs/modules/ROOT/pages/running/local.adoc
new file mode 100644
index 0000000..ad70222
--- /dev/null
+++ b/docs/modules/ROOT/pages/running/local.adoc
@@ -0,0 +1,172 @@
+[[running-locally]]
+= Running Locally
+
+While Camel K is a framework for running integrations on a cloud, it also
allows you to run your integration locally during development.
+
+NOTE: Not all features are available for the local running. See
<<running-locally-limitations>>.
+
+== Available Commands
+
+Available subcommands for `kamel local` are:
+
+.Available Commands
+[cols="1m,2,2m"]
+|===
+|Name |Description |Example
+
+|build
+|Build integration images locally
+|kamel local build
+
+|inspect
+|Generate dependencies list given integration files
+|kamel local inspect
+
+|run
+|Run integration locally
+|kamel local run
+
+|===
+
+To run an integration locally:
+
+[source,console]
+----
+$ kamel local run hello.groovy
+----
+
+To inspect which dependencies are resolved in the integration you are
developing:
+
+[source,console]
+----
+$ kamel local inspect hello.groovy
+----
+
+For more information on what options each subcommand accepts, run it with the
`--help` option:
+
+[source,console]
+----
+$ kamel local <subcommand> --help
+----
+
+== Local Build
+
+The `local build` subcommand can build integration images locally for
development purposes. It provides three main use cases:
+
+1. <<running-locally-build-integration,Build an integration image locally>>
+2. <<running-locally-build-base-image,Build only a base image locally>>
+3. <<running-locally-create-directory,Create a directory structure for an
integration>>
+
+[CAUTION]
+====
+It is not intended to be a feature for packaging integrations for later
deployment on a Kubernetes cluster. It is purely for development and running on
Docker.
+
+To package an integration, use `kamel kit create` to create an
`IntegrationKit` on a cluster as a way to package your self-contained
resources. Then you can move those kits and reuse them on another cluster.
+====
+
+[[running-locally-build-integration]]
+=== Building an integration
+
+To build an integration image locally, you at lease need to specify an image
name with the `--image` option in addition to the integration files you want to
build.
+
+[source,console]
+----
+$ kamel local build --image=docker.io/myrepo/hello hello.groovy
+----
+
+[[running-locally-build-base-image]]
+=== Building a base image
+
+You can also build only a base image (`integration-base-image`) locally that
all integration images are based on. It requires two options, `--base-image`
and `--container-registry`, and no arguments.
+
+[source,console]
+----
+$ kamel local build --base-image --container-registry=docker.io/myrepo
+----
+
+It will create a `docker.io/myrepo/integration-base-image:latest` image
locally.
+
+[[running-locally-create-directory]]
+=== Creating a directory structure
+
+You can create a directory structure with the integration files: property
files, routes, and dependencies.
+
+[source,console]
+----
+$ kamel local build --integration-directory <dir-name> file1.yaml file2.java
file3.groovy
+----
+
+The directory will be created in the parent directory of where the command was
invoked and will contain the following directory structure:
+----
+<dir-name>/
+├── dependencies/
+├── properties/
+└── routes/
+----
+
+The `properties`, `routes`, and `dependencies` subdirectories will contain the
respective integration files.
+
+For convenience you can output just the dependencies with
`--dependencies-only` as follows:
+[source,console]
+----
+$ kamel local build --integration-directory <dir-name> --dependencies-only
file1.yaml file2.java file3.groovy
+----
+
+The created integration directory can later be run with the `local run`
subcommand. See <<running-locally-run-directory>>.
+
+== Local Run
+
+You can run integrations locally with the `local run` subcommand.
+
+[source,console]
+----
+$ kamel local run hello.groovy
+----
+
+[[running-locally-run-image]]
+=== Running with an image
+
+You can also run an integration from an image which has been already built
with the `local build` subcommand:
+
+[source,console]
+----
+$ kamel local run --image=docker.io/myrepo/hello
+----
+
+You can also build and run an image all at once with the `--containerize`
option:
+
+[source,console]
+----
+$ kamel local run --containerize --image=docker.io/myrepo/hello hello.groovy
+----
+
+[[running-locally-run-directory]]
+=== Running with an integration directory
+
+The `local run` subcommand can take as input an integration directory
constructed by `local build`.
+
+NOTE: Only full integration directories can be processed; i.e. directories
created with `--dependencies-only` are not supported.
+
+`local run` can use an integration directory as input and run the integration
locally:
+[source,console]
+----
+$ kamel local run --integration-directory <dir-name>
+----
+
+`local run` can use an integration directory and run the integration within a
container:
+[source,console]
+----
+$ kamel local run --integration-directory <dir-name> --containerize
--network=host --image <image-name>
+----
+
+For now, if route files contain modeline options which depend on lazily
evaluated environment variables (for example, `\[[env:ENV_VAR]]`) then the
command above will need to specify the environment variable explicitly like so:
+[source,console]
+----
+$ kamel local run --integration-directory <dir-name> --env ENV_VAR
+$ kamel local run --integration-directory <dir-name> --containerize
--network=host --image <image-name> --env ENV_VAR
+----
+
+[[running-locally-limitations]]
+== Limitations
+
+* Since there is no platform to leverage, traits are not usable for `kamel
local` commands. Right now, if you specify any traits in the
xref:cli/modeline.adoc[modeline] an integration will not run locally throwing
an error.
diff --git a/docs/modules/ROOT/pages/running/running.adoc
b/docs/modules/ROOT/pages/running/running.adoc
index 1c7299f..aca8eee 100644
--- a/docs/modules/ROOT/pages/running/running.adoc
+++ b/docs/modules/ROOT/pages/running/running.adoc
@@ -28,7 +28,7 @@ You can run it on the cluster by executing:
kamel run hello.groovy
```
-Integrations can be written in multiple languages. We are collecting examples
in our https://github.com/apache/camel-k/[Github repository].
+Integrations can be written in multiple languages. We are collecting examples
in our https://github.com/apache/camel-k/[GitHub repository].
[[monitoring-integration]]
== Monitoring the application status
@@ -57,6 +57,11 @@ kamel logs hello
Camel K provide a very nice **dev mode** feature that will allow you to apply
any change to your Integration code reactively. Check out the
xref:running/dev-mode.adoc[Camel K dev mode]
+[[running-integration-locally]]
+== Running an Integration locally
+
+During development, you can also run your integration locally with `kamel
local` sub commands. Check out xref:running/local.adoc[Running Locally] for how
to use the commands.
+
[[no-cli-integration]]
== Running an Integration without CLI
