This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch feature/CAMEL-23722-cli-docs-restructure in repository https://gitbox.apache.org/repos/asf/camel.git
commit 2f2a37aadeb16b4f4efcd9e2c156b09222e0ec73 Author: Claus Ibsen <[email protected]> AuthorDate: Tue Jun 9 18:12:08 2026 +0200 CAMEL-23722: Split Running Camel into essentials and Tips page Move power-user features (clipboard, GitHub routes, stub, inline code, interactive prompt, HTTP upload, Maven config, Maven project migration) to new Tips and Recipes sub-page. Running Camel now focuses on what new users need: dev mode, properties, profiles, platform-http, dependencies, runtimes, and Kamelets. Remove deprecated Pipes/bind sections and trim verbose prose. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: Claus Ibsen <[email protected]> --- docs/user-manual/modules/ROOT/nav.adoc | 1 + .../modules/ROOT/pages/camel-jbang-running.adoc | 940 +++------------------ .../modules/ROOT/pages/camel-jbang-tips.adoc | 222 +++++ .../modules/ROOT/pages/camel-jbang.adoc | 8 +- 4 files changed, 329 insertions(+), 842 deletions(-) diff --git a/docs/user-manual/modules/ROOT/nav.adoc b/docs/user-manual/modules/ROOT/nav.adoc index 920439aac4b8..45a6bb106090 100644 --- a/docs/user-manual/modules/ROOT/nav.adoc +++ b/docs/user-manual/modules/ROOT/nav.adoc @@ -15,6 +15,7 @@ *** xref:camel-jbang-transforming.adoc[Data Transformation] *** xref:camel-jbang-managing.adoc[Managing Integrations] *** xref:camel-jbang-projects.adoc[Projects and Catalog] +*** xref:camel-jbang-tips.adoc[Tips and Recipes] *** xref:camel-jbang-configuration.adoc[Configuration] *** xref:jbang-commands/camel-jbang-commands.adoc[Command Reference] *** xref:camel-jbang-launcher.adoc[Camel CLI Launcher] diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-running.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-running.adoc index 665fa18fe79c..b30d7824b5ab 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang-running.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-running.adoc @@ -1,738 +1,254 @@ = Camel CLI - Running Camel -This page covers the many ways to run Camel integrations using the CLI, from interactive prompts to dev mode with hot reload. +This page covers the essential options for running Camel integrations — dev mode, +properties, profiles, HTTP endpoints, dependencies, and runtimes. + +For advanced techniques like running from GitHub, clipboard, or stub components, +see xref:camel-jbang-tips.adoc[Tips and Recipes]. == Dev mode with live reload -You can enable dev mode that comes with live reload of the route(s) when the source file is updated (saved), -using the `--dev` options as shown: +Run with `--dev` to get automatic reload when you edit and save your source files: [source,bash] ---- camel run foo.yaml --dev ---- -Then, while the Camel integration is running, you can update the YAML route and update when saving. +This works for all DSLs (YAML, Java, XML). -This works for all DSLs, even java, so you can do: +NOTE: Live reload is for development purposes. If you encounter JVM class loading issues, +restart the integration. Java files are not live-reloadable in Spring Boot runtime. -[source,bash] ----- -camel run hello.java --dev ----- +=== Source directory -NOTE: The live reload is meant for development purposes, and if you encounter problems with reloading -such as JVM class loading issues, then you may need to restart the integration. Java files cannot -be supported in Spring Boot runtime since they have to be recompiled to trigger a restart. - -You can also run dev mode when running Camel with `--source-dir`, such as: +Use `--source-dir` for more flexibility — Camel watches the entire directory (including subfolders) +and automatically detects new, modified, and deleted files: [source,bash] ---- camel run --source-dir=mycode --dev ---- -This starts Camel where it will load the files from the _source dir_ (also subfolders). -And in _dev mode_ then you can add new files, update existing files, and delete files, and Camel -will automatically hot-reload on the fly. - -Using _source dir_ is more flexible than having to specify the files in the CLI as shown below: - -[source,bash] ----- -camel run mycode/foo.java mycode/bar.java --dev ----- - -In this situation, then Camel will only watch and reload these two files (foo.java and bar.java). -So, for example, if you add a new file cheese.xml, then this file is not reloaded. On the other hand, -if you use `--source-dir` then any files in this directory (and subfolders) are automatic detected -and reloaded. You can also delete files to remove routes. +Without `--source-dir`, Camel only watches the specific files you listed on the command line. -NOTE: You cannot use both files and source dir together. -The following is not allowed: `camel run abc.java --source-dir=mycode`. +NOTE: You cannot combine files and source dir: `camel run abc.java --source-dir=mycode` is not allowed. === Live reload of resource files -When `--dev` is used, Camel also disables `contentCache` on resource-based components (such as -`xslt`) whose default is `true`, so that edits to resource files are picked up on the next message -without having to restart the route. +In dev mode, Camel disables `contentCache` on resource-based components (such as `xslt`) +so that edits to resource files are picked up on the next message without restarting. -This is driven by `camel.main.routesReloadEnabled` (set automatically by `--dev`). User properties -(e.g. `camel.component.xslt.contentCache=true`) and explicit endpoint/URI settings are always -respected: set `contentCache=true` to keep caching even in dev mode. +User properties (e.g. `camel.component.xslt.contentCache=true`) and explicit endpoint settings +are always respected. === Loading new routes into existing Camel *Available as of Camel 4.17* -The `camel cmd load` command can be used to load new route(s) into an existing running Camel CLI application. -For example during development to inject a new route for experimentation. This can also be used as part -of testing scenarios using Citrus with the xref:camel-jbang-test.adoc[Camel CLI Test] plugin. - -For example to load `bar.java` route into a Camel application: +The `camel cmd load` command loads new routes into a running Camel application: [source,bash] ---- camel cmd load --source=bar.java ---- -You can load any of the DSLs such as Java, XML, or YAML. - -IMPORTANT: Assign _ids_ to your routes so the `load` command would detect a previous loaded route (when you update), -to avoid adding the same route as a duplicate. - -TIP: There is a `--restart` option to tell Camel to restart all routes after the new route is loaded. - -=== Uploading files to source directory via HTTP - -When running Camel CLI with `--source-dir`, `--console` and `--dev` (reloading) then you can -change the source files on-the-fly by copying, modifying or deleting the files in the source directory. - -This can also be done via HTTP using the `q/upload/:filename` HTTP endpoint using PUT and DELETE verbs. - -Suppose that you run Camel CLI with: - -[source,bash] ----- -camel run --source-dir=mycode --console --dev ----- - -Then you can upload or modify a source file named `bar.java` you can send a PUT request via curl: - -[source,bash] ----- -curl -X PUT http://0.0.0.0:8080/q/upload/bar.java --data-binary "@bar.java" ----- - -Or via: - -[source,bash] ----- -curl -T bar.java http://0.0.0.0:8080/q/upload/bar.java ----- - -To send the data via PUT, then the file body can be included when using `Content-Type: application/x-www-form-urlencoded`: - -For example, from a CURL `--trace-ascii log.txt`: - -[source,text] ----- -0000: PUT /q/upload/bar.java HTTP/1.1 -0021: Host: 0.0.0.0:8080 -0035: User-Agent: curl/7.87.0 -004e: Accept: */* -005b: Content-Length: 385 -0070: Content-Type: application/x-www-form-urlencoded -00a1: -=> Send data, 385 bytes (0x181) -0000: // camel-k: language=java..import org.apache.camel.builder.Route -0040: Builder;..public class bar extends RouteBuilder {.. @Override -0080: . public void configure() throws Exception {.. // Writ -00c0: e your routes here, for example:. from("timer:java?period -0100: ={{time:1000}}"). .setBody(). .simple( -0140: "XXXCamel from ${routeId}"). .log("${body}");. }.} -0180: . -== Info: Mark bundle as not supporting multiuse -<= Recv header, 17 bytes (0x11) -0000: HTTP/1.1 200 OK -<= Recv header, 19 bytes (0x13) -0000: content-length: 0 -<= Recv header, 2 bytes (0x2) -0000: -== Info: Connection #0 to host 0.0.0.0 left intact ----- - -To delete one or more files, you use the DELETE verb, such as: - -[source,bash] ----- -curl -X DELETE http://0.0.0.0:8080/q/upload/bar.java ----- - -You can also use wildcards ('*') to delete all .java files: - -[source,bash] ----- -curl -X DELETE http://0.0.0.0:8080/q/upload/*.java ----- - -Or to delete everything - -[source,bash] ----- -curl -X DELETE http://0.0.0.0:8080/q/upload/* ----- - -== Running Routes from source directory - -You can also run dev mode when running Camel with `--source-dir`, such as: - -[source,bash] ----- -camel run --source-dir=mycode ----- - -This starts Camel where it will load the files from the _source dir_ (also subfolders). - -== Running Route from input parameter - -For very small Java routes then it is possible to provide the route as CLI argument, as shown below: - -[source,bash] ----- -camel run --code='from("kamelet:beer-source").to("log:beer")' ----- - -This is very limited as the CLI argument is a bit cumbersome to use than files. - -- Java DSL code is only supported -- Code wrapped in single quote, so you can use double quote in Java DSL -- Code limited to what literal values possible to provide from the terminal and JBang. -- All route(s) must be defined in a single `--code` parameter. - -NOTE: Using `--code` is only usable for very quick and small prototypes. - -From *Camel 4.7* onwards the `--code` parameter can also refer to a `.java` source file, -that are not wrapped in a `public class` which makes it possible to quickly try a prototype -with some Camel java based routes such as the following stored in a file named `quick.java`: - -[source,java] ----- -from("timer:java?period=1000") - .setBody() - .simple("Hello Quick Camel from ${routeId}") - .log("${body}"); ----- - -Then you can run this route via: - -[source,bash] ----- -camel run --code=quick.java ----- - -NOTE: You cannot use `--dev` to hot-reload this on code changes. - -== Running Route with user interactive prompt for placeholder values - -You can create Camel integrations that makes it possible for the user to quickly enter placeholder values from command prompt. - -For example, given the following route: - -[source,java] ----- -import org.apache.camel.builder.RouteBuilder; - -public class foo extends RouteBuilder { - - @Override - public void configure() throws Exception { - from("timer:java?period={{time:1000}}") - .setBody() - .simple("Hello Camel from {{you}}") - .log("${body}"); - } -} ----- - -Then if you run this with: - -[source,bash] ----- -camel run foo.java ----- - -You will have an exception on startup about the missing value -[source,text] ----- -Caused by: java.lang.IllegalArgumentException: Property with key [you] not found in properties from text: Hello Camel from {{you}}` ----- - -However, you can then run in prompt mode as follows: - -[source,bash] ----- -camel run foo.java --prompt ----- - -And Camel will now prompt in the terminal for you to enter values for the placeholders: - -[source,bash] ----- -2023-12-15 21:46:44.218 INFO 15033 --- [ main] org.apache.camel.main.MainSupport : Apache Camel (JBang) 4.7.0 is starting -2023-12-15 21:46:44.331 INFO 15033 --- [ main] org.apache.camel.main.MainSupport : Using Java 17.0.5 with PID 15033. Started by davsclaus in /Users/davsclaus/workspace/deleteme/prompt -2023-12-15 21:46:45.360 INFO 15033 --- [ main] mel.cli.connector.LocalCliConnector : Management from Camel CLI enabled -Enter optional value for time (1000): -Enter required value for you: Jack -2023-12-15 21:46:55.239 INFO 15033 --- [ main] el.impl.engine.AbstractCamelContext : Apache Camel 4.7.0 (foo) is starting -2023-12-15 21:46:55.323 INFO 15033 --- [ main] g.apache.camel.main.BaseMainSupport : Property-placeholders summary -2023-12-15 21:46:55.323 INFO 15033 --- [ main] g.apache.camel.main.BaseMainSupport : [prompt] you=Jack -2023-12-15 21:46:55.341 INFO 15033 --- [ main] el.impl.engine.AbstractCamelContext : Routes startup (started:1) ----- - -From the snippet above, Camel CLI had two prompts. First for the `time` which has a default value of `1000` so you can just press ENTER to accept the default value. -And for `you` a value must be entered, and we entered `Jack` in this example. - -You may want to use this for Camel prototypes where you want the user to be able to enter custom values quickly. -Those values can of course be pre-configured in `application.properties` as well. - -== Stub components that should not be active - -Sometimes you need to troubleshoot an existing integration and is given some Camel code (routes). -These routes may use different components, and those components may be tricky to run as they are configured -in a custom way, or need connection to servers you may not have access to. - -You can run Camel CLI by stubbing those components (or all of them). - -For example, suppose you need access to a JMS broker in the given route below. - -[source,java] ----- -from("jms:inbox") - .log("Incoming order") - .to("bean:transform") - .log("After transformation") - .to("jms:process"); ----- - -Then you can run this by stub the `jms` component by: +IMPORTANT: Assign _ids_ to your routes so the `load` command detects previously loaded routes +and avoids duplicates. -[source,bash] ----- -camel run syncToDatabase.java --stub=jms ----- +TIP: Use `--restart` to restart all routes after the new route is loaded. -Then Camel will not start up the JMS component but replace it with the `stub` component, but keep the actual endpoint URIs. - -You can then simulate sending messages to Camel with the `cmd send` command: - -[source,bash] ----- -camel cmd send --body='Something here' ----- - -Which then will send the message to the incoming endpoint in the route, i.e. `jms:inbox` which has been stubbed. - -You can also stub a specific endpoint by providing the full uri, such as: - -[source,bash] ----- -camel run syncToDatabase.java --stub=jms:inbox ----- - -Then only the `jms:inbox` endpoint is stubbed. - -TIP: You can stub multiple components separated by comma, such as `--stub=jms,sql` - -You can also use `--stub=all` to stub all components, or `--stub=remote` to stub only -remote components (components that connect to external systems such as messaging brokers, databases, cloud services, etc.). -The `remote` flag uses the Camel catalog to determine which components are remote, so it automatically -handles new components without needing a hardcoded list. - -[source,bash] ----- -camel run syncToDatabase.java --stub=remote ----- - -Camel CLI comes with the `camel cmd stub` command that allows to list all endpoints that -has been stubbed, and also browse any messages that are currently present in their internal queues. -A stub endpoint is based on the `seda` component. - -[source,bash] ----- -camel cmd stub ----- +== Using properties -And to browse the messages: +Set properties with `--property` or load them from a file with `--properties`: [source,bash] ---- -camel cmd stub --browse +camel run foo.yaml --property=my-key=my-value +camel run foo.yaml --properties=/var/my-app/config.properties ---- -== Using properties - -To set properties when running a route, you can use the `--property` or `--properties` parameter from `camel run` command: +NOTE: Use the `=` sign directly after `--property` (no space). -* `--property`: sets individual parameters, example: `--property=my-key=my-value`, you have to add more `--property` in case you need more parameters. -* `--properties`: loads a properties file from the local filesystem, example: `--properties=/var/my-app/config.properties`. - -NOTE: You have to use the `=` sign right after the `--property`, as in the examples above. - -If both parameters are used, the properties will be merged in a single `application.properties` file. +If both are used, the properties are merged into a single `application.properties` file. [#_using_profiles] == Using profiles *Available from Camel 4.5* -Camel CLI comes with three sets of profiles - -- `dev`:for development (default) -- `test`:for testing (currently same as production) -- `prod`:for production +Camel CLI has three profiles: -The developer profile will pre-configure Camel CLI with a number of developer assisted features when -running Camel. For example, tracing messages during routing, additional metrics collected, and more. -This is useful during development and also enhanced the Camel CLI tool. +- `dev` — development (default), enables tracing, extra metrics, and developer-focused features +- `test` — testing (currently same as production) +- `prod` — production -However, you may want to run Camel CLI in a production-like scenario, which you can do with: +Run with a specific profile: [source,bash] ---- camel run hello.java --profile=prod ---- -You can have profile-specific configuration in configuration files using the naming style `application-<profile>.properties`, -such as in the following: - -- `application.properties`: common configuration that is always in use (default). -- `application-dev.properties`: developer specific configuration for the `dev` profile. -- `application-prod.properties`: developer specific configuration for the `prod` profile. - -The profile-specific configuration will override values in the common configuration. - -NOTE: Since Camel 4.21, the `camel run` and `camel export` commands auto-detect `application.properties` -(and profile-specific variants such as `application-prod.properties`) in the current directory. -You no longer need to list them explicitly on the command line. - -== Run from clipboard - -You can also run Camel routes directly from the OS clipboard. This allows copying some code, -and then quickly run this. - -The syntax is - -[source,bash] ----- -camel run clipboard.<extension> ----- - -Where `<extension>` is what kind of file the content of the clipboard is, such as `java`, `xml`, or `yaml` etc. - -For example, you can copy this to your clipboard and then run it afterward: - -[source,xml] ----- -<route> - <from uri="timer:foo"/> - <log message="Hello World"/> -</route> ----- - -[source,bash] ----- -camel run clipboard.xml ----- - -=== Run and reload from clipboard +Use profile-specific configuration files: -*Available since Camel 4.2* +- `application.properties` — common configuration (always loaded) +- `application-dev.properties` — dev profile overrides +- `application-prod.properties` — production profile overrides -It is also possible to run from clipboard in _reload_ mode as shown: +NOTE: Since Camel 4.21, `camel run` and `camel export` auto-detect `application.properties` +(and profile-specific variants) in the current directory. -[source,bash] ----- -camel run clipboard.xml --dev ----- - -Then you can quickly make changes and copy to clipboard, and Camel CLI will update while running. - -== Running routes hosted on GitHub - -You can run a route hosted on GitHub using Camels xref:components:others:resourceresolver-github.adoc[GitHub] resource loader. +== Using the platform-http component -For example, to run one of the Camel Kamelets examples, you can do: +When a route uses `platform-http`, Camel CLI automatically starts a VertX HTTP server on port 8080: -[source,bash] +[source,yaml] ---- -camel run github:apache:camel-kamelets-examples:jbang/hello-java/Hey.java +- route: + from: + uri: platform-http:/hello + steps: + - set-body: + constant: "Hello World" ---- -You can also use the `https` URL for GitHub. For example, you can browse the examples from a web-browser and -then copy the URL from the browser window and run the example with Camel CLI: - [source,bash] ---- -camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/hello-java ----- - -You can also use wildcards (i.e. `*`) to match multiple files, or you can run all files starting with rou* - -[source,bash] ----- -camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/languages/rou* +camel run server.yaml ---- -=== Running routes from GitHub gists - -Using gists from GitHub is a quick way to share small Camel routes that you can easily run. - -For example, to run a gist, you can execute: - [source,bash] ---- -camel run https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92 +$ curl http://localhost:8080/hello +Hello World% ---- -A gist can contain one or more files, and Camel CLI will gather all relevant files, so a gist -can contain multiple routes, properties files, Java beans, etc. +NOTE: Camel CLI only supports `platform-http` for HTTP serving and REST DSL. +It does not support `camel-servlet` or `camel-jetty`. -== Downloading routes hosted on GitHub - -We have made it easy for Camel CLI to download existing examples from GitHub to local disk, -which allows for modifying the example and to run locally. +== Adding custom JARs -All you need to do is to copy the https link from the web browser. -For example, you can download the _dependency injection_ example by: +Camel CLI automatically detects and downloads dependencies for Camel components. +For 3rd-party JARs, use `--dep` with Maven GAV syntax: [source,bash] ---- -camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection +camel run foo.java --dep=com.foo:acme:1.0 ---- -Then the files (not subfolders) are downloaded to the current directory. -The example can then be run locally with: +For Camel dependencies, use the shorthand syntax: [source,bash] ---- -camel run * +camel run foo.java --dep=camel-saxon ---- -You can also download to a new folder using the `--directory` option, for example, to download to a folder named _myproject_, -you would do: +Multiple dependencies can be separated by comma: [source,bash] ---- -camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection --directory=myproject +camel run foo.java --dep=camel-saxon,com.foo:acme:1.0 ---- -You can also run in dev mode, to hot-deploy on source code changes. - -[source,bash] ----- -camel run * --dev ----- +== Using 3rd-party Maven repositories -You can also download a single file, such as one of the Camel Kamelets examples: +By default, Camel CLI downloads from the local Maven repository and Maven Central. +To add other repositories: [source,bash] ---- -camel init https://github.com/apache/camel-kamelets-examples/blob/main/jbang/hello-yaml/hello.camel.yaml +camel run foo.java --repos=https://packages.atlassian.com/maven-external ---- -=== Downloading routes form GitHub gists +TIP: Separate multiple repositories with commas. -You can also download files from gists easily as shown: +You can also configure repositories in `application.properties`: -[source,bash] ----- -camel init https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92 ----- - -This will then download the files to local disk, which you can run afterward: - -[source,bash] +[source,properties] ---- -camel run * +camel.jbang.repos=https://packages.atlassian.com/maven-external ---- -You can also download to a new folder using the `--directory` option, for example, to download to a folder named _foobar_, -you would do: +Or set a global default via environment variable: [source,bash] ---- -camel init https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92 --directory=foobar +export JAVA_TOOL_OPTIONS="-Dcamel.extra.repos=repo1=https://repo1.example.com/maven2,repo2=https://repo2.example.com/releases"; ---- -== Running Pipes +== Downloading JARs over the internet -Camel also supports running pipes, which represent Kubernetes custom resources following a specific CRD format (Kubernetes Custom Resource Definitions). +Camel CLI automatically resolves and downloads dependencies in this order: -For example, a pipe file named `joke.yaml`: +1. Local Maven repository (`~/.m2/repository`) +2. Maven Central +3. Custom 3rd-party repositories +4. Repositories from `~/.m2/settings.xml` -[source,yaml] ----- -#!/usr/bin/env jbang camel@apache/camel run -apiVersion: camel.apache.org/v1 -kind: Pipe -metadata: - name: joke -spec: - source: - ref: - kind: Kamelet - apiVersion: camel.apache.org/v1 - name: chuck-norris-source - properties: - period: 2000 - sink: - ref: - kind: Kamelet - apiVersion: camel.apache.org/v1 - name: log-sink - properties: - show-headers: false ----- - -Can be run with camel: +To disable automatic downloading: [source,bash] ---- -camel run joke.yaml +camel run foo.java --download=false ---- -=== Binding Kamelets in a pipe - -WARNING: The bind command is deprecated from Camel 4.19 onwards - -Camel CLI is able to create the Pipe custom resource for you. -You can use the `bind` command to specify a source and a sink that should be set in the pipe. -As a result, Camel CLI will create a proper Pipe custom resource for you. +== Running with Spring Boot or Quarkus -The command expects a file name as command argument and provides several options to define the source and the sink that should be used in the pipe. +Camel CLI can run integrations using Spring Boot or Quarkus runtimes: [source,bash] ---- -camel bind joke.yaml --source chuck-norris-source --sink log-sink ----- - -This creates the `joke.yaml` file that represents the Pipe resource. - -[source,yaml] ----- -apiVersion: camel.apache.org/v1 -kind: Pipe -metadata: - name: joke -spec: - source: - ref: - kind: Kamelet - apiVersion: camel.apache.org/v1 - name: chuck-norris-source - properties: - period: 5000 - sink: - ref: - kind: Kamelet - apiVersion: camel.apache.org/v1 - name: log-sink +camel run foo.camel.yaml --runtime=spring-boot +camel run foo.camel.yaml --runtime=quarkus ---- -NOTE: The bind command is able to inspect the Kamelets being used as a source and sink in order to automatically set all required properties. -In case the Kamelet defines a required property, and the user has not specified such, the command will automatically set this property with an example value. -Once the pipe resource file is generated, you can review and set the properties as you wish. - -The bind command supports the following options: - -[width="100%",cols="1m,3",options="header",] -|======================================================================= -|Option |Description - -|--source -|Source (from) such as a Kamelet or Camel endpoint uri that provides data. - -|--sink -|Sink (to) such as a Kamelet or Camel endpoint uri where data should be sent to. - -|--step -|Add optional 1-n steps to the pipe processing. Each step represents a reference to a Kamelet of type action. - -|--property -|Add a pipe property in the form of `[source,sink,error-handler,step-<n>].<key>=<value>` where `<n>` is the step number starting from 1. +This does an export to a temporary folder and runs using Maven. +Source changes are reloaded via Spring Boot dev-tools or Quarkus dev mode. -|--error-handler -|Add error handler (none,log,sink:<endpoint>). Sink endpoints are expected in the format [[apigroup/]version:]kind:[namespace/]name, plain Camel URIs or Kamelet name. +Limitations: -|--output -|Output format generated by this command (supports: file, YAML or JSON). Default is "file". -|======================================================================= - -=== Binding explicit Camel URIs - -Usually, the source and sink reference a Kamelet by its name as shown in the previous section. -As an alternative, you can also just use an arbitrary Camel endpoint URI that acts as a source or sink in the pipe. +- Spring Boot and Quarkus cannot auto-detect new components (stop and run again to update dependencies) +- Quarkus versions are locked to a specific Camel version (`camel version list --runtime=quarkus`) +- Spring Boot is more flexible — you can choose different versions: [source,bash] ---- -camel bind joke.yaml --source chuck-norris-source --sink https://mycompany.com/the-service ----- - -As a result, the Pipe resource uses the Camel endpoints as source and sink. - -[source,yaml] ----- -apiVersion: camel.apache.org/v1 -kind: Pipe -metadata: - name: my-pipe -spec: - source: -# ... - sink: - uri: https://mycompany.com/the-service # <1> +camel run foo.camel.yaml --runtime=spring-boot --spring-boot-version=3.2.3 --camel-version=4.4.1 +camel run foo.camel.yaml --runtime=quarkus --quarkus-version=3.9.4 ---- -<1> Pipe with explicit Camel endpoint URI as sink where the data gets pushed to == Running local Kamelets -You can also use Camel CLI to try local Kamelets, without the need to publish them on GitHub or package them in a jar. +Run local Kamelets without publishing them: [source,bash] ---- camel run --local-kamelet-dir=/path/to/local/kamelets earthquake.yaml ---- -TIP: When the kamelets are from local file system, then they can be live reloaded if they are updated, when you run -Camel CLI in `--dev` mode. +TIP: Local Kamelets support live reload in dev mode. -You can also point to a folder in a GitHub repository. For example, we have provided some custom Kamelets -at https://github.com/apache/camel-kamelets-examples/tree/main/custom-kamelets, which can be used easily: +You can also point to a GitHub folder: [source,bash] ---- camel run --local-kamelet-dir=https://github.com/apache/camel-kamelets-examples/tree/main/custom-kamelets user.java ---- -NOTE: If a kamelet is loaded from GitHub, then they cannot be live reloaded. +NOTE: Kamelets loaded from GitHub cannot be live reloaded. == Creating a new Kamelet -You can create a new kamelet with the `init` command by using kamelet naming convention. - -For example, to create a new kamelet source, you can do: - -[source,bash] ----- -camel init cheese-source.kamelet.yaml ----- - -This will create a basic kamelet (based on the timer source). - -And to use the kamelet, you could create the following route: - -[source,yaml] ----- -- route: - from: - uri: kamelet:cheese-source - parameters: - period: "2000" - message: "Hello World" - steps: - - log: - message: "${body}" ----- - -If you want to create a sink kamelet, then you just name it with sink as follows (based on log sink): +Create a new Kamelet using naming conventions — the suffix determines the type: [source,bash] ---- -camel init wine-sink.kamelet.yaml +camel init cheese-source.kamelet.yaml # creates a source kamelet +camel init wine-sink.kamelet.yaml # creates a sink kamelet ---- -You can then change the route to use the wine kamelet as follows: +Use the new Kamelet in a route: [source,yaml] ---- @@ -747,265 +263,9 @@ You can then change the route to use the wine kamelet as follows: uri: kamelet:wine-sink ---- -If you want to create a new Kamelet based on an existing Kamelet, for example, to create a new sink based on the existing MySQL: +To base a new Kamelet on an existing one: [source,bash] ---- camel init orderdb-sink.kamelet.yaml --from-kamelet=mysql-sink ---- - -== Using the platform-http component - -NOTE: Camel CLI is only intended for working with `platform-http` as HTTP server component for rest-dsl, -and for HTTP serer in general. It is not intended to work with `camel-servlet` or `camel-jetty`. If you find a need for using Jetty, -then Camel CLI will not support seamless rest-dsl support and exporting. - -When a route is started from `platform-http` then Camel CLI will automatically include a VertX HTTP server -running on port 8080. For example, the following route in a file named `server.yaml`: - -[source,yaml] ----- -- route: - from: - uri: platform-http:/hello - steps: - - set-body: - constant: "Hello World" ----- - -Can be run with - -[source,bash] ----- -camel run server.yaml ----- - -And you can call the HTTP service with: - -[source,bash] ----- -$ curl http://localhost:8080/hello -Hello World% ----- - -== Running with Spring Boot or Quarkus - -Camel CLI is __primary__ intended to be Camel standalone only. In *Camel 4.6* onwards, we added limited -support for running with Spring Boot or Quarkus, but there are some limitations. - -You use the `--runtime` option to specify which platform to use, as shown below: - -[source,bash] ----- -camel run foo.camel.yaml --runtime=spring-boot ----- - -And for Quarkus: - -[source,bash] ----- -camel run foo.camel.yaml --runtime=quarkus ----- - -When running this way, then Camel CLI is _essentially_ doing an _export_ to a temporary folder, -and then running Spring Boot or Quarkus using Maven. - -You can do changes to the source file and have Quarkus and Spring Boot reload the routes, just as `camel run --dev` can do, -but uses the natural Spring Boot _dev-tools_ and Quarkus _dev mode_ functionality. - -There are several limitations, one would be that Spring Boot and Quarkus cannot automatically detect new components and download JARs. -(you can stop and run again to update dependencies). - -When using Quarkus, then you can only select the Quarkus version to run. That is locked to a specific Camel version. -You can see the versions by `camel version list --runtime=quarkus`. On the other hand Spring Boot is more flexible -where you can choose different Spring Boot and Camel versions (within reasonable range). - -For example: - -[source,bash] ----- -camel run foo.camel.yaml --runtime=spring-boot --spring-boot-version=3.2.3 --camel-version=4.4.1 ----- - -And for Quarkus: - -[source,bash] ----- -camel run foo.camel.yaml --runtime=quarkus --quarkus-version=3.9.4 ----- - -== Downloading JARs over the internet - -By default, Camel CLI will automatically resolve dependencies needed to run Camel, which is done -by JBang and Camel respectively. Camel itself detects at runtime if a component has a need for JARs that -are not currently available on the classpath, and can then automatically download the JARs (incl transitive). - -Camel will download these JARs in the following order: - -1. from local disk in `~/.m2/repository` -2. from the internet in Maven Central -3. from the internet from custom third-party Maven repositories -4. from all the repositories found in active profiles of `~/.m2/settings.xml` or a settings file specified using -`--maven-settings` option. - -If you do not want Camel CLI to download over the internet, you can turn this off with `--download`, as shown below: - -[source,bash] ----- -camel run foo.java --download=false ----- - -If you do not want Camel CLI to use your existing Maven settings file, you can use: - -[source,bash] ----- -camel run foo.java --maven-settings=false ----- - -[#_adding_custom_jars] - -[#_adding_custom_jars] -== Adding custom JARs - -Camel CLI will automatically detect dependencies for Camel components, languages, data formats, etc. that -from its own release. This means you often do not have to specify which JARs to use. - -However, if you need to add 3rd-party custom JARs, then you can specify these with `--dep` as CLI argument in Maven -GAV syntax (`groupId:artifactId:version`), such as: - -[source,bash] ----- -camel run foo.java --dep=com.foo:acme:1.0 ----- - -In case you need to explicit add a Camel dependency you can use a shorthand syntax (starting with `camel:` or `camel-`) -such as: - -[source,bash] ----- -camel run foo.java --dep=camel-saxon ----- - -You can specify multiple dependencies separated by comma: - -[source,bash] ----- -camel run foo.java --dep=camel-saxon,com.foo:acme:1.0 ----- - -== Using 3rd-party Maven repositories - -Camel CLI will download from local repository first, and then online from Maven Central. -To be able to download from 3rd-party Maven repositories then you need to specify this as CLI argument, -]or in `application.properties` - -[source,bash] ----- -camel run foo.java --repos=https://packages.atlassian.com/maven-external ----- - -TIP: Multiple repositories can be separated by comma - -The configuration for the 3rd-party Maven repositories can also be configured in `application.properties` -with the key `camel.jbang.repos` as shown: - -[source,properties] ----- -camel.jbang.repos=https://packages.atlassian.com/maven-external ----- - -Alternatively, you can configure default Maven repositories globally via a system property. -This is useful for custom Camel distributions that require additional repositories without manual configuration on each command: - -[source,bash] ----- -export JAVA_TOOL_OPTIONS="-Dcamel.extra.repos=repo1=https://repo1.example.com/maven2,repo2=https://repo2.example.com/releases"; ----- - -When running Camel, `application.properties` in the current directory is auto-detected and included. -You can also pass it explicitly if needed: - -[source,bash] ----- -camel run foo.java application.properties ----- - -== Configuration of Maven usage - -By default, existing `~/.m2/settings.xml` file is loaded, so it is possible to alter the behaviour of Maven resolution -process. Maven settings file can provide information about Maven mirrors, credential configuration (potentially -encrypted) or active profiles, and additional repositories. - -Maven repositories can use authentication and the Maven-way to configure credentials is through `<server>` elements, -like this: - -[source,xml] ----- -<server> - <id>external-repository</id> - <username>camel</username> - <password>{SSVqy/PexxQHvubrWhdguYuG7HnTvHlaNr6g3dJn7nk=}</password> -</server> ----- - -While the password may be specified using plain text, it's better to configure maven master password first and then -use it to configure repository password: - -[source,bash] ----- -$ mvn -emp -Master password: camel -{hqXUuec2RowH8dA8vdqkF6jn4NU9ybOsDjuTmWvYj4U=} ----- - -The above password should be added to `~/.m2/settings-security.xml` file like this: - -[source,xml] ----- -<settingsSecurity> - <master>{hqXUuec2RowH8dA8vdqkF6jn4NU9ybOsDjuTmWvYj4U=}</master> -</settingsSecurity> ----- - -Then a normal password can be configured like this: - -[source,bash] ----- -$ mvn -ep -Password: camel -{SSVqy/PexxQHvubrWhdguYuG7HnTvHlaNr6g3dJn7nk=} ----- - -Finally, such passwords can be used in `<server>/<password>` configuration. - -By default, Maven reads the master password from `~/.m2/settings-security.xml` file, but we can override it. -The location of the `settings.xml` file itself can be specified as well: - -[source,bash] ----- -camel run foo.java --maven-settings=/path/to/settings.xml --maven-settings-security=/path/to/settings-security.xml ----- - -If you want to run Camel application without assuming any location (even `~/.m2/settings.xml`), use this option: - -[source,bash] ----- -camel run foo.java --maven-settings=false ----- - -== Running a Maven based project - -Camel CLI is intended for flat-file-based projects, where you run small integrations. -However, Camel CLI may be used as a tool for migrating existing Maven based projects. -To make the migration easier, then JBang can do _best effort_ to run, export, or transform these projects. - -For example, if you have a Maven-based project, you can execute - -[source,bash] ----- -camel run pom.xml ----- - -Camel CLI will then scan in `src/main/java` and `src/main/resources` for files to include (recursive). - -NOTE: Using `camel run pom.xml` is not intended as a fully compatible way of running an existing Maven-based project. It cannot start Quarkus or Spring Boot applications; instead, use the proper plugins/commands. The command is mainly used to migrate from old projects. diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tips.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tips.adoc new file mode 100644 index 000000000000..8ba3ed03e8de --- /dev/null +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tips.adoc @@ -0,0 +1,222 @@ += Camel CLI - Tips and Recipes + +A collection of productivity shortcuts and advanced techniques for working with the Camel CLI. + +== Run from clipboard + +Run a route directly from the OS clipboard — copy some code, then run it: + +[source,bash] +---- +camel run clipboard.yaml +---- + +The extension tells the CLI which DSL the clipboard content uses (`yaml`, `java`, `xml`). + +You can also run from clipboard in dev mode for live reload: + +[source,bash] +---- +camel run clipboard.yaml --dev +---- + +Edit your code, copy it again, and Camel reloads automatically. + +== Run with inline code + +For quick one-liners, pass the route directly on the command line: + +[source,bash] +---- +camel run --code='from("kamelet:beer-source").to("log:beer")' +---- + +Limitations: + +- Java DSL only +- Wrap code in single quotes so you can use double quotes inside +- All routes must fit in a single `--code` parameter + +From Camel 4.7, `--code` can also reference a `.java` file that contains bare route definitions +(no `public class` wrapper): + +[source,java] +---- +from("timer:java?period=1000") + .setBody() + .simple("Hello from ${routeId}") + .log("${body}"); +---- + +[source,bash] +---- +camel run --code=quick.java +---- + +== Interactive prompt for placeholder values + +Run with `--prompt` to have Camel ask for missing placeholder values at startup: + +[source,bash] +---- +camel run foo.java --prompt +---- + +Camel will prompt for each unresolved `{{placeholder}}` in the terminal. +Placeholders with default values (e.g. `{{time:1000}}`) can be accepted by pressing Enter. + +This is useful for prototypes where you want users to enter custom values quickly. +Values can also be pre-configured in `application.properties`. + +== Stub components + +When troubleshooting a route that uses components you cannot connect to (JMS brokers, databases, etc.), +stub them out: + +[source,bash] +---- +camel run myroute.java --stub=jms +---- + +Camel replaces the stubbed component with an in-memory substitute, keeping the original endpoint URIs. +You can then send test messages with: + +[source,bash] +---- +camel cmd send --body='Something here' +---- + +Other stub options: + +[source,bash] +---- +camel run myroute.java --stub=jms:inbox # stub a specific endpoint +camel run myroute.java --stub=jms,sql # stub multiple components +camel run myroute.java --stub=remote # stub all remote components +camel run myroute.java --stub=all # stub everything +---- + +The `remote` flag uses the Camel catalog to determine which components connect to external systems. + +Use `camel cmd stub` to list stubbed endpoints, and `camel cmd stub --browse` to browse their messages. + +== Run from GitHub + +Run a route directly from a GitHub repository: + +[source,bash] +---- +camel run github:apache:camel-kamelets-examples:jbang/hello-java/Hey.java +---- + +Or use the full HTTPS URL — copy it from your browser: + +[source,bash] +---- +camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/hello-java +---- + +Wildcards work too: + +[source,bash] +---- +camel run https://github.com/apache/camel-kamelets-examples/tree/main/jbang/languages/rou* +---- + +=== Run from GitHub gists + +Gists are a quick way to share small Camel routes: + +[source,bash] +---- +camel run https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92 +---- + +A gist can contain multiple files (routes, properties, Java beans) — the CLI gathers them all. + +== Download from GitHub + +Download examples from GitHub to local disk for editing: + +[source,bash] +---- +camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection +camel run * +---- + +Use `--directory` to download into a specific folder: + +[source,bash] +---- +camel init https://github.com/apache/camel-kamelets-examples/tree/main/jbang/dependency-injection --directory=myproject +---- + +Single files and gists work the same way: + +[source,bash] +---- +camel init https://github.com/apache/camel-kamelets-examples/blob/main/jbang/hello-yaml/hello.camel.yaml +camel init https://gist.github.com/davsclaus/477ddff5cdeb1ae03619aa544ce47e92 +---- + +== Upload files via HTTP + +When running with `--source-dir`, `--console`, and `--dev`, you can upload, modify, or delete +source files over HTTP: + +[source,bash] +---- +camel run --source-dir=mycode --console --dev +---- + +Upload or update a file: + +[source,bash] +---- +curl -T bar.java http://0.0.0.0:8080/q/upload/bar.java +---- + +Delete files (wildcards supported): + +[source,bash] +---- +curl -X DELETE http://0.0.0.0:8080/q/upload/bar.java +curl -X DELETE http://0.0.0.0:8080/q/upload/*.java +curl -X DELETE http://0.0.0.0:8080/q/upload/* +---- + +== Maven configuration + +By default, Camel CLI loads `~/.m2/settings.xml` for Maven mirrors, credentials, and repositories. + +You can override the settings file location: + +[source,bash] +---- +camel run foo.java --maven-settings=/path/to/settings.xml --maven-settings-security=/path/to/settings-security.xml +---- + +Or disable Maven settings entirely: + +[source,bash] +---- +camel run foo.java --maven-settings=false +---- + +For encrypted passwords in Maven settings, configure a master password with `mvn -emp`, +store it in `~/.m2/settings-security.xml`, then encrypt repository passwords with `mvn -ep`. +See the https://maven.apache.org/guides/mini/guide-encryption.html[Maven encryption guide] for details. + +== Running a Maven based project + +Camel CLI can do a _best effort_ run of an existing Maven-based project for migration purposes: + +[source,bash] +---- +camel run pom.xml +---- + +Camel CLI scans `src/main/java` and `src/main/resources` for files to include. + +NOTE: This is not a fully compatible way to run Maven projects. It cannot start Spring Boot or Quarkus +applications — use the proper plugins for those. This command is mainly useful for migrating from old projects. diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc index bc57480862dd..b49ebcf86cbb 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang.adoc @@ -79,8 +79,8 @@ TIP: You can also install without JBang using the xref:camel-jbang-launcher.adoc | Version-pinned installs, offline-safe setups, container images, installing without JBang. | xref:camel-jbang-running.adoc[Running Camel] -| Dev mode with hot reload, profiles, properties, dependency management, GitHub-hosted routes, - Pipes, clipboard, Spring Boot and Quarkus runtimes. +| Dev mode with hot reload, profiles, properties, dependency management, + Kamelets, platform-http, Spring Boot and Quarkus runtimes. | xref:camel-jbang-dev-services.adoc[Dev Services] | Start and manage local infrastructure services (databases, message brokers, etc.) @@ -105,6 +105,10 @@ TIP: You can also install without JBang using the xref:camel-jbang-launcher.adoc | Component catalog, exporting to Spring Boot / Quarkus / Camel Main, SBOM generation, plugin management, version management, automated upgrades. +| xref:camel-jbang-tips.adoc[Tips and Recipes] +| Run from GitHub or clipboard, stub components, inline code, interactive prompts, + upload via HTTP, Maven configuration. + | xref:camel-jbang-configuration.adoc[Configuration] | CLI configuration options, config commands, configuration precedence, troubleshooting.
