{"id":20695771,"url":"https://github.com/ibm-cloud/jpetstore-kubernetes","last_synced_at":"2025-04-22T20:24:57.317Z","repository":{"id":55846160,"uuid":"134912072","full_name":"IBM-Cloud/jpetstore-kubernetes","owner":"IBM-Cloud","description":"Modernize and Extend: JPetStore on IBM Cloud Kubernetes Service","archived":false,"fork":false,"pushed_at":"2023-03-24T14:49:32.000Z","size":76845,"stargazers_count":23,"open_issues_count":2,"forks_count":41,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-29T18:36:29.845Z","etag":null,"topics":["demo","docker","go","helm","ibm-cloud","ibm-cloud-solutions","image-classification","image-recognition","istio","java","jpetstore","kubernetes","kubernetes-cluster","kubernetes-service","mms-capabilities","toolchain","twilio"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IBM-Cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-25T22:59:31.000Z","updated_at":"2025-03-03T14:57:39.000Z","dependencies_parsed_at":"2024-11-17T00:23:22.822Z","dependency_job_id":null,"html_url":"https://github.com/IBM-Cloud/jpetstore-kubernetes","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fjpetstore-kubernetes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fjpetstore-kubernetes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fjpetstore-kubernetes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fjpetstore-kubernetes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM-Cloud","download_url":"https://codeload.github.com/IBM-Cloud/jpetstore-kubernetes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250317052,"owners_count":21410674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["demo","docker","go","helm","ibm-cloud","ibm-cloud-solutions","image-classification","image-recognition","istio","java","jpetstore","kubernetes","kubernetes-cluster","kubernetes-service","mms-capabilities","toolchain","twilio"],"created_at":"2024-11-17T00:10:51.859Z","updated_at":"2025-04-22T20:24:57.309Z","avatar_url":"https://github.com/IBM-Cloud.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Modernize and Extend: JPetStore on IBM Cloud Kubernetes Service\n\nThis demo modernizes an existing Java web application (JPetStore) by:\n\n1. building Docker containers from the legacy stack\n2. moving the app to [IBM Cloud Kubernetes Service](https://www.ibm.com/cloud/container-service)\n3. and extending it with image(visual) classification and [Twilio](https://www.twilio.com/) text messaging (or a web chat interface).\n\nIBMers can access the demo script and additional collateral from [here](https://github.ibm.com/Bluemix/cloud-portfolio-solutions/tree/master/demos/modernize-jpetstore).\n\n![](readme_images/architecture_new.png)\n\n[![Containerized Applications with IBM Cloud Kubernetes Service](readme_images/youtube_play.png)](https://youtu.be/26RjSa0UZp0 \"Containerized Applications with IBM Cloud Kubernetes\")\n\n## Before you begin\n\nFollow the below steps to create IBM Cloud services and resources used in this demo. You will create a Kubernetes cluster, and an optional [Twilio](https://www.twilio.com/) account (if you want to shop for pets using text messaging).\n\n1. If you do not have Docker or Kubernetes tooling installed, see [Setting up the IBM Cloud Developer Tools CLI](https://cloud.ibm.com/docs/cli?topic=cloud-cli-getting-started#step1-install-idt).\n\n2. Set up a cluster by going to the [Kubernetes Service on IBM Cloud](http://www.ibm.com/cloud/container-service) and [provision a Standard **Paid** cluster](https://cloud.ibm.com/docs/containers/container_index.html#clusters) (it might take up to 15 minutes to provision, so be patient). A Free cluster will *not* work because this demo uses Ingress resources.\n\n3. Follow the instructions in the **Access** tab of your cluster to gain access to your cluster using [**kubectl**](https://kubernetes.io/docs/reference/kubectl/overview/).\n\n4. **Optionally** visit [Twilio](http://twilio.com), sign up for a free account and **buy a number** with MMS capabilities by creating a project/feature on the Dashboard. Locate the **Account SID** and **Auth Token** from the API Credentials in the [dashboard](https://www.twilio.com/console/sms/dashboard#). Locate you **Phone Number** on the respective [Twilio page](https://www.twilio.com/console/phone-numbers/incoming).\n\n## Automated deployment\n\nA toolchain has been created and automates deployment of the demo. You will still need to manually configure Twilio as described in the Manual deployment section.\n\n[![Create toolchain](https://cloud.ibm.com/devops/graphics/create_toolchain_button.png)](https://cloud.ibm.com/devops/setup/deploy/?repository=https%3A//github.com/IBM-Cloud/jpetstore-kubernetes)\n\nOnce the toolchain has completed, the applications will be available at `https://jpetstore.\u003cyour-cluster-ingress-domain\u003e` and `https://mmssearch.\u003cyour-cluster-ingress-domain\u003e`.\n\nThe toolchain includes a stage named **UNINSTALL (manual)**. This stage can only be triggered manually and will remove all resources created by the toolchain.\n\n## Manual deployment\n\nTo manually deploy the demo, follow the below steps.\n\n### Clone the demo to your laptop\n\nClone the demo repository:\n\n```bash\ngit clone https://github.com/ibm-cloud/jpetstore-kubernetes\ncd jpetstore-kubernetes\n```\n\n#### Code structure\n\n| Folder | Description |\n| ---- | ----------- |\n|[**jpetstore**](/jpetstore)| Traditional Java JPetStore application |\n|[**mmssearch**](/mmssearch)| New Golang microservice (used to identify the content of an image) |\n|[**helm**](/helm)| Helm charts for templated Kubernetes deployments |\n|[**pet-images**](/pet-images)| Pet images (which can be used for the demo) |\n\n### Create a Kubernetes secret\n\n1. Create a file with the name **mms-secrets.json** by using the existing template:\n\n   ```bash\n   # from jpetstore-kubernetes directory\n   cd mmssearch\n   cp mms-secrets.json.template mms-secrets.json\n   ```\n\n2. Run `ibmcloud ks cluster get --cluster CLUSTER_NAME` to get your **Ingress Subdomain** (make sure to replace CLUSTER_NAME with the name of the cluster you created above).\n\n3. Open **mms-secrets.json** file and update the **Ingress Subdomain** in the **jpetstoreurl** field. This allows the mmssearch microservice to find the images that are part of the message back to the user.\n   Example: `http://jpetstore.yourclustername.us-south.containers.appdomain.cloud `\n\n\n### Set up Twilio (optional)\n\nThis step is only required if you want to use MMS text messaging during the demo (which is not possible in many countries outside the U.S.).\n\nSkip this section if you only want to interact using the web chat.\n\n1. Visit [Twilio](http://twilio.com), sign up for a free account and **buy a number** with MMS capabilities by creating a project/feature on the Dashboard.\n2. Open the **mms-secrets.json** file and replace:\n\n   1.  **sid** and **token** values with your **AccountSID** and the **AuthToken** from the Twilio Account Dashboard.\n   2.  **number** with the number you just purchased in the format **+1XXXYYYZZZZ**.\n\n3. Configure Twilio to send messages to the MMSSearch service\n   1. Go to **Manage Numbers** on Twilio dashboard by clicking on **All Products \u0026 Services** on the left pane then click on your number.\n   2. In the **Messaging** section of the **Configure** page under **A message comes in**, select **Webhook**, set the URL to `http://mmssearch.\u003cIngress Subdomain\u003e/sms/receive` and the METHOD to **HTTP POST**\n\n![](readme_images/twilio.png)\n\n\n### Create Kubernetes secrets\n\nNext, use the `kubectl` command to allow your Kubernetes cluster access to the secrets you just created. This will allow it to access the JPetStore frontend and Twilio services:\n\n```bash\n# from the jpetstore-kubernetes directory\ncd mmssearch\nkubectl create secret generic mms-secret --from-file=mms-secrets=./mms-secrets.json\n```\n\n## Build and push the container images\n\nThe docker images for each of the micro-services need to be built and then pushed to a container registry. Here are the steps for pushing to your IBM Cloud private registry, but be aware that you could also push them to a public registry.\n\n1. Identify your registry **Namespace** with `ibmcloud cr namespaces` or create a new one using `ibmcloud cr namespace-add \u003cNAMESPACE\u003e`\n\n2. Set MYNAMESPACE env var to your namespace.\n\n   `export MYNAMESPACE=\u003cNAMESPACE\u003e`\n\n3. Identify your **Container Registry** (e.g. us.icr.io) by running `ibmcloud cr info`.\n\n4. Set MYREGISTRY env var to your registry.\n\n   `export MYREGISTRY=\u003cREGISTRY\u003e`\n\n5. Make sure that the steps above worked by running `echo ${MYREGISTRY}/${MYNAMESPACE}` . You should see output similar to `us.icr.io/mynamespace`\n\n6. Build and push the **jpetstoreweb** image. Run these commands as they are. You do not need to replace any of the values belwo:\n\n   ```bash\n   # from the jpetstore-kubernetes directory\n   cd jpetstore\n   docker build . -t ${MYREGISTRY}/${MYNAMESPACE}/jpetstoreweb\n   docker push ${MYREGISTRY}/${MYNAMESPACE}/jpetstoreweb\n   ```\n   If you see `Unauthorized ` while pushing the image, run `ibmcloud cr login` to ensure you are logged into the IBM Cloud and have access to the container registry.\n\n7. Next, build and push the **jpetstoredb** image:\n\n   ```bash\n   # from the jpetstore directory\n   cd db\n   docker build . -t ${MYREGISTRY}/${MYNAMESPACE}/jpetstoredb\n   docker push ${MYREGISTRY}/${MYNAMESPACE}/jpetstoredb\n   ```\n\n8. Build and push the **mmssearch** image:\n\n   ```bash\n   # from the db directory\n   cd ../../mmssearch\n   docker build . -t ${MYREGISTRY}/${MYNAMESPACE}/mmssearch\n   docker push ${MYREGISTRY}/${MYNAMESPACE}/mmssearch\n   ```\n\n9. Finally make sure that all three images have been successfully pushed to the IBM Cloud container registry by running `ibmcloud cr images --restrict $MYNAMESPACE` .\n\n## Deploy the application\n\nThere are two different ways to deploy the three micro-services to a Kubernetes cluster:\n\n- Using [Helm](https://helm.sh/) to provide values for templated charts (recommended)\n- Or, updating yaml files with the right values and then running  `kubectl create`\n\n### Option 1: Deploy with Helm (recommended)\n\n1. Install [Helm](https://docs.helm.sh/using_helm/#installing-helm). (`brew install kubernetes-helm` on MacOS)\n\n2. Find your **Ingress Subdomain** by running `ibmcloud ks cluster get --cluster YOUR_CLUSTER_NAME` , it will look similar to \"mycluster.us-south.containers.appdomain.cloud\".\n\n3. Open `../helm/modernpets/values.yaml` and make the following changes.\n\n    - Update `repository` and replace `\u003cREGISTRY\u003e` with your Container Registry and `\u003cNAMESPACE\u003e` with your Container Registry namespace.\n    - Update `hosts` and replace `\u003cIngress Subdomain\u003e` with your Ingress Subdomain.\n\n4. Repeat the previous step and update `../helm/mmssearch/values.yaml` with the same changes.\n\n5. Next, install JPetStore and Visual Search using the helm yaml files you just created:\n\n    ```bash\n    # Change into the helm directory\n    cd ../helm\n\n    # Create the JPetstore app\n    helm install jpetstore ./modernpets\n\n    # Ceate the MMSSearch microservice\n    helm install mmssearch ./mmssearch\n    ```\n\n### Option 2: Deploy using YAML files\n\nIf you did not deploy using Helm, you can deploy using the yaml files and kubectl. For this option, you need to update the YAML files to point to your registry namespace and Kubernetes cluster Ingress subdomain:\n\n1. Edit **jpetstore/jpetstore.yaml** and **jpetstore/jpetstore-mmssearch.yaml** and replace all instances of:\n\n  - `\u003cCLUSTER DOMAIN\u003e` with your Ingress Subdomain (`ibmcloud ks cluster get --cluster CLUSTER_NAME`)\n  - `\u003cREGISTRY NAMESPACE\u003e` with your Image registry URL. For example:`us.icr.io/mynamespace`\n\n2. `kubectl create -f jpetstore.yaml`  - This creates the JPetstore app and database microservices\n3. `kubectl create -f jpetstore-mmssearch.yaml`  - This creates the MMSSearch microservice\n\n## You're Done!\n\nYou are now ready to use the UI to shop for a pet or query the store by sending it a picture of what you're looking at:\n\n1. Access the java jpetstore application web UI for JPetstore at `http://jpetstore.\u003cIngress Subdomain\u003e/shop/index.do`\n\n   ![](readme_images/petstore.png)\n\n2. Access the mmssearch app and start uploading images from `pet-images` directory.\n\n   ![](readme_images/webchat.png)\n\n3. If you configured Twilio, send a picture of a pet to your Twilio number via your phone. The app should respond with an available pet from the store or or with a message that this type of pet is not available:\n\n\n\n   ![](readme_images/sms.png)\n\n## Using your Mac to send text messages to Twilio\n\nIf you'd like to send and receive texts from the pet store on your Mac, do the following steps:\n\n1. Ensure your iPhone is capable of forwarding text messages to your Mac.\n    - See this [Apple support document](https://support.apple.com/en-us/HT208386).\n    - If the Text Message Forwarding option is not present, confirm that your Apple ID is enabled under **Send \u0026 Receive**.\n2. Access the [Getting Started page](https://www.twilio.com/console/sms/getting-started/build) from your Twilio account home page\n3. In the **Send a Message** widget, enter the Twilio number you bought into the **To:** text field.\n4. Add a message to the **Body** text field and click the **Make Request** button.\n5. After receiving the message on your Mac, drag and drop an image into the iMessage window\n\n## Logging\n\nCheck this tutorial - [Analyze logs and monitor application health with LogDNA and Sysdig](https://cloud.ibm.com/docs/solution-tutorials?topic=solution-tutorials-application-log-analysis)\n\n## Monitoring\n\nCheck this tutorial - [Analyze logs and monitor application health with LogDNA and Sysdig](https://cloud.ibm.com/docs/solution-tutorials?topic=solution-tutorials-application-log-analysis#monitor_cluster_sysdig)\n\n### Load Generation for demo purposes\n\nIn a demo situation, you might want to generate load for your application (it will help illustrate the various features in the dashboard). This can be done through the loadtest package:\n\n```bash\n# Use npm to install loadtest\nnpm install -g loadtest\n\n# Geneate increasing load (make sure to replace \u003cIngress Subdomain\u003e with your ingress subdomain)\nloadtest http://jpetstore.\u003cIngress Subdomain\u003e/\n```\n\n## Clean up\n\n```bash\n# Use \"helm delete\" to delete the two apps\nhelm uninstall jpetstore\nhelm uninstall mmssearch\n\n# Delete the secrets stored in our cluster\nkubectl delete secret mms-secret\n\n# Remove the container images from the registry\nibmcloud cr image-rm ${MYREGISTRY}/${MYNAMESPACE}/mmssearch\nibmcloud cr image-rm ${MYREGISTRY}/${MYNAMESPACE}/jpetstoreweb\nibmcloud cr image-rm ${MYREGISTRY}/${MYNAMESPACE}/jpetstoredb\n\n# Delete your entire cluster!\nibmcloud ks cluster rm --cluster yourclustername\n```\n\n## Troubleshooting\n\n### The toolchain DEPLOY fails with an UPGRADE FAILED error\n\nThe DEPLOY log shows:\n```\nError: UPGRADE FAILED: \"mmssearch\" has no deployed releases\n```\n\nThere is a known helm issue. If an install of a given release fails the very first time it was attempted, all subsequent install (upgrade) attempts of that release will fail.  To fix, for example in the case of the exact error above related to mmssearch, you can issue a `helm delete mmssearch --purge` command. This command can be added in the deploy script right before issuing the `helm upgrade --install ....` command.\n\n\n## Related Content\n\nIBM Cloud solution tutorial: [Migrate web applications from Virtual Machines to Kubernetes](https://cloud.ibm.com/docs/solution-tutorials?topic=solution-tutorials-vm-to-containers-and-kubernetes)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud%2Fjpetstore-kubernetes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm-cloud%2Fjpetstore-kubernetes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud%2Fjpetstore-kubernetes/lists"}