NOTE: The front-end-ui
microservice is currently undergoing an upgrade of Angular (#50). In the meantime, please use the GUI as an example only as it may be prone to some issues.
A social gift giving application built on the MicroProfile platform
- What is Acme Gifts?
- Getting Started
- Using the Application
- Microservices
- Configuration and Customization
- Using Acme Gifts
- Running Acme Gifts on Minikube
Acme 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.
Acme 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.
-
Maven or Gradle - Maven v3.5.0 must be installed and set on the environment path. Users may use their installed Gradle or use the included Gradle wrapper (Example usage:
./gradlew libertyStart
orgradlew.bat libertyStart
for Windows). -
Java 8 - Java 8 must be used to compile and run this project.
-
MongoDB - MongoDB v3.4.6 must be installed and either set on the environment path or set using the <mongo.path> property in sample-acmegifts/pom.xml or sample-acmegifts/build.gradle.
-
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
Download the repository and navigate into it:
git clone https://github.com/OpenLiberty/sample-acmegifts.git
cd sample-acmegifts
Build and start the full suite of microservices that make up the Acme Gifts application with the build tool of choice:
mvn clean install
mvn package -P start-databases,start-servers -pl run-app
gradle clean build
gradle libertyStart
Go 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.
Acme Gifts is secured with self-signed certificates. The certificate is generated when the 'shared-keystore' project is built, and copied into each of the other projects.
IMPORTANT After the microservices are started, the first time you use Acme Gifts, you will need to accept the self-signed certificate browser challenge.
FIREFOX NOTE Firefox requires that certificate be accepted for each distinct hostname and port combination. Consequently, you will need to go to each of the following URLs and accept the self signed certificate challenges.
Landing Page: https://localhost:5064/login
User microservice: https://localhost:5051/users
Group microservice: https://localhost:5054/groups
Occasion microservice: https://localhost:5057/occasions
Authorization microservice: https://localhost:5066/auth
If you are using the default hosts and ports, you can use the links as shown. Otherwise, replace the host and ports for each of the links with your custom host and ports.
Note: The following error can be ignored while accepting certificates:
HTTP Error 401 Error: CWWKS5525E: An error was encountered while authenticating a user by using MicroProfile JSON Web Token (JWT).
The user interface is composed of a four main portals:
- Landing/Login - Allows users to create an account, sign into their account, or sign in with Twitter.
- 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.
- Group - Displays information for a specific group including the members and occasions of that group.
- Occasion - Displays information for a specific occasion including the date, recipient and organizer.
The life-cycle of users, groups, and occasions (creating, editing, deleting) can be managed through these portals.
Acme 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.
- User Microservice
- Group Microservice
- Occasion Microservice
- Notification Microservice
- Notification Microservice v1_1
- Frontend-UI
- Auth Microservice
The 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.
- To allow users to login using Twitter, complete the Twitter Configuration
Issue the following commands from within sample-acmegifts/microservice-user directory
mvn clean package install
mvn exec:exec@start-database
mvn liberty:start-server
Issue the following commands from within sample-acmegifts/microservice-user directory
gradle clean build
gradle libertyStart
Calling libertyStart
automatically triggers startDatabase
.
The group microservice manages the lifecycle of groups within the Acme Gifts application.
Issue the following commands from within sample-acmegifts/microservice-group directory
mvn clean package install
mvn exec:exec@start-database
mvn liberty:start-server
Issue the following commands from within sample-acmegifts/microservice-group directory
gradle clean build
gradle libertyStart
Calling libertyStart
automatically triggers startDatabase
.
The occasion microservice manages the lifecycle and orchestration of occasions within the Acme Gifts application.
Issue the following commands from within sample-acmegifts/microservice-occasion directory
mvn clean package install
mvn exec:exec@start-database
mvn liberty:start-server
Issue the following commands from within sample-acmegifts/microservice-occasion directory
gradle clean build
gradle libertyStart
Calling libertyStart
automatically triggers startDatabase
.
The notification microservice is a basic admin notification service that logs to a file when scheduled occasions take place.
Update the location/name of the administrative log and fallback log.
Update 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:
notification.log.file = ${project.build.directory}/logs/notifications.log
For Gradle, update the entry defined in the ExtraPropertiesExtension (ext
). The default value is:
notificationLogFile = new File("$buildDir/logs/notifications.log")
Issue the following commands from within sample-acmegifts/microservice-notification directory
mvn clean package install
mvn liberty:start-server
Issue the following comamnds from within sample-acmegifts/microservice-notification directory
gradle clean build
gradle libertyStart
The 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.
-
To allow users to receive tweets, complete the Twitter Configuration (This may have already been done when configuring the user microservice)
-
Optionally, Update the location/name of the administrative log and fallback log.
Update 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:
notification_1_1.log.file = ${project.build.directory}/logs/${project.build.directory}/logs/notifications_1_1.log
notification_1_1.fallback.log.file = ${project.build.directory}/logs/notifications_1_1_fallback.log
Update the entries defined in the ExtraPropertiesExtension (ext
). The default values are:
notification_v1_1_logfile = new File("$buildDir/logs/notifications_1_1.log")
notification_v1_1_fallback_logfile = new File("$buildDir/logs/notifications_1_1_fallback.log")
Issue the following commands from within sample-acmegifts/microservice-notification_v1_1 directory
mvn clean package install
mvn liberty:start-server
Issue the following commands from within sample-acemgifts/microservice-notification_v1_1 directory
gradle clean build
gradle libertyStart
The 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 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.
Issue the following commands from within sample-acmegifts/front-end-ui directory
mvn clean package install
mvn liberty:start-server
Issue the following commands from within sample-acmegifts/front-end-ui directory
gradle clean build
gradle libertyStart
The auth microservice manages the creation and validation of JSON Web Tokens (JWTs) used to secure the Acme Gifts application.
Issue the following commands from within sample-acmegifts/microservice-auth directory
mvn clean package install
mvn liberty:start-server
Issue the following commands from within sample-acmegifts/microservice-auth directory
gradle clean build
gradle libertyStart
Acme 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.
Follow the steps below to configure an existing twitter account for Acme Gifts.
Obtain the app consumer key, consumer secret, user access token and user access secret for the desired account. These values can be obtained from a valid twitter account application to be used on behalf of the Acme Gifts application. The steps for setting up and obtaining the needed values:
-
Go to: https://apps.twitter.com/ to register the 'Acme Gifts' application under a valid twitter account. This account will be used on behalf of the Gifts application. NOTE: Be sure to fill in the 'Callback URL' section when creating the application. The entry can be a dummy URL. If the application exists already, go to the 'Settings' tab and make sure something was specified in the 'Callback URL' section.
-
Under the Details tab, modify the access level to 'Read, write, and direct messages'.
-
Under the 'Key and Access Tokens' tab, generate access token/secret.
-
Replace CHANGE_ME with the consumer key/secret and the access token/secret generated values (see below).
The properties to update are located under the "Optional Microservice Configuration" label in the "properties" section of sample-acmegifts/pom.xml.
The properties are located in the ExtraPropertiesExtension (ext) of sample-acmegifts/build.gradle. Update the CHANGE_ME values with valid twitter generated keys/secrets/tokens.
You can customize the ports and host names used by the microservices and their resources. These values can be updated under the "Optional Microservice Configuration" label in the "properties" section of the Acme Gifts pom.xml. These are the defaults:
- user.hostname = localhost
- user.http.port = 5050
- user.https.port = 5051
- user.mongo.port = 5052
- user.mongo.hostname = localhost
- group.hostname = localhost
- group.http.port = 5053
- group.https.port = 5054
- group.mongo.port = 5055
- group.mongo.hostname = localhost
- occasion.hostname = localhost
- occasion.http.port = 5056
- occasion.https.port = 5057
- occasion.mongo.port = 5058
- occasion.mongo.hostname = localhost
- notification.http.port = 5059
- notification.https.port = 5060
- notification_1_1.http.port = 5061
- notification_1_1.https.port = 5062
- frontend.http.port = 5063
- frontend.https.port = 5064
- frontend.hostname = localhost
- auth.http.port = 5065
- auth.https.port = 5066
- auth.hostname = localhost
The Acme Gifts application can be started with custom bootstrap data. Users, groups, and occasions can be preloaded for demo purposes. Checkout the run-app readme for usage details.
For details on how to use Acme Gifts checkout Using Acme Gifts.
Acme Gifts can run on a minikube Kubernetes cluster.
- Minikube.
- Kubectl.
- Docker.
- Virtual Machine driver (i.e. VirtualBox).
The following instructions show how to run pre-built images of the application from Docker Hub. These images do not contain the
custom information required to perform actions such as logging-in with twitter or using the twitter notification support
provided by notification microservice v1_1
. If you wish to perform twitter related action, you will need to build your own images
using the provided docker-build
script. Before executing the script, update the following entries:
- -Dtwitter.app.consumer.key=CHANGE_ME \
- -Dtwitter.app.consumer.secret=CHANGE_ME \
- -Dtwitter.user.access.token=CHANGE_ME \
- -Dtwitter.user.access.secret=CHANGE_ME \
See Twitter Configuration on how to obtain the needed information.
Note 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)
.
-
Start minikube:
minikube start
-
Ensure that ingress is enabled:
minikube addons enable ingress
-
Ensure
kubectl
is targeting your cluster (as it would be after aminikube start
) and then run the command:kubectl apply -f kubernetes.yml
-
Wait for all of the pods to show as running when the following commands is executed:
kubectl get pods
-
Access the Acme Gifts UI in a browser using the IP address returned by:
minikube ip