{"id":18429156,"url":"https://github.com/openliberty/sample-acmegifts","last_synced_at":"2026-03-13T11:33:01.717Z","repository":{"id":25533747,"uuid":"104364894","full_name":"OpenLiberty/sample-acmegifts","owner":"OpenLiberty","description":"A gift giving and budgeting application written using MicroProfile and Liberty","archived":false,"fork":false,"pushed_at":"2023-02-04T07:57:43.000Z","size":3012,"stargazers_count":17,"open_issues_count":10,"forks_count":13,"subscribers_count":24,"default_branch":"main","last_synced_at":"2024-04-15T08:16:26.052Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenLiberty.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}},"created_at":"2017-09-21T15:21:04.000Z","updated_at":"2022-10-31T14:42:49.000Z","dependencies_parsed_at":"2023-02-15T06:45:45.496Z","dependency_job_id":null,"html_url":"https://github.com/OpenLiberty/sample-acmegifts","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/OpenLiberty%2Fsample-acmegifts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-acmegifts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-acmegifts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenLiberty%2Fsample-acmegifts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenLiberty","download_url":"https://codeload.github.com/OpenLiberty/sample-acmegifts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223286329,"owners_count":17120002,"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":[],"created_at":"2024-11-06T05:16:02.924Z","updated_at":"2026-03-13T11:33:01.684Z","avatar_url":"https://github.com/OpenLiberty.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"NOTE: The `front-end-ui` microservice is currently undergoing an upgrade of Angular (https://github.com/OpenLiberty/sample-acmegifts/issues/50). In the meantime, please use the GUI as an example only as it may be prone to some issues. \n\n# Acme Gifts [![Build Status](https://travis-ci.org/OpenLiberty/sample-acmegifts.svg?branch=master)](https://travis-ci.org/OpenLiberty/sample-acmegifts)\nA social gift giving application built on the [MicroProfile](http://microprofile.io/) platform\n\n## Table of Contents\n\n* [What is Acme Gifts?](#what-is-acme-gifts)\n* [Getting Started](#getting-started)\n* [Using the Application](#using-the-application)\n* [Microservices](#microservices)\n* [Configuration and Customization](#configuration-and-customization)\n* [Using Acme Gifts](#using-acme-gifts)\n* [Running Acme Gifts on Minikube](#running-acme-gifts-on-minikube)\n\n## What is Acme Gifts?\n\nAcme Gifts is a Java microservices application that was designed to run on Open Liberty and showcase MicroProfile. The front-end was written using Angular 2, and the back-end uses microservices written to the MicroProfile 1.2 specification. The MicroProfile services used include Config 1.1, Fault Tolerance 1.0, and JWT 1.0. Each service, as well as the front end, was designed to run in an independent Liberty server instance.\n\nAcme Gifts provides a platform for users to create and join groups and exchange gifts within those groups. For example, a specific user may be a part of a co-workers group as well as a friends or family group. In each of these groups, occasions can be created (i.e. John's Birthday, Stacy's Retirement, etc.) to occur on a specific date. Users in that group can then pledge a contribution to that occasion, and when the occasion occurs, the recipient will be notified via Twitter of the total sum that their group raised for them. They are then informed to choose an item off of their predefined wish-list for the allotted sum. \n\n![alt text](collateral/architecture.bmp)\n\n\n## Getting Started\n\n### Prereqs \n\n* Maven or Gradle - [Maven](https://maven.apache.org/download.cgi) v3.5.0 must be installed and set on the environment path. Users may use their installed [Gradle](https://gradle.org/install/) or use the included Gradle wrapper (Example usage: `./gradlew libertyStart` or `gradlew.bat libertyStart` for Windows).\n\n* Java 8 - Java 8 must be used to compile and run this project.\n\n* MongoDB - [MongoDB](https://www.mongodb.com/) v3.4.6 must be installed and either set on the environment path or set using the \u003cmongo.path\u003e property in sample-acmegifts/pom.xml or sample-acmegifts/build.gradle.\n\n* Running in admin mode (Windows only) - Maven commands must be run in admin mode to ensure that the Mongo databases are successfully auto-started in the background\n\n### Quick start\nDownload the repository and navigate into it:\n\n\tgit clone https://github.com/OpenLiberty/sample-acmegifts.git\n\tcd sample-acmegifts\n\t\nBuild and start the full suite of microservices that make up the Acme Gifts application with the build tool of choice:\n\n#### Maven\n\n    mvn clean install\n    mvn package -P start-databases,start-servers -pl run-app\n\n#### Gradle\n\t\n\tgradle clean build\n\tgradle libertyStart\n\nGo to https://localhost:5064 if using the default host and ports. Otherwise, use the custom host and ports defined for the front-end-ui service.\n\n## Using the Application\n\n### Accepting Certificates\n\nAcme Gifts is secured with self-signed certificates. The certificate is generated when the \n'shared-keystore' project is built, and copied into each of the other projects.\n   \n   **IMPORTANT** \n   After the microservices are started, the first time you use Acme Gifts, you will need to accept\n   the self-signed certificate browser challenge.\n\n   **FIREFOX NOTE**\n   Firefox requires that certificate be accepted for each distinct hostname and port combination. \n   Consequently, you will need to go to each of the following URLs and accept the self signed \n   certificate challenges.\n\n    Landing Page: https://localhost:5064/login  \n    User microservice: https://localhost:5051/users  \n    Group microservice: https://localhost:5054/groups  \n    Occasion microservice: https://localhost:5057/occasions  \n    Authorization microservice: https://localhost:5066/auth\n\n   If you are using the default hosts and ports, you can use the links as shown. Otherwise, replace the\n   host and ports for each of the links with your custom host and ports.\n\nNote: The following error can be ignored while accepting certificates:\n\n\u003e HTTP Error 401 \nError: CWWKS5525E: An error was encountered while authenticating a user by using MicroProfile JSON Web Token (JWT).\n\n### Navigating the UI\n\nThe user interface is composed of a four main portals: \n\n1. Landing/Login - Allows users to create an account, sign into their account, or sign in with Twitter. \n2. User - Displays information about the authenticated user including a list of groups that the user is a part of, and how much money he or she is pledging. \n3. Group - Displays information for a specific group including the members and occasions of that group.\n4. Occasion - Displays information for a specific occasion including the date, recipient and organizer. \n\nThe life-cycle of users, groups, and occasions (creating, editing, deleting) can be managed through these portals.\n\n## Microservices\n\nAcme Gifts has a microservice architecture. It is made up of several services that are deployed independently. Below are the details of each microservices. To build and start a specific service, complete any configuration steps and issue the Maven commands in the \"Build and Start\" section.\n\n* [User Microservice](#user-microservice)\n* [Group Microservice](#group-microservice)\n* [Occasion Microservice](#occasion-microservice)\n* [Notification Microservice](#notification-microservice)\n* [Notification Microservice v1_1](#notification-microservice-v1_1)\n* [Frontend-UI](#frontend-ui)\n* [Auth Microservice](#auth-microservice)\n\n### User Microservice:\nThe user microservice manages the lifecycle of users and user login within the Acme Gifts application. Users have the added ability to login using Twitter credentials.\n\n#### Configuration:\n\n* To allow users to login using Twitter, complete the [Twitter Configuration](#twitter-configuration)\n\n#### Build and Start\n##### Maven\nIssue the following commands from within sample-acmegifts/microservice-user directory\n\n    mvn clean package install\n    mvn exec:exec@start-database\n    mvn liberty:start-server\n    \n##### Gradle\nIssue the following commands from within sample-acmegifts/microservice-user directory\n\n\tgradle clean build\n\tgradle libertyStart\n\nCalling `libertyStart` automatically triggers `startDatabase`.\n\t\n### Group Microservice:\n\nThe group microservice manages the lifecycle of groups within the Acme Gifts application. \n\n#### Build and Start\n##### Maven\nIssue the following commands from within sample-acmegifts/microservice-group directory\n\n    mvn clean package install\n    mvn exec:exec@start-database\n    mvn liberty:start-server\n    \n##### Gradle\nIssue the following commands from within sample-acmegifts/microservice-group directory\n\n\tgradle clean build\n\tgradle libertyStart\n\nCalling `libertyStart` automatically triggers `startDatabase`.\n    \n### Occasion Microservice:\n\nThe occasion microservice manages the lifecycle and orchestration of occasions within the Acme Gifts application. \n\n#### Build and Start\n##### Maven\nIssue the following commands from within sample-acmegifts/microservice-occasion directory\n\n    mvn clean package install\n    mvn exec:exec@start-database\n    mvn liberty:start-server\n    \n##### Gradle\nIssue the following commands from within sample-acmegifts/microservice-occasion directory\n\n\tgradle clean build\n\tgradle libertyStart\n\nCalling `libertyStart` automatically triggers `startDatabase`.\n    \n### Notification Microservice:\n\nThe notification microservice is a basic admin notification service that logs to a file when \nscheduled occasions take place.\n\n#### Configuration:\nUpdate the location/name of the administrative log and fallback log.\n##### Maven\nUpdate the entry located under the \"Optional Microservice Configuration\" label in the \"properties\" section of the sample-acmegifts/microservice-notification pom.xml. The default value is: \n   \n   `notification.log.file = ${project.build.directory}/logs/notifications.log`\n   \n##### Gradle\nFor Gradle, update the entry defined in the ExtraPropertiesExtension (`ext`). The default value is:\n   \n   `notificationLogFile = new File(\"$buildDir/logs/notifications.log\")`\n   \n   \n#### Build and Start\n##### Maven\nIssue the following commands from within sample-acmegifts/microservice-notification directory\n\n    mvn clean package install\n    mvn liberty:start-server\n\t\n##### Gradle\nIssue the following comamnds from within sample-acmegifts/microservice-notification directory\n\n\tgradle clean build\n\tgradle libertyStart\n\n### Notification Microservice v1_1:\nThe notification microservice v1_1 is a notification service that logs to a file for administrative purposes and sends twitter notifications to those users associated to the occasion. To receive twitter notifications, users must have a valid twitter handle in their user profile.\n\n#### Configuration:\n* To allow users to receive tweets, complete the [Twitter Configuration](#twitter-configuration) (This may have already been done when configuring the user microservice)\n\n* Optionally, Update the location/name of the administrative log and fallback log.\n##### Maven\nUpdate the entry located under the \"Optional Microservice Configuration\" label in the \"properties\" section of the sample-acmegifts/microservice-notification_v1_1 pom.xml. The default values are: \n   \n   `notification_1_1.log.file = ${project.build.directory}/logs/${project.build.directory}/logs/notifications_1_1.log`\n   \n   `notification_1_1.fallback.log.file = ${project.build.directory}/logs/notifications_1_1_fallback.log`   \n   \n##### Gradle\nUpdate the entries defined in the ExtraPropertiesExtension (`ext`). The default values are:\n   \n   `notification_v1_1_logfile = new File(\"$buildDir/logs/notifications_1_1.log\")`\n   \n   `notification_v1_1_fallback_logfile = new File(\"$buildDir/logs/notifications_1_1_fallback.log\")`\n\n#### Build and Start\n##### Maven\nIssue the following commands from within sample-acmegifts/microservice-notification_v1_1 directory\n\n    mvn clean package install\n    mvn liberty:start-server\n\t\n##### Gradle\nIssue the following commands from within sample-acemgifts/microservice-notification_v1_1 directory\n\n\tgradle clean build\n\tgradle libertyStart\n\n### Frontend UI:\n\nThe Acme Gifts UI is written in Angular 2 and built in Maven using the frontend-maven-plugin. This plugin downloads and installs local versions of Node and NPM which makes calls to Angular CLI to install and build the source code. Gradle uses [ysb33r's Gradle nodejs plugin](https://gitlab.com/ysb33rOrg/nodejs-gradle-plugin) to similarly install local versions of Node and NPM to build the source code. Compiled files are placed in src/main/webapp which builds into a war to deploy in Liberty.\n\n#### Build and Start\n##### Maven\nIssue the following commands from within sample-acmegifts/front-end-ui directory\n\n    mvn clean package install\n    mvn liberty:start-server\n    \n##### Gradle\nIssue the following commands from within sample-acmegifts/front-end-ui directory\n\n\tgradle clean build\n\tgradle libertyStart\n\n### Auth Microservice:\n\nThe auth microservice manages the creation and validation of JSON Web Tokens (JWTs) used to secure the Acme  Gifts application.\n\n#### Build and Start\n##### Maven\nIssue the following commands from within sample-acmegifts/microservice-auth directory\n\n    mvn clean package install\n    mvn liberty:start-server\n    \n##### Gradle\nIssue the following commands from within sample-acmegifts/microservice-auth directory\n\n\tgradle clean build\n\tgradle libertyStart\n\t\n## Configuration and Customization\n\n### Twitter Configuration\nAcme Gifts provides the ability for users to login using Twitter credentials as well as receive direct messages when occasions occur. Note that in order for occasion recipients to be notified of the occasion with a direct message, they must be following the twitter account being used on behalf of Acme Gifts.  \n\nFollow the steps below to configure an existing twitter account for Acme Gifts.\n\n#### Find your Twitter generated keys/secrets/tokens.  \nObtain the app consumer key, consumer secret, user access token and user access secret for the desired account.\nThese values can be obtained from a valid twitter account application to be used on behalf of the Acme Gifts application. \nThe steps for setting up and obtaining the needed values:\n\n  1. Go to: https://apps.twitter.com/ to register the 'Acme Gifts' application under a \n    valid twitter account. This account will be used on behalf of the Gifts application.\n    NOTE: Be sure to fill in the 'Callback URL' section when creating the application. \n    The entry can be a dummy URL. If the application exists already, go to the 'Settings' tab \n    and make sure something was specified in the 'Callback URL' section.\n\n  2. Under the Details tab, modify the access level to 'Read, write, and direct messages'.\n\n  3. Under the 'Key and Access Tokens' tab, generate access token/secret.\n\n  4. Replace CHANGE_ME with the consumer key/secret and the access token/secret generated values (see below).\n\n#### Specify your Twitter credentials to your build tool   \n##### Maven\nThe properties to update are located under the \"Optional Microservice Configuration\" label in the \"properties\" section of sample-acmegifts/pom.xml. \n\n##### Gradle \nThe properties are located in the ExtraPropertiesExtension (ext) of sample-acmegifts/build.gradle. Update the CHANGE_ME values with valid twitter generated keys/secrets/tokens.\n\n\n\n   \n### Host and Port Configuration\nYou can customize the ports and host names used by the microservices and their resources.\nThese values can be updated under the \"Optional Microservice Configuration\" label in the \"properties\" \nsection of the Acme Gifts pom.xml. These are the defaults:\n\n    - user.hostname = localhost\n    - user.http.port = 5050  \n    - user.https.port = 5051  \n    - user.mongo.port = 5052  \n    - user.mongo.hostname = localhost\n\n    - group.hostname = localhost\n    - group.http.port = 5053  \n    - group.https.port = 5054  \n    - group.mongo.port = 5055  \n    - group.mongo.hostname = localhost\n\n    - occasion.hostname = localhost\n    - occasion.http.port = 5056  \n    - occasion.https.port = 5057  \n    - occasion.mongo.port = 5058  \n    - occasion.mongo.hostname = localhost\n\n    - notification.http.port = 5059  \n    - notification.https.port = 5060  \n\n    - notification_1_1.http.port = 5061  \n    - notification_1_1.https.port = 5062  \n\n    - frontend.http.port = 5063  \n    - frontend.https.port = 5064  \n    - frontend.hostname = localhost  \n\n    - auth.http.port = 5065\n    - auth.https.port = 5066\n    - auth.hostname = localhost\n  \n### Bootstrapping Data \nThe Acme Gifts application can be started with custom bootstrap data. Users, groups, and occasions can be preloaded for demo purposes. \nCheckout the run-app [readme](run-app/README.md) for usage details.\n\n## Using Acme Gifts\nFor details on how to use Acme Gifts checkout [Using Acme Gifts](front-end-ui/README.md).\n\n## Running Acme Gifts on Minikube\nAcme Gifts can run on a minikube Kubernetes cluster.\n\n### Pre-reqs\n1. Minikube.\n1. Kubectl.\n1. Docker.\n1. Virtual Machine driver (i.e. VirtualBox).\n\n### Usage:\nThe following instructions show how to run pre-built images of the application from Docker Hub. These images do not contain the \ncustom information required to perform actions such as logging-in with twitter or using the twitter notification support \nprovided by `notification microservice v1_1`. If you wish to perform twitter related action, you will need to build your own images\nusing the provided `docker-build` script. Before executing the script, update the following entries:\n  - -Dtwitter.app.consumer.key=CHANGE_ME \\\n  - -Dtwitter.app.consumer.secret=CHANGE_ME \\\n  - -Dtwitter.user.access.token=CHANGE_ME \\\n  - -Dtwitter.user.access.secret=CHANGE_ME \\\n\nSee [Twitter Configuration](#twitter-configuration) on how to obtain the needed information.\n\nNote that if you want the resulting images to be used inside a minikube environment, make sure that you target your Docker CLI at the minikube Docker Engine before building using the following command: `eval $(minikube docker-env)`.\n\n1. Start minikube:\n\n   `minikube start`\n\t\n1. Ensure that ingress is enabled:\n   \n   `minikube addons enable ingress`\n   \n1. Ensure `kubectl` is targeting your cluster (as it would be after a `minikube start`) and then run the command:\n   \n   `kubectl apply -f kubernetes.yml`\n\n1. Wait for all of the pods to show as running when the following commands is executed:\n   \n   `kubectl get pods`\n   \n1.  Access the Acme Gifts UI in a browser using the IP address returned by:\n\n    `minikube ip`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fsample-acmegifts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenliberty%2Fsample-acmegifts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenliberty%2Fsample-acmegifts/lists"}