docs/modules/ROOT/pages/contributing/developers.adoc - camel-k - Git at Google

 [[contributing]]
 = Contributing to Camel K

 We love contributions!

 The https://github.com/apache/camel-k/[main project] is written in https://golang.org/[go] and contains some parts written in Java for the https://github.com/apache/camel-k-runtime/[integration runtime].
 Camel K is built on top of Kubernetes through *Custom Resource Definitions*.

 [[how]]
 == How can I contribute?

 There are many ways you can contribute to Camel K, not only software development, as well as with the rest of Camel community:

 * Contribute actively to development (see the section below)
 * Use it and report any feedback, improvement or bug you may find via https://github.com/apache/camel-k/[Github], link:/community/mailing-list/[mailing list] or https://camel.zulipchat.com[chat].
 * Contribute by writing missing documentation or blog posts about the features around Camel K
 * https://twitter.com/ApacheCamel[Tweet], like and socialize Camel K in your preferred social network
 * Enjoy the talks that the contributors submit in various conferences around the world.

 [[requirements]]
 == Requirements

 In order to build the project, you need to comply with the following requirements:

 * **Go version 1.22+**: needed to compile and test the project. Refer to the https://golang.org/[Go website] for the installation.
 * **GNU Make**: used to define composite build actions. This should be already installed or available as a package if you have a good OS (https://www.gnu.org/software/make/).
 * **JDK version 17+**: the build requires JDK version 17 or above. This corresponds to the JDK version of the integration base image.
 * **Maven version 3.8+**: the build requires Maven 3.8 or above. This corresponds to the version defined in the `build/Dockerfile`.
 * **MinGW**: needed to compile the project on Windows. Refer to the https://www.mingw-w64.org/[MinGW website] for the installation.
 * **Windows Subsystem for Linux (WSL)**: for running Linux binary executables natively on Windows. Refer to https://docs.microsoft.com/en-us/windows/wsl/install[WSL Website] for installation. Alternatively, you can use https://www.cygwin.com/[Cygwin] or https://www.educative.io/edpresso/how-to-install-git-bash-in-windows[Git Bash].
 * **Docker**: the image build requires https://www.docker.com/[Docker] and the https://github.com/docker/buildx[buildx plugin].

 NOTE: MacOS users will need to use *gnu-sed* to successfully run the Make build scripts (e.g. for generating the Camel K bundle). Please install gnu-sed on your machine (e.g. `brew install gnu-sed`) and set your PATH accordingly to use gnu-sed with: `export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"`

 The Camel K Java runtime (camel-k-runtime) requires:

 * **Java 17**: needed for compilation
 * **Maven**: needed for building

 [[checks]]
 == Running checks
 Checks rely on `golangci-lint` being installed in version `1.55.2`, to install it look at the https://golangci-lint.run/welcome/install/[Local Installation] instructions.

 You can run checks via `make lint`.

 [[checking-out]]
 == Checking Out the Sources

 You can create a fork of https://github.com/apache/camel-k[this project] from GitHub, then clone your fork with the `git` command line tool.

 [[structure]]
 == Structure

 This is a high-level overview of the project structure:

 .Structure
 [options="header"]
 |=======================
 | Path						| Content
 | https://github.com/apache/camel-k/tree/main/addons[/addons]       | Contains various of addons.
 | https://github.com/apache/camel-k/tree/main/build[/build]			| Contains the Docker and Maven build configuration.
 | https://github.com/apache/camel-k/tree/main/cmd[/cmd]			| Contains the entry points (the *main* functions) for the **camel-k** binary (manager) and the **kamel** client tool.
 | https://github.com/apache/camel-k/tree/main/docs[/docs]			| Contains the documentation website based on https://antora.org/[Antora].
 | https://github.com/apache/camel-k/tree/main/e2e[/e2e]			| Include integration tests to ensure that the software interacts correctly with Kubernetes and OpenShift.
 | https://github.com/apache/camel-k/tree/main/examples[/examples]			| Camel K examples were moved to separate git repository https://github.com/apache/camel-k-examples[camel-k-examples].
 | https://github.com/apache/camel-k/tree/main/helm/camel-k[/helm/camel-k]           | Contains Helm chart for Camel K installation on any Kubernetes cluster.
 | https://github.com/apache/camel-k/tree/main/install[/install]         | Contains installation files.
 | https://github.com/apache/camel-k/tree/main/java[/java]           | Contains crds and Maven logging.
 | https://github.com/apache/camel-k/tree/main/pkg[/pkg]			| This is where the code resides. The code is divided in multiple subpackages.
 | https://github.com/apache/camel-k/tree/main/proposals[/proposals]           | Contains variety of proposals for Camel K.
 | https://github.com/apache/camel-k/tree/main/release-utils/scripts[/release-utils/scripts]         | Contains scripts for creating release.
 | https://github.com/apache/camel-k/tree/main/script[/script]		| Contains scripts used during make operations for building the project.
 |=======================

 [[building]]
 == Building

 To build the whole project you now need to run:

 [source]
 ----
 make
 ----

 This executes a full build of the Go code. If you need to build the components separately you can execute:

 To build the `kamel` client tool only:

 [source]
 ----
 make build-kamel
 ----

 Currently the build is not entirely supported on Windows. If you're building on a Windows system, here's a temporary workaround:

     1. Copy the `script/Makefile` to the root of the project.
     2. Run `make -f script/Makefile`.
     3. If the above command fails, run `make build-kamel`.
     4. Rename the `kamel` binary in the root to `kamel.exe`.


 After a successful build, if you're connected to a Docker daemon, you can build the operator Docker image by running:

 [source]
 ----
 make images
 ----

 The above command produces a `camel-k` image with the name `apache/camel-k`. Sometimes you might need to produce `camel-k` images that need to be pushed to the custom repository e.g. `docker.io/myrepo/camel-k`, to do that you can pass a parameter `STAGING_IMAGE` to `make` as shown below:

 [source]
 ----
 make STAGING_IMAGE='docker.io/myrepo/camel-k' images-push-staging
 ----

 [[testing]]
 == Testing

 Unit tests are executed automatically as part of the build. They use the standard go testing framework.

 Integration tests (aimed at ensuring that the code integrates correctly with Kubernetes and OpenShift), need special care.
 Integration tests are all in the https://github.com/apache/camel-k/tree/main/e2e[/e2e] dir.

 For more detail on integration testing, refer to the following documentation:

 - xref:contributing/e2e.adoc[End To End local integration test]

 [[running]]
 == Running

 If you want to install everything you have in your source code and see it running on Kubernetes, you need to run the following command:

 === For Minikube

 First remove any camel k operator you may have installed, otherwise it will conflict with the new one we will build and install.

 * Enable the `registry` minikube addon: `minikube addons enable registry`
 * Set the access to the internal minikube registry: `eval $(minikube docker-env)`
 * Run `make images` to build the project and install the image in the internal minikube registry
 * Install camel-k-operator: `make install-k8s-global`

 === For Red Hat CodeReady Containers (CRC)

 * You need to have https://docs.docker.com/get-docker/[Docker] installed and running (or connected to a Docker daemon)
 * You need to set up Docker daemon to https://docs.docker.com/registry/insecure/[trust] CRC's insecure Docker registry which is exposed by default through the route `default-route-openshift-image-registry.apps-crc.testing`. One way of doing that is to instruct the Docker daemon to trust the certificate:
 ** `oc extract secret/router-ca --keys=tls.crt -n openshift-ingress-operator`: to extract the certificate
 ** `sudo cp tls.crt /etc/docker/certs.d/default-route-openshift-image-registry.apps-crc.testing/ca.crt`: to copy the certificate for Docker daemon to trust
 ** `docker login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.apps-crc.testing`: to test that the certificate is trusted
 * Run `make install-openshift-global`

 The commands assume you have an already running CRC instance and logged in correctly.

 === For remote Kubernetes/OpenShift clusters

 If you have changed anything locally and want to apply the changes to a remote cluster, first push your `camel-k` image to a custom repository (see <<building>>) and run the following command (the image name `docker.io/myrepo/camel-k:2.4.0-SNAPSHOT` should be changed accordingly):

 [source]
 ----
 CUSTOM_IMAGE=docker.io/myrepo/camel-k CUSTOM_VERSION=2.4.0-SNAPSHOT make bundle
 make install-k8s-global
 ----

 === Local Helm installation

 If you want to test Helm installation

 * Build the Helm chart: `make release-helm`
 * Build the project and the image: `make images`
 * Set the internal registry: `export REGISTRY_ADDRESS=$(kubectl -n kube-system get service registry -o jsonpath='{.spec.clusterIP}')`
 * Install with Helm (look at the latest version produced by `make release-helm`)

 [source]
 ----
 helm install camel-k-dev docs/charts/camel-k-2.4.0-SNAPSHOT.tgz --set platform.build.registry.address=${REGISTRY_ADDRESS} --set platform.build.registry.insecure=true --set operator.image=apache/camel-k:2.4.0-SNAPSHOT
 ----

 * To uninstall: `helm uninstall camel-k-dev`

 === Examples

 Camel K examples are located in separate git repository https://github.com/apache/camel-k-examples/[camel-k-examples]. You can clone it and run the examples locally.

 === Use

 Now you can play with Camel K:

 [source]
 ----
 ./kamel run <camel-k-examples>/01-basic/Basic.java
 ----

 [[local-development]]
 == Local development environment
 If you need to develop and test your Camel K operator locally, you can follow the link:local-development.html[local development procedure].

 [[debugging]]
 == Debugging and Running from IDE

 Sometimes it's useful to debug the code from the IDE when troubleshooting.

 .**Debugging the `kamel` binary**

 It should be straightforward: just execute the https://github.com/apache/camel-k/tree/main/cmd/kamel/main.go[/cmd/kamel/main.go] file from the IDE (e.g. Goland) in debug mode.

 .**Debugging the operator**

 It is a bit more complex (but not so much).

 You are going to run the operator code **outside** OpenShift in your IDE so, first of all, you need to **stop the operator running inside**:

 [source]
 ----
 // use kubectl in plain Kubernetes
 oc scale deployment/camel-k-operator --replicas 0
 ----

 You can scale it back to 1 when you're done, and you have updated the operator image.

 You can set up the IDE (e.g. Goland) to execute the https://github.com/apache/camel-k/blob/main/cmd/manager/main.go[/cmd/manager/main.go] file in debug mode with `operator` as the argument.

 When configuring the IDE task, make sure to add all required environment variables in the *IDE task configuration screen*:

 * Set the `KUBERNETES_CONFIG` environment variable to point to your Kubernetes configuration file (usually `<homedir>/.kube/config`).
 * Set the `WATCH_NAMESPACE` environment variable to a Kubernetes namespace you have access to.
 * Set the `OPERATOR_NAME` environment variable to `camel-k`.


 After you set up the IDE task, with Java 11+ to be used by default, you can run and debug the operator process.

 NOTE: The operator can be fully debugged in CRC, because it uses OpenShift S2I binary builds under the hood.

 [[publishing]]
 == Building Metadata for Publishing the Operator in Operator Hub

 Publishing to an operator hub requires creation and submission of metadata, required in a specific
 https://github.com/operator-framework/operator-registry/#manifest-format[format]. The
 https://sdk.operatorframework.io/docs/cli[operator-sdk] provides tools to help with the creation of this metadata.

 === `bundles`
 The latest packaging format used for deploying the operator to an OLM registry. This generates a CSV and related metadata
 files in a directory named `bundle`. The directory contains a Dockerfile that allows for building the bundle into a
 single image. It is this image that is submitted to the OLM registry.

 To generate the bundle for camel-k, use the following command:

 [source]
 ----
 make bundle
 ----

 The bundle directory is created at the root of the camel-k project filesystem.
	[[contributing]]
	= Contributing to Camel K

	We love contributions!

	The https://github.com/apache/camel-k/[main project] is written in https://golang.org/[go] and contains some parts written in Java for the https://github.com/apache/camel-k-runtime/[integration runtime].
	Camel K is built on top of Kubernetes through Custom Resource Definitions.

	[[how]]
	== How can I contribute?

	There are many ways you can contribute to Camel K, not only software development, as well as with the rest of Camel community:

	* Contribute actively to development (see the section below)
	* Use it and report any feedback, improvement or bug you may find via https://github.com/apache/camel-k/[Github], link:/community/mailing-list/[mailing list] or https://camel.zulipchat.com[chat].
	* Contribute by writing missing documentation or blog posts about the features around Camel K
	* https://twitter.com/ApacheCamel[Tweet], like and socialize Camel K in your preferred social network
	* Enjoy the talks that the contributors submit in various conferences around the world.

	[[requirements]]
	== Requirements

	In order to build the project, you need to comply with the following requirements:

	* Go version 1.22+: needed to compile and test the project. Refer to the https://golang.org/[Go website] for the installation.
	* GNU Make: used to define composite build actions. This should be already installed or available as a package if you have a good OS (https://www.gnu.org/software/make/).
	* JDK version 17+: the build requires JDK version 17 or above. This corresponds to the JDK version of the integration base image.
	* Maven version 3.8+: the build requires Maven 3.8 or above. This corresponds to the version defined in the `build/Dockerfile`.
	* MinGW: needed to compile the project on Windows. Refer to the https://www.mingw-w64.org/[MinGW website] for the installation.
	* Windows Subsystem for Linux (WSL): for running Linux binary executables natively on Windows. Refer to https://docs.microsoft.com/en-us/windows/wsl/install[WSL Website] for installation. Alternatively, you can use https://www.cygwin.com/[Cygwin] or https://www.educative.io/edpresso/how-to-install-git-bash-in-windows[Git Bash].
	* Docker: the image build requires https://www.docker.com/[Docker] and the https://github.com/docker/buildx[buildx plugin].

	NOTE: MacOS users will need to use gnu-sed to successfully run the Make build scripts (e.g. for generating the Camel K bundle). Please install gnu-sed on your machine (e.g. `brew install gnu-sed`) and set your PATH accordingly to use gnu-sed with: `export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"`

	The Camel K Java runtime (camel-k-runtime) requires:

	* Java 17: needed for compilation
	* Maven: needed for building

	[[checks]]
	== Running checks
	Checks rely on `golangci-lint` being installed in version `1.55.2`, to install it look at the https://golangci-lint.run/welcome/install/[Local Installation] instructions.

	You can run checks via `make lint`.

	[[checking-out]]
	== Checking Out the Sources

	You can create a fork of https://github.com/apache/camel-k[this project] from GitHub, then clone your fork with the `git` command line tool.

	[[structure]]
	== Structure

	This is a high-level overview of the project structure:

	.Structure
	[options="header"]
	\|=======================
	\| Path \| Content
	\| https://github.com/apache/camel-k/tree/main/addons[/addons] \| Contains various of addons.
	\| https://github.com/apache/camel-k/tree/main/build[/build] \| Contains the Docker and Maven build configuration.
	\| https://github.com/apache/camel-k/tree/main/cmd[/cmd] \| Contains the entry points (the main functions) for the camel-k binary (manager) and the kamel client tool.
	\| https://github.com/apache/camel-k/tree/main/docs[/docs] \| Contains the documentation website based on https://antora.org/[Antora].
	\| https://github.com/apache/camel-k/tree/main/e2e[/e2e] \| Include integration tests to ensure that the software interacts correctly with Kubernetes and OpenShift.
	\| https://github.com/apache/camel-k/tree/main/examples[/examples] \| Camel K examples were moved to separate git repository https://github.com/apache/camel-k-examples[camel-k-examples].
	\| https://github.com/apache/camel-k/tree/main/helm/camel-k[/helm/camel-k] \| Contains Helm chart for Camel K installation on any Kubernetes cluster.
	\| https://github.com/apache/camel-k/tree/main/install[/install] \| Contains installation files.
	\| https://github.com/apache/camel-k/tree/main/java[/java] \| Contains crds and Maven logging.
	\| https://github.com/apache/camel-k/tree/main/pkg[/pkg] \| This is where the code resides. The code is divided in multiple subpackages.
	\| https://github.com/apache/camel-k/tree/main/proposals[/proposals] \| Contains variety of proposals for Camel K.
	\| https://github.com/apache/camel-k/tree/main/release-utils/scripts[/release-utils/scripts] \| Contains scripts for creating release.
	\| https://github.com/apache/camel-k/tree/main/script[/script] \| Contains scripts used during make operations for building the project.
	\|=======================

	[[building]]
	== Building

	To build the whole project you now need to run:

	[source]
	----
	make
	----

	This executes a full build of the Go code. If you need to build the components separately you can execute:

	To build the `kamel` client tool only:

	[source]
	----
	make build-kamel
	----

	Currently the build is not entirely supported on Windows. If you're building on a Windows system, here's a temporary workaround:

	1. Copy the `script/Makefile` to the root of the project.
	2. Run `make -f script/Makefile`.
	3. If the above command fails, run `make build-kamel`.
	4. Rename the `kamel` binary in the root to `kamel.exe`.


	After a successful build, if you're connected to a Docker daemon, you can build the operator Docker image by running:

	[source]
	----
	make images
	----

	The above command produces a `camel-k` image with the name `apache/camel-k`. Sometimes you might need to produce `camel-k` images that need to be pushed to the custom repository e.g. `docker.io/myrepo/camel-k`, to do that you can pass a parameter `STAGING_IMAGE` to `make` as shown below:

	[source]
	----
	make STAGING_IMAGE='docker.io/myrepo/camel-k' images-push-staging
	----

	[[testing]]
	== Testing

	Unit tests are executed automatically as part of the build. They use the standard go testing framework.

	Integration tests (aimed at ensuring that the code integrates correctly with Kubernetes and OpenShift), need special care.
	Integration tests are all in the https://github.com/apache/camel-k/tree/main/e2e[/e2e] dir.

	For more detail on integration testing, refer to the following documentation:

	- xref:contributing/e2e.adoc[End To End local integration test]

	[[running]]
	== Running

	If you want to install everything you have in your source code and see it running on Kubernetes, you need to run the following command:

	=== For Minikube

	First remove any camel k operator you may have installed, otherwise it will conflict with the new one we will build and install.

	* Enable the `registry` minikube addon: `minikube addons enable registry`
	* Set the access to the internal minikube registry: `eval $(minikube docker-env)`
	* Run `make images` to build the project and install the image in the internal minikube registry
	* Install camel-k-operator: `make install-k8s-global`

	=== For Red Hat CodeReady Containers (CRC)

	* You need to have https://docs.docker.com/get-docker/[Docker] installed and running (or connected to a Docker daemon)
	* You need to set up Docker daemon to https://docs.docker.com/registry/insecure/[trust] CRC's insecure Docker registry which is exposed by default through the route `default-route-openshift-image-registry.apps-crc.testing`. One way of doing that is to instruct the Docker daemon to trust the certificate:
	** `oc extract secret/router-ca --keys=tls.crt -n openshift-ingress-operator`: to extract the certificate
	** `sudo cp tls.crt /etc/docker/certs.d/default-route-openshift-image-registry.apps-crc.testing/ca.crt`: to copy the certificate for Docker daemon to trust
	** `docker login -u kubeadmin -p $(oc whoami -t) default-route-openshift-image-registry.apps-crc.testing`: to test that the certificate is trusted
	* Run `make install-openshift-global`

	The commands assume you have an already running CRC instance and logged in correctly.

	=== For remote Kubernetes/OpenShift clusters

	If you have changed anything locally and want to apply the changes to a remote cluster, first push your `camel-k` image to a custom repository (see <<building>>) and run the following command (the image name `docker.io/myrepo/camel-k:2.4.0-SNAPSHOT` should be changed accordingly):

	[source]
	----
	CUSTOM_IMAGE=docker.io/myrepo/camel-k CUSTOM_VERSION=2.4.0-SNAPSHOT make bundle
	make install-k8s-global
	----

	=== Local Helm installation

	If you want to test Helm installation

	* Build the Helm chart: `make release-helm`
	* Build the project and the image: `make images`
	* Set the internal registry: `export REGISTRY_ADDRESS=$(kubectl -n kube-system get service registry -o jsonpath='{.spec.clusterIP}')`
	* Install with Helm (look at the latest version produced by `make release-helm`)

	[source]
	----
	helm install camel-k-dev docs/charts/camel-k-2.4.0-SNAPSHOT.tgz --set platform.build.registry.address=${REGISTRY_ADDRESS} --set platform.build.registry.insecure=true --set operator.image=apache/camel-k:2.4.0-SNAPSHOT
	----

	* To uninstall: `helm uninstall camel-k-dev`

	=== Examples

	Camel K examples are located in separate git repository https://github.com/apache/camel-k-examples/[camel-k-examples]. You can clone it and run the examples locally.

	=== Use

	Now you can play with Camel K:

	[source]
	----
	./kamel run <camel-k-examples>/01-basic/Basic.java
	----

	[[local-development]]
	== Local development environment
	If you need to develop and test your Camel K operator locally, you can follow the link:local-development.html[local development procedure].

	[[debugging]]
	== Debugging and Running from IDE

	Sometimes it's useful to debug the code from the IDE when troubleshooting.

	.Debugging the `kamel` binary

	It should be straightforward: just execute the https://github.com/apache/camel-k/tree/main/cmd/kamel/main.go[/cmd/kamel/main.go] file from the IDE (e.g. Goland) in debug mode.

	.Debugging the operator

	It is a bit more complex (but not so much).

	You are going to run the operator code outside OpenShift in your IDE so, first of all, you need to stop the operator running inside:

	[source]
	----
	// use kubectl in plain Kubernetes
	oc scale deployment/camel-k-operator --replicas 0
	----

	You can scale it back to 1 when you're done, and you have updated the operator image.

	You can set up the IDE (e.g. Goland) to execute the https://github.com/apache/camel-k/blob/main/cmd/manager/main.go[/cmd/manager/main.go] file in debug mode with `operator` as the argument.

	When configuring the IDE task, make sure to add all required environment variables in the IDE task configuration screen:

	* Set the `KUBERNETES_CONFIG` environment variable to point to your Kubernetes configuration file (usually `<homedir>/.kube/config`).
	* Set the `WATCH_NAMESPACE` environment variable to a Kubernetes namespace you have access to.
	* Set the `OPERATOR_NAME` environment variable to `camel-k`.


	After you set up the IDE task, with Java 11+ to be used by default, you can run and debug the operator process.

	NOTE: The operator can be fully debugged in CRC, because it uses OpenShift S2I binary builds under the hood.

	[[publishing]]
	== Building Metadata for Publishing the Operator in Operator Hub

	Publishing to an operator hub requires creation and submission of metadata, required in a specific
	https://github.com/operator-framework/operator-registry/#manifest-format[format]. The
	https://sdk.operatorframework.io/docs/cli[operator-sdk] provides tools to help with the creation of this metadata.

	=== `bundles`
	The latest packaging format used for deploying the operator to an OLM registry. This generates a CSV and related metadata
	files in a directory named `bundle`. The directory contains a Dockerfile that allows for building the bundle into a
	single image. It is this image that is submitted to the OLM registry.

	To generate the bundle for camel-k, use the following command:

	[source]
	----
	make bundle
	----

	The bundle directory is created at the root of the camel-k project filesystem.