This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-jbang-examples.git
The following commit(s) were added to refs/heads/main by this push:
new 698dbc3 chore(docs): Improve README files (#11)
698dbc3 is described below
commit 698dbc39f9c70dfa42b41ab36651daad07788d45
Author: Christoph Deppisch <cdeppi...@redhat.com>
AuthorDate: Thu Dec 12 17:43:09 2024 +0100
chore(docs): Improve README files (#11)
- Use Asciidoc everywhere
- Include common chapters from imported files (help.adoc,
install-jbang.adoc)
- Use consistent headline hierarchy
- Use "shell" language in code blocks
---
README.md => README.adoc | 60 ++++++++++++-------------------
aws-s3-event-based/README.adoc | 78 ++++++++++++++--------------------------
ftp/README.adoc | 82 +++++++++++++++---------------------------
help.adoc | 7 ++++
install.adoc | 24 +++++++++++++
mqtt/README.adoc | 72 +++++++++++++------------------------
6 files changed, 132 insertions(+), 191 deletions(-)
diff --git a/README.md b/README.adoc
similarity index 65%
rename from README.md
rename to README.adoc
index 30ed105..63fdf65 100644
--- a/README.md
+++ b/README.adoc
@@ -1,13 +1,13 @@
-# Apache Camel JBang Examples
+= Apache Camel JBang Examples
-[Apache Camel](http://camel.apache.org/) is a powerful open source integration
framework based on known
+http://camel.apache.org/[Apache Camel] is a powerful open source integration
framework based on known
Enterprise Integration Patterns with powerful bean integration.
-## Introduction
+== Introduction
This project provides examples for low-code integrations with Apache Camel
JBang.
-### Examples
+=== Examples
This git repository hosts a set of ready-to-use examples you can try to learn
more about Apache Camel,
and how Camel can be used to integrate systems. These examples are accessible
for non developers, as
@@ -17,61 +17,45 @@ All examples can run local on your computer from a CLI
terminal by executing a f
These examples uses JBang as the CLI which is a great tool that makes using
Java much easier.
-#### Installing JBang
+== Install Camel JBang
-First install JBang according to https://www.jbang.dev
+include::install.adoc[]
-When JBang is installed then you should be able to run from a shell:
+== Integration testing
-```shell
-jbang --version
-```
-
-This will output the version of JBang.
-
-#### Installing Camel JBang
-
-To run this example you can install Camel on JBang via:
-
-```shell
-jbang app install camel@apache/camel
-```
-
-Which allows to run Camel with `camel` as shown below.
-
-```shell
-camel --version
-```
-
-#### Integration testing
-
-The examples provide automated integration tests that you can run with the
[Citrus](https://citrusframework.org/) test framework.
+The examples provide automated integration tests that you can run with the
https://citrusframework.org/[Citrus] test framework.
You need to install Citrus as a JBang app, too:
-```shell
+[source,shell]
+----
jbang app install citrus@citrusframework/citrus
-```
+----
Now you can start running commands for the Citrus JBang app with just calling
`citrus`:
-```shell
+[source,shell]
+----
citrus --version
-```
+----
Usually the Citrus tests are written in YAML files and named accordingly to
the Camel JBang route source file.
For instance the Camel route `mqtt.camel.yaml` route provides a test named
`mqtt.camel.it.yaml`.
You can run the test with Citrus JBang like this:
-```shell
+[source,shell]
+----
citrus run mqtt.camel.it.yaml
-```
+----
Usually the test prepares the complete infrastructure (e.g. via Docker
compose) and starts the Camel route automatically via JBang.
Of course the test also performs some validation steps to make sure that the
Camel route works as expected.
-### Other Examples
+== Other Examples
+
+You can also find a set of various Camel JBang examples at:
https://github.com/apache/camel-kamelets-examples/tree/main/jbang
-You can also find a set of various Camel JBang examples at:
https://github.com/apache/camel-kamelets-examples/tree/main/jbang
+== Help and contributions
+include::help.adoc[]
diff --git a/aws-s3-event-based/README.adoc b/aws-s3-event-based/README.adoc
index fb81418..6af7529 100644
--- a/aws-s3-event-based/README.adoc
+++ b/aws-s3-event-based/README.adoc
@@ -1,96 +1,78 @@
-== AWS S3 CDC Example
+= AWS S3 CDC Example
In this sample you'll use the AWS S3 CDC Source Kamelet.
Through the usage of EventBridge and SQS Services you'll be able to consume
events from specific bucket.
-=== Install JBang
+== Install Camel JBang
-First install JBang according to https://www.jbang.dev
+include::../install.adoc[]
-When JBang is installed then you should be able to run from a shell:
-
-[source,sh]
-----
-$ jbang --version
-----
-
-This will output the version of JBang.
-
-To run this example you can either install Camel on JBang via:
-
-[source,sh]
-----
-$ jbang app install camel@apache/camel
-----
-
-Which allows to run CamelJBang with `camel` as shown below.
-
-=== Setup the AWS S3 bucket, SQS Queue and EventBridge Rule
+== Setup the AWS S3 bucket, SQS Queue and EventBridge Rule
You'll need a fully working AWS CLI locally.
Create a bucket on AWS on a particular region
-[source,sh]
+[source,shell]
----
aws s3api create-bucket --bucket cdc-s3-bucket --region eu-west-1
--create-bucket-configuration LocationConstraint=eu-west-1
----
Enable EventBridge notification on the bucket
-[source,sh]
+[source,shell]
----
aws s3api put-bucket-notification-configuration --bucket cdc-s3-bucket
--region eu-west-1 --notification-configuration '{ "EventBridgeConfiguration":
{} }'
----
Add an EventBridge rule on the bucket
-[source,sh]
+[source,shell]
----
aws events put-rule --name "s3-events-cdc" --event-pattern
"{\"source\":[\"aws.s3\"], \"detail\": {\"bucket\": { \"name\":
[\"cdc-s3-bucket\"]}}}" --region=eu-west-1
----
Create an SQS Queue where we're going to receive the notification
-[source,sh]
+[source,shell]
----
aws sqs create-queue --queue-name test-queue-3 --region eu-west-1
----
Modify Access Policy for the queue just created. Don't forget to edit the
policy-queue.json file (by adding the correct rule_arn and queue_arn), before
submitting the command.
-[source,sh]
+[source,shell]
----
aws sqs set-queue-attributes --queue-url <just_created_queue_arn> --attributes
file://policy-queue.json
----
Add a target for EventBridge Rule which will be the SQS Queue just created
-[source,sh]
+[source,shell]
----
aws events put-targets --rule s3-events-cdc --targets
"Id"="sqs-sub","Arn"="<just_created_queue_arn>" --region eu-west-1
----
-=== Setup the AWS S3 bucket, SQS Queue and EventBridge Rule through Terraform
+== Setup the AWS S3 bucket, SQS Queue and EventBridge Rule through Terraform
If you are in a hurry you can also try this example by running the Terraform
configuration provided in Terraform folder.
-[source,sh]
+[source,shell]
----
cd terraform/
----
and then run
-[source,sh]
+[source,shell]
----
terraform init
----
At this point you should be to run the configuration
-[source,sh]
+[source,shell]
----
terraform apply -var="s3_bucket_name=s3-eventbridge-test-123"
-var="sqs_queue_name=sqs-eventbridge-test-123"
----
@@ -101,38 +83,38 @@ At the end the AWS environment on your account will be
completed, and you could
Don't forget to specify the correct sqs queue name in the yaml file and adding
correct credentials for AWS.
-=== How to run
+== How to run
Then you can run this example using:
-[source,sh]
+[source,shell]
----
$ camel run aws-s3-cdc-log.camel.yaml
----
Or run it even shorter:
-[source,sh]
+[source,shell]
----
$ camel run *
----
-=== Developer Web Console
+== Developer Web Console
You can enable the developer console via `--console` flag as show:
-[source,sh]
+[source,shell]
----
$ camel run aws-s3-cdc-log.camel.yaml --console
----
Then you can browse: http://localhost:8080/q/dev to introspect the running
Camel Application.
-=== Create and delete an object
+== Create and delete an object
While the integration is running you can run the following commands:
-[source,sh]
+[source,shell]
----
aws s3api put-object --bucket cdc-s3-bucket --key example-file-uploaded.txt
--body example-file.txt --region eu-west-1
{
@@ -141,7 +123,7 @@ aws s3api put-object --bucket cdc-s3-bucket --key
example-file-uploaded.txt --bo
aws s3api delete-object --bucket cdc-s3-bucket --key example-file.txt
----
-[source,sh]
+[source,shell]
----
022-11-02 15:13:03.747 INFO 120300 --- [ main]
he.camel.cli.connector.LocalCliConnector : Camel CLI enabled (local)
2022-11-02 15:13:08.570 INFO 120300 --- [ main]
e.camel.impl.engine.AbstractCamelContext : Apache Camel 3.21.0-SNAPSHOT
(aws-s3-cdc-log) is starting
@@ -163,20 +145,20 @@ aws s3api delete-object --bucket cdc-s3-bucket --key
example-file.txt
2022-11-02 15:13:41.250 INFO 120300 --- [://test-queue-3] info
: Exchange[ExchangePattern: InOnly, BodyType:
com.fasterxml.jackson.databind.node.ObjectNode, Body: { "version" : "0", "id"
: "d54290df-2ad9-31ff-308b-8331fee7344a", "detail-type" : "Object Deleted",
"source" : "aws.s3", "account" : "xxxx", "time" : "2022-11-02T14:13:37Z",
"region" : "eu-west-1", "resources" : [ "arn:aws:s3:::cdc-s3-bucket" ],
"detail" : { "version" : "0", " [...]
----
-=== Cleanup AWS S3 bucket, SQS Queue and EventBridge Rule through Terraform
+== Cleanup AWS S3 bucket, SQS Queue and EventBridge Rule through Terraform
You'll need to cleanup everything from AWS console or CLI.
If you used terraform it will be enough to run terraform destroy
-[source,sh]
+[source,shell]
----
cd terraform/
----
At this point you should be to run the destroy
-[source,sh]
+[source,shell]
----
terraform destroy -var="s3_bucket_name=s3-eventbridge-test"
-var="sqs_queue_name=sqs-eventbridge-test"
----
@@ -185,12 +167,6 @@ You'll need to specify the same var used for terraform
apply.
At the end the AWS environment on your account will be clean.
-=== Help and contributions
-
-If you hit any problem using Camel or have some feedback, then please
-https://camel.apache.org/community/support/[let us know].
-
-We also love contributors, so
-https://camel.apache.org/community/contributing/[get involved] :-)
+== Help and contributions
-The Camel riders!
+include::../help.adoc[]
diff --git a/ftp/README.adoc b/ftp/README.adoc
index c5145f5..0a73ee9 100644
--- a/ftp/README.adoc
+++ b/ftp/README.adoc
@@ -1,118 +1,92 @@
-== ActiveMQ to FTP
+= ActiveMQ to FTP
This example shows how to integrate ActiveMQ with FTP server.
image::ftp-kaoto.png[Apache Camel Kaoto online designer]
-=== Running ActiveMQ and FTP server
+== Install Camel JBang
-You need both an ActiveMQ Artemis broker, and FTP server up and running.
-
-You can run both via Docker Compose (or Podman)
-
-[source,sh]
-----
-$ docker compose up --detach
-----
-
-=== Install JBang
-
-First install JBang according to https://www.jbang.dev
-
-When JBang is installed then you should be able to run from a shell:
+include::../install.adoc[]
-[source,sh]
-----
-$ jbang --version
-----
+== Running ActiveMQ and FTP server
-This will output the version of JBang.
+You need both an ActiveMQ Artemis broker, and FTP server up and running.
-To run this example you can either install Camel on JBang via:
+You can run both via Docker Compose (or Podman)
-[source,sh]
+[source,shell]
----
-$ jbang app install camel@apache/camel
+docker compose up --detach
----
-Which allows to run CamelJBang with `camel` as shown below.
-
-=== How to run
+== How to run
Then you can run this example using:
-[source,sh]
+[source,shell]
----
-$ camel run *
+camel run *
----
-=== Sending Messages to ActiveMQ
+== Sending Messages to ActiveMQ
When the example is running, you need to trigger Camel, by sending messages to
the ActiveMQ broker.
You can either do this via the broker web console http://localhost:8161 (login
with `artemis/artemis`
or by using Camel JBang:
-[source,sh]
+[source,shell]
----
-$ camel cmd send --body=file:test/payload.xml
+camel cmd send --body=file:test/payload.xml
----
-=== Browsing FTP server
+== Browsing FTP server
When you have sent some messages to ActiveMQ Camel will route these to the FTP
server.
To see which files have been uploaded, you can start a remote shell into the
Docker container or use Camel JBang:
-[source,sh]
+[source,shell]
----
-$ camel cmd browse
+camel cmd browse
----
Which shows a status page of pending messages in the systems.
To see the content of these messages, you can tell Camel to dump via
-[source,sh]
+[source,shell]
----
-$ camel cmd browse --dump
+camel cmd browse --dump
----
TIP: To see more options use `camel cmd browse --help`.
-
-=== Developer Web Console
+== Developer Web Console
You can enable the developer console via `--console` flag as show:
-[source,sh]
+[source,shell]
----
-$ camel run * --console
+camel run * --console
----
Then you can browse: http://localhost:8080/q/dev to introspect the running
Camel Application.
-=== Integration testing
+== Integration testing
The example provides an automated integration test (`ftp.camel.it.yaml`) that
you can run with the https://citrusframework.org/[Citrus] test framework.
Please make sure to install Citrus as a JBang app, too.
You may run the test with:
-[source,sh]
+[source,shell]
----
-$ citrus run ftp.camel.it.yaml
+citrus run ftp.camel.it.yaml
----
-=== More Information
+== More Information
This example was also covered in the following YouTube video:
https://youtu.be/V0sBmE8rcVg
+== Help and contributions
-=== Help and contributions
-
-If you hit any problem using Camel or have some feedback, then please
-https://camel.apache.org/community/support/[let us know].
-
-We also love contributors, so
-https://camel.apache.org/community/contributing/[get involved] :-)
-
-The Camel riders!
+include::../help.adoc[]
diff --git a/help.adoc b/help.adoc
new file mode 100644
index 0000000..32b2c88
--- /dev/null
+++ b/help.adoc
@@ -0,0 +1,7 @@
+If you hit any problem using Camel or have some feedback, then please
+https://camel.apache.org/community/support/[let us know].
+
+We also love contributors, so
+https://camel.apache.org/community/contributing/[get involved] :-)
+
+The Camel riders!
diff --git a/install.adoc b/install.adoc
new file mode 100644
index 0000000..27b1f3d
--- /dev/null
+++ b/install.adoc
@@ -0,0 +1,24 @@
+First install JBang according to https://www.jbang.dev
+
+When JBang is installed then you should be able to run from a shell:
+
+[source,shell]
+----
+jbang --version
+----
+
+This will output the version of JBang.
+
+To run this example you can install Camel on JBang via:
+
+[source,shell]
+----
+jbang app install camel@apache/camel
+----
+
+Which allows to run Camel with `camel` as shown below.
+
+[source,shell]
+----
+camel --version
+----
diff --git a/mqtt/README.adoc b/mqtt/README.adoc
index 2d0ab4b..888562b 100644
--- a/mqtt/README.adoc
+++ b/mqtt/README.adoc
@@ -1,64 +1,46 @@
-== MQTT
+= MQTT
This example is using Camel to receive MQTT events from an external MQTT
broker,
as illustrated below.
image::mqtt-kaoto.png[Apache Camel Kaoto online designer]
-=== Install JBang
+== Install Camel JBang
-First install JBang according to https://www.jbang.dev
+include::../install.adoc[]
-When JBang is installed then you should be able to run from a shell:
-
-[source,sh]
-----
-$ jbang --version
-----
-
-This will output the version of JBang.
-
-To run this example you can either install Camel on JBang via:
-
-[source,sh]
-----
-$ jbang app install camel@apache/camel
-----
-
-Which allows to run CamelJBang with `camel` as shown below.
-
-=== How to run
+== How to run
You need to run a MQTT broker such as via Docker, or download and run Apache
ActiveMQ Artemis.
To use docker (docker compose), you can run the following command:
-[source,sh]
+[source,shell]
----
-$ start.sh
+start.sh
----
Or use
-[source,sh]
+[source,shell]
----
-$ docker compose up --detach
+docker compose up --detach
----
Then you can run the Camel integration using:
-[source,sh]
+[source,shell]
----
-$ camel run mqtt.camel.yaml application.properties
+camel run mqtt.camel.yaml application.properties
----
And then from another terminal (or run the integration with `--background`
option),
then send a message to the MQTT broker. This can be done with the help from
camel-jbang
where you can send a message as follows:
-[source,sh]
+[source,shell]
----
-$ camel cmd send --body=file:test/payload.json mqtt
+camel cmd send --body=file:test/payload.json mqtt
----
This will send a message where the payload (body) is read from the local file
named payload.json.
@@ -75,48 +57,42 @@ The Camel integration will then consume the payload and
output in the console.
Now send another sample file `payload-low.json` and see what is the output now.
-[source,sh]
+[source,shell]
----
-$ camel cmd send --body=file:test/payload-low.json mqtt
+camel cmd send --body=file:test/payload-low.json mqtt
----
-==== Stopping
+== Stopping
To stop Docker, you can run
-[source,sh]
+[source,shell]
----
-$ docker compose down
+docker compose down
----
And you can stop Camel with
-[source,sh]
+[source,shell]
----
-$ camel stop mqtt
+camel stop mqtt
----
-=== Integration testing
+== Integration testing
The example provides an automated integration test (`mqtt.camel.it.yaml`) that
you can run with the https://citrusframework.org/[Citrus] test framework.
Please make sure to have installed Citrus as a JBang application.
You can run the test with:
-[source,sh]
+[source,shell]
----
-$ citrus run mqtt.camel.it.yaml
+citrus run mqtt.camel.it.yaml
----
The test prepares the complete infrastructure (e.g. via Docker compose) and
starts the Camel route automatically via JBang.
The test sends some test data to the MQTT broker and verifies that the Camel
route successfully processes the messages.
-=== Help and contributions
-
-If you hit any problem using Camel or have some feedback, then please
-https://camel.apache.org/community/support/[let us know].
-
-We also love contributors, so
-https://camel.apache.org/community/contributing/[get involved] :-)
+== Help and contributions
-The Camel riders!
+include::../help.adoc[]
