From f8d023e4ada4113cb73865f5243b9ce254b02850 Mon Sep 17 00:00:00 2001 From: Mykola Fant Date: Thu, 10 Oct 2024 11:20:34 +0300 Subject: [PATCH] move templates to the main repo --- antora-playbook-local.yml | 4 +- antora-playbook.yml | 4 +- templates/antora.yml | 7 +++ .../modules/ROOT/pages/getting-started.adoc | 13 ++++++ .../modules/ROOT/pages/link-to-repo.adoc | 1 + .../microservices/application-structure.adoc | 6 +++ .../pages/microservices/prerequisites.adoc | 3 ++ .../running-the-application-curl.adoc | 15 ++++++ .../microservices/what-you-will-learn.adoc | 5 ++ .../modules/ROOT/pages/minikube-teardown.adoc | 36 +++++++++++++++ .../modules/ROOT/pages/prereq-caching-ms.adoc | 30 ++++++++++++ .../modules/ROOT/pages/start-cluster.adoc | 33 +++++++++++++ .../modules/ROOT/pages/start-hz-cluster.adoc | 46 +++++++++++++++++++ .../modules/ROOT/pages/validate-kube-env.adoc | 25 ++++++++++ .../modules/ROOT/pages/what-is-hz-cloud.adoc | 3 ++ templates/modules/ROOT/pages/what-is-hz.adoc | 8 ++++ .../pages/what-will-learn-caching-ms.adoc | 10 ++++ .../ROOT/pages/youre-done-caching-ms.adoc | 3 ++ .../modules/ROOT/pages/youre-done-cloud.adoc | 6 +++ 19 files changed, 252 insertions(+), 6 deletions(-) create mode 100644 templates/antora.yml create mode 100644 templates/modules/ROOT/pages/getting-started.adoc create mode 100644 templates/modules/ROOT/pages/link-to-repo.adoc create mode 100644 templates/modules/ROOT/pages/microservices/application-structure.adoc create mode 100644 templates/modules/ROOT/pages/microservices/prerequisites.adoc create mode 100644 templates/modules/ROOT/pages/microservices/running-the-application-curl.adoc create mode 100644 templates/modules/ROOT/pages/microservices/what-you-will-learn.adoc create mode 100644 templates/modules/ROOT/pages/minikube-teardown.adoc create mode 100644 templates/modules/ROOT/pages/prereq-caching-ms.adoc create mode 100644 templates/modules/ROOT/pages/start-cluster.adoc create mode 100644 templates/modules/ROOT/pages/start-hz-cluster.adoc create mode 100644 templates/modules/ROOT/pages/validate-kube-env.adoc create mode 100644 templates/modules/ROOT/pages/what-is-hz-cloud.adoc create mode 100644 templates/modules/ROOT/pages/what-is-hz.adoc create mode 100644 templates/modules/ROOT/pages/what-will-learn-caching-ms.adoc create mode 100644 templates/modules/ROOT/pages/youre-done-caching-ms.adoc create mode 100644 templates/modules/ROOT/pages/youre-done-cloud.adoc diff --git a/antora-playbook-local.yml b/antora-playbook-local.yml index 75c4e1b9..63d39f78 100644 --- a/antora-playbook-local.yml +++ b/antora-playbook-local.yml @@ -10,7 +10,7 @@ site: content: sources: - url: . - start_paths: [home, tutorials] + start_paths: [home, tutorials, templates] branches: HEAD - url: https://github.com/hazelcast/hz-docs branches: [main, v/*] @@ -78,8 +78,6 @@ content: - url: https://github.com/hazelcast/hazelcast-cloud-maven-plugin branches: main start_path: docs - - url: https://github.com/hazelcast-guides/adoc-templates.git - branches: antora-doc - url: https://github.com/hazelcast-guides/caching-springboot-jcache branches: master start_path: docs diff --git a/antora-playbook.yml b/antora-playbook.yml index 23071ee1..7f7a467e 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -12,7 +12,7 @@ urls: content: sources: - url: . - start_paths: [home, tutorials] + start_paths: [home, tutorials, templates] branches: HEAD - url: https://github.com/hazelcast/hz-docs branches: [main, v/*] @@ -80,8 +80,6 @@ content: - url: https://github.com/hazelcast/hazelcast-cloud-maven-plugin branches: main start_path: docs - - url: https://github.com/hazelcast-guides/adoc-templates.git - branches: antora-doc - url: https://github.com/hazelcast-guides/caching-springboot-jcache branches: master start_path: docs diff --git a/templates/antora.yml b/templates/antora.yml new file mode 100644 index 00000000..57e08435 --- /dev/null +++ b/templates/antora.yml @@ -0,0 +1,7 @@ +name: templates +title: Templates +version: v0.1 +nav: + - modules/ROOT/nav.adoc + + diff --git a/templates/modules/ROOT/pages/getting-started.adoc b/templates/modules/ROOT/pages/getting-started.adoc new file mode 100644 index 00000000..da40f3cd --- /dev/null +++ b/templates/modules/ROOT/pages/getting-started.adoc @@ -0,0 +1,13 @@ +== Getting started + +The fastest way to work through this guide is to clone the Git repository and use the project provided inside: + +[subs="attributes"] +---- +$ > git clone {github-address} +$ > cd {project-folder} +---- + +The `initial` directory contains the starting project that you will build upon. + +The `final` directory contains the finished project that you will build. diff --git a/templates/modules/ROOT/pages/link-to-repo.adoc b/templates/modules/ROOT/pages/link-to-repo.adoc new file mode 100644 index 00000000..3a331b22 --- /dev/null +++ b/templates/modules/ROOT/pages/link-to-repo.adoc @@ -0,0 +1 @@ +You can see the whole project {github-address}[here.] diff --git a/templates/modules/ROOT/pages/microservices/application-structure.adoc b/templates/modules/ROOT/pages/microservices/application-structure.adoc new file mode 100644 index 00000000..aa2d5c14 --- /dev/null +++ b/templates/modules/ROOT/pages/microservices/application-structure.adoc @@ -0,0 +1,6 @@ +// {framework} -> The name of the microservices framework + +The application is a basic {framework} app having 2 endpoints defined in `CommandController`: + +- `/put` is the page where key and values can be put on a Hazelcast distributed map. It takes `key` and `value` as query parameters and returns the entry in JSON format. +- `/get` is the page where the values in the Hazelcast distributed map can be obtained by keys. It takes `key` as query parameter and returns the found entry in JSON format. \ No newline at end of file diff --git a/templates/modules/ROOT/pages/microservices/prerequisites.adoc b/templates/modules/ROOT/pages/microservices/prerequisites.adoc new file mode 100644 index 00000000..1d0a9e8c --- /dev/null +++ b/templates/modules/ROOT/pages/microservices/prerequisites.adoc @@ -0,0 +1,3 @@ +- A text editor or IDE +- JDK 1.8+ +- Apache Maven 3.2+ \ No newline at end of file diff --git a/templates/modules/ROOT/pages/microservices/running-the-application-curl.adoc b/templates/modules/ROOT/pages/microservices/running-the-application-curl.adoc new file mode 100644 index 00000000..5c62c7d6 --- /dev/null +++ b/templates/modules/ROOT/pages/microservices/running-the-application-curl.adoc @@ -0,0 +1,15 @@ +// {application-ip-address} -> The IP address of the running application + +Now, you can make calls to application endpoints to put data and get it back. Firstly, run the following command to put the data into Hazelcast distributed map: + +---- +curl --data "key=key1&value=hazelcast" "{application-ip-address}:8080/put" +---- + +You will see the value in the output. Then run the command below to get the data back. Please note that the call is made to the other application instance: + +---- +curl "{application-ip-address}:8081/get?key=key1" +---- + +Again, you will see the value in the output since the data is distributed among Hazelcast cluster instances and can be accessed from any of them. diff --git a/templates/modules/ROOT/pages/microservices/what-you-will-learn.adoc b/templates/modules/ROOT/pages/microservices/what-you-will-learn.adoc new file mode 100644 index 00000000..969277d5 --- /dev/null +++ b/templates/modules/ROOT/pages/microservices/what-you-will-learn.adoc @@ -0,0 +1,5 @@ +// {framework} -> The name of the microservices framework + +In this guide, you will learn how to use Hazelcast IMDG within {framework} microservices. + +The {framework} application contains two REST controllers which helps you to put data and read it back. The application initializes a single Hazelcast IMDG member instance which is used to keep the data. When you run the application multiple times, Hazelcast IMDG instances build a cluster and share the data. \ No newline at end of file diff --git a/templates/modules/ROOT/pages/minikube-teardown.adoc b/templates/modules/ROOT/pages/minikube-teardown.adoc new file mode 100644 index 00000000..cb479e7e --- /dev/null +++ b/templates/modules/ROOT/pages/minikube-teardown.adoc @@ -0,0 +1,36 @@ +== Tearing down the environment + +When you no longer need your deployed microservices, you can delete all Kubernetes resources by running the kubectl delete command: You might need to wait up to 30 seconds as stateful sets kills pods one at a time. + +---- +$ > kubectl delete -f kubernetes.yaml +---- + +**** +[system]#*Windows* | *Mac*# + +Nothing more needs to be done for Docker Desktop. + +[system]#*Linux*# + +Perform the following steps to return your environment to a clean state. + +. Point the Docker daemon back to your local machine: ++ +``` +$ > eval $(minikube docker-env -u) +``` + +. Stop your Minikube cluster: ++ +``` +$ > minikube stop +``` + +. Delete your cluster: ++ +``` +$ > minikube delete +``` + +**** diff --git a/templates/modules/ROOT/pages/prereq-caching-ms.adoc b/templates/modules/ROOT/pages/prereq-caching-ms.adoc new file mode 100644 index 00000000..955690c9 --- /dev/null +++ b/templates/modules/ROOT/pages/prereq-caching-ms.adoc @@ -0,0 +1,30 @@ +== Prerequisites + +Before you begin, have the following tools installed: + +First, you will need Apache Maven to build and run the project. + +Also you will need a containerization software for building containers. {kube} supports a variety +of container types. You will use `Docker` in this guide. For installation instructions, refer to the https://docs.docker.com/install/[official Docker documentation^]. + +**** +[system]#*Windows* | *Mac*# + +Use Docker Desktop, where a local {kube} environment is pre-installed and enabled. If you do not see the {kube} tab then you have an older version of Docker Desktop; upgrade to the latest version. + +Complete the setup for your operating system: + + - Set up https://docs.docker.com/docker-for-windows/#kubernetes[Docker for Windows^]. + On the Docker for Windows _General Setting_ page, ensure that the option `Expose daemon on + tcp://localhost:2375 without TLS` is enabled. This is required by the `dockerfile-maven` + part of the build. + - Set up https://docs.docker.com/docker-for-mac/#kubernetes[Docker for Mac^]. + +- After following one of the sets of instructions, ensure that {kube} (not Swarm) is selected as the orchestrator in Docker Preferences. + +[system]#*Linux*# + +You will use `Minikube` as a single-node {kube} cluster that runs locally in a virtual machine. +For Minikube installation instructions see the https://github.com/kubernetes/minikube#installation[minikube installation instructions^]. Make sure to pay attention to the requirements as they vary by platform. + +**** diff --git a/templates/modules/ROOT/pages/start-cluster.adoc b/templates/modules/ROOT/pages/start-cluster.adoc new file mode 100644 index 00000000..595e9c78 --- /dev/null +++ b/templates/modules/ROOT/pages/start-cluster.adoc @@ -0,0 +1,33 @@ +== Starting and preparing your cluster for deployment + +Now that you have a proper docker image, deploy the app to kuberntes pods. Start your {kube} cluster first. + +**** +[system]#*Windows* | *Mac*# + +Start your Docker Desktop environment. Make sure "Docker Desktop is running" and "Kubernetes is running" status are updated. + +ifdef::docker-desktop-description[] +{docker-desktop-description} +endif::[] + +[system]#*Linux*# + +Run the following command from a command line: + +[subs="attributes"] +``` +ifdef::minikube-start[] +{minikube-start} +endif::[] +ifndef::minikube-start[] +$ > minikube start +endif::[] +``` + +ifdef::minikube-description[] +{minikube-description} +endif::[] +**** + + diff --git a/templates/modules/ROOT/pages/start-hz-cluster.adoc b/templates/modules/ROOT/pages/start-hz-cluster.adoc new file mode 100644 index 00000000..74f4e563 --- /dev/null +++ b/templates/modules/ROOT/pages/start-hz-cluster.adoc @@ -0,0 +1,46 @@ +[tabs] +==== + +Hazelcast Cloud:: ++ +-- +You can easily create a Hazelcast cluster on https://cloud.hazelcast.com[Hazelcast Cloud] with just a few clicks. See https://docs.cloud.hazelcast.com/docs/getting-started[Getting Started] documentation for details. +-- + +Docker Image:: ++ +-- +You can start members inside Docker containers. See the https://github.com/hazelcast/hazelcast-docker[documentation] for details. +[source, bash] +---- +$ docker run hazelcast/hazelcast:$HAZELCAST_VERSION +---- +-- + +Hazelcast CLI:: ++ +-- +You can start members via Hazelcast CLI. See the https://github.com/hazelcast/hazelcast-command-line[documentation] for the installation instructions and details. +[source, bash] +---- +$ hz start +---- +-- + +Download Packages:: ++ +-- +You can start members via `start` script in https://hazelcast.org/imdg/download[IMDG bundle]. +[source, bash] +---- +$ sh bin/start.sh +---- +-- +==== + +[NOTE] +==== +You can find other ways of starting Hazelcast members and forming a cluster +https://docs.hazelcast.org/docs/latest/manual/html-single/#installing-hazelcast-imdg[here]. +==== + diff --git a/templates/modules/ROOT/pages/validate-kube-env.adoc b/templates/modules/ROOT/pages/validate-kube-env.adoc new file mode 100644 index 00000000..2154c55c --- /dev/null +++ b/templates/modules/ROOT/pages/validate-kube-env.adoc @@ -0,0 +1,25 @@ +=== Validate {kube} environment + +Next, validate that you have a healthy {kube} environment by running the following command from the command line. + +``` +$ > kubectl get nodes +``` + +This command should return a `Ready` status for the master node. + +**** +[system]#*Windows* | *Mac*# + +You do not need to do any other step. + +[system]#*Linux*# + +Run the following command to configure the Docker CLI to use Minikube's Docker daemon. +After you run this command, you will be able to interact with Minikube's Docker daemon and build new +images directly to it from your host machine: + +``` +$ > eval $(minikube docker-env) +``` +**** diff --git a/templates/modules/ROOT/pages/what-is-hz-cloud.adoc b/templates/modules/ROOT/pages/what-is-hz-cloud.adoc new file mode 100644 index 00000000..1c195002 --- /dev/null +++ b/templates/modules/ROOT/pages/what-is-hz-cloud.adoc @@ -0,0 +1,3 @@ +== What is Hazelcast Cloud? + +Hazelcast Cloud delivers enterprise-grade Hazelcast software in the cloud, deployed as a fully managed service. Leveraging over a decade of experience and best practices, Hazelcast Cloud delivers a high-throughput, low-latency service that scales to your needs while remaining simple to deploy. diff --git a/templates/modules/ROOT/pages/what-is-hz.adoc b/templates/modules/ROOT/pages/what-is-hz.adoc new file mode 100644 index 00000000..9eb15c18 --- /dev/null +++ b/templates/modules/ROOT/pages/what-is-hz.adoc @@ -0,0 +1,8 @@ +== What is {hazelcast}? + +Hazelcast is an open source In-Memory Data Grid (IMDG). It provides elastically scalable distributed In-Memory computing, +widely recognized as the fastest and most scalable approach to application performance. + +Hazelcast is designed to scale up to hundreds and thousands of members. +Simply add new members and they will automatically discover the cluster +and will linearly increase both memory and processing capacity. diff --git a/templates/modules/ROOT/pages/what-will-learn-caching-ms.adoc b/templates/modules/ROOT/pages/what-will-learn-caching-ms.adoc new file mode 100644 index 00000000..2fac1732 --- /dev/null +++ b/templates/modules/ROOT/pages/what-will-learn-caching-ms.adoc @@ -0,0 +1,10 @@ +== What you'll learn + +You will learn how to use Hazelcast distributed caching with {framework} and deploy to a local {kube} cluster. +You will then create a Kubernetes Service which load balance between containers and verify that you can share data between Microservices. + +The microservice you will deploy is called `hazelcast-{framework-short}`. The `hazelcast-{framework-short}` microservice simply +helps you put a data and read it back. As Kubernetes Service will send the request to different pod each time +you initiate the request, the data will be served by shared hazelcast cluster between `hazelcast-{framework-short}` pods. + +You will use a local single-node {kube} cluster. However, you can deploy this application on any kubernetes distributions. diff --git a/templates/modules/ROOT/pages/youre-done-caching-ms.adoc b/templates/modules/ROOT/pages/youre-done-caching-ms.adoc new file mode 100644 index 00000000..5572337a --- /dev/null +++ b/templates/modules/ROOT/pages/youre-done-caching-ms.adoc @@ -0,0 +1,3 @@ +== Great work! You’re done! + +You have just run a {framework} application and created its Docker image. First you runned the app on a container and then deployed it to Kubernetes. You then added Hazelcast caching to the hazelcast-{framework-short}, tested with a simple curl command. You also scaled out the microservices and saw that data is shared between microservices. As a last step, you ran integration tests against hazelcast-{framework-short} that was deployed in a Kubernetes cluster. diff --git a/templates/modules/ROOT/pages/youre-done-cloud.adoc b/templates/modules/ROOT/pages/youre-done-cloud.adoc new file mode 100644 index 00000000..2977ca53 --- /dev/null +++ b/templates/modules/ROOT/pages/youre-done-cloud.adoc @@ -0,0 +1,6 @@ +== Great work! You’re done! + +You have just run a {framework} application then connected it to your Hazelcast Cloud account. +Then you stored data using your app and Hazelcast Cloud. When you shut down the app, containerized it and run again on Docker, +you saw the data is not lost. Then you deployed the app to Kubernetes and saw that data is shared between microservices. +As a last step, you ran integration tests against hazelcast-{framework-short} that was deployed in a Kubernetes cluster.