Welcome to the Liberty app accelerator

An application builder to allow you to construct starter applications for building your projects with Liberty.

Liberty app accelerator is still in its early stages so we will be adding new technologies and capabilities to the page over time. For now, feel free to try it out and see how quickly you can have a fully fledged application. If you have any questions, comments or suggestions please raise an issue on our GitHub repository.

For an introduction see our blog post. To learn how the Liberty Starter can be used to create the image service for the Plants by WebSphere evolution from monolith to microservice, see our new article.

The current technologies we have are:

Rest

This provides you with the jaxrs-2.0 feature and the jsonp-1.0 feature.

Inside the project produced there is a application.rest package containing the LibertyRestEndpoint class. This adds a REST endpoint which you can access at /rest. There is also a test class named it.rest.LibertyRestEndpointTest that will test the REST endpoint to ensure it is working.

For the complete feature documentation, see the (jaxrs-2.0)[http://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/rwlp_feature_jaxrs-2.0.html] feature description in IBM Knowledge Center.

Servlet

This provides you with the servlet-3.1 feature.

Inside the project there is a application.servlet package containing the LibertyServlet class. This adds a servlet with an endpoint which you can access at /servlet. There is also a test class named it.servlet.LibertyServletTest that will test the servlet's endpoint to ensure it is working.

For the complete feature documentation, see the servlet-3.1 feature description in IBM Knowledge Center.

Spring Boot with Spring REST

This provides you with a SpringBoot application that will run on WebSphere Liberty.

Inside the project there is a application.springboot.web package containing two classes:

• SpringBootLibertyApplication: The entry point for the SpringBoot application.
• LibertyHelloController: A Spring REST endpoint which you can access at /springbootweb.

There is also a test class named it.springboot.web.HelloControllerTest that will test the Spring REST endpoint to ensure it is working.

Websockets

This provides you with the websocket-1.1 feature.

For the complete feature documentation, see the websocket-1.1 feature description in IBM Knowledge Center.

Persistence

This provides you with jpa-2.1. For the complete feature documentation, see the jpa-2.1 feature description in IBM Knowledge Center.

Watson SDK

The Watson SDK provides an API for accessing Watson Services. For the complete documentation, take a look at the Watson developer pages and the Watson SDK github project.

MicroProfile

The MicroProfile project is an open community with the aim of optimizing Enterprise Java for a microservices architecture. MicroProfile will be evolving with guidance from the community.

If you want to share your thoughts you can post straight to the MicroProfile Google group.

For the complete feature documentation, see the microProfile-1.0 feature feature description in IBM Knowledge Center.

Swagger

Swagger is a simple yet powerful representation of RESTful APIs.

This provides you with the apiDiscovery-1.0 feature, which allows you to discover REST APIs that are available on the Liberty server and then invoke the found REST endpoints using the Swagger user interface.

You can also easily expose the REST endpoints available from your web modules running on Liberty server by documenting the endpoints using the Swagger 2.0 Specification.

It is also possible to follow a design-first approach by creating the Swagger documentation first and then generating the server code from it.

For the complete feature documentation, see the apiDiscovery-1.0 feature description in IBM Knowledge Center.

Building and adding to the app accelerator

Building the Project

Once you have downloaded the project, to build it you just need to run the command gradle clean build in the top level project. To run the application locally from the root project run liberty-starter-application:localRun. The application should be available at http://localhost:9082/start.

Project Structure

The project is split up into several different pieces.

• liberty-starter-application contains the code to build the main application including the code for the UI
• liberty-starter-common contains common api code for the projects
• liberty-filter-application is a simple war that redirects people to the context /start
• liberty-starter-wlpcfg contains the Liberty usr directory where the logs and apps for the app accelerator will be put after a build
• liberty-starter-test contains a test microservice used during the testing phase

There are then a set of starter-microservice-techId projects that contain the code for the individual technology types.

Creating the project on GitHub

If you are running locally you will be required to register the application with GitHub and provide the client id and secret as well as an extra app accelerator secret (for signing the state sent to GitHub) as environment variables.

To do this go to GitHub's OAuth applications page. Register your application with the following settings:

• Application Name: Anything you want
• Homepage URL: http://localhost:9082/start
• Application description: Anything you want
• Authorization callback URL: http://localhost:9082/start/api/v1/github/callback

Once you have done this GitHub will give you a client ID and client secret set the following environment variables prior to starting the server:

• gitHubClientId
• gitHubClientSecret
• appAcceleratorSecret (this can be anything you want it to be)

Deployment Options

There are two deployment options for the app accelerator: local and Bluemix

Local Deployment

If you have chosen the local deployment option when you run mvn install the application will be compiled, tested and then the application will start at localhost:9080/mylibertyApp. To stop the application run mvn clean -P stopServer. This will stop the server and clean up the target directories.

Bluemix Deployment

To deploy an application to Bluemix you first need a Bluemix account. Once you have created a Bluemix account you can build and deploy your application by running mvn install -Dcf.org=[your email address] -Dcf.username=[your username] -Dcf.password=[your password]. Where cf.org is the Bluemix organization you want to deploy to and cf.username and cf.password are your credentials for Bluemix. Once the build has been run see your command line output to find the endpoint for your application or look for it in the Bluemix dashboard.

You can optionally supply the following Bluemix configurations in the command line or in the top level pom.xml:

• <cf.context>eu-gb.mybluemix.net</cf.context>
• <cf.target>https://api.eu-gb.bluemix.net</cf.target>
• <cf.space>dev</cf.space>
• <cf.context.root>${cf.host}.${cf.context}/${warContext}</cf.context.root>

Changing the deployment type

If you have chosen the deployment type on the app accelerator you can specify a different deployment type on the command line as follows:

• mvn install -P localServer for local deployment
• mvn install -P bluemix for Bluemix deployment

Adding new technologies to the app accelerator

To see an example of everything you can include in a technology see the starter-microservice-test project. This is the example project we use to test the main piece of the app against.

If you want to add changes to the app accelerator, create a fork of the project and then once you are happy with the change create a pull request to the "staging" branch. We will use this branch to run some testing before pushing the changes live.

Create a technology from the template service

1. Copy the contents of the starter-microservice-template directory into a new directory. The convention is that the last part of the name is related to the technology. So, if you were creating a technology based on SuperTech then the directory would be starter-microservice-supertech. (SuperTech will be the name used for the rest of these instructions).

2. Update the id's and context root in the build.gradle file. The context root would change to /supertech, the id in the installAllPoms task would be supertech and the id in the fvt task would be starter-microservice-supertech.

3. Change the group ID values in the POM files under starter-microservice-supertech/repository/0.0.1, compile-pom.xml, provided-pom.xml and runtime-pom.xml. net.wasdev.wlp.starters.template becomes net.wasdev.wlp.starters.supertech.

4. Refactor the packages and classes under src to SuperTech i.e. starter-microservice-supertech/src/main/java/com/ibm/liberty/starter/service/template becomes starter-microservice-supertech/src/main/java/com/ibm/liberty/starter/service/supertech

5. Change the GROUP_SUFFIX constant in the ProviderEndpoint class to supertech.

6. Change the value of context-root in src/main/webapp/WEB-INF/ibm-web-ext.xml to supertech.

7. Edit src/main/webapp/WEB-INF/classes/description.html to tell everyone about how SuperTech works and it's benefits.

8. (If you don't want to provide sample code for your technology type skip to step 10). Put the application sample code into src/main/webapp/sample.

9. Put the Liberty configuration for the sample application into src/main/webapp/sample.

10. Change the tests package to src/test/java/com/ibm/liberty/starter/service/supertech/api/v1/it and then the test classes to expect the correct responses for SuperTech.

Configuring a new technology

1. In liberty-starter-application/src/main/resources update the services.json file to add your new technology, including an id, name, description and the endpoint you want to use. This will add your technology as an option on the main page.

2. By convention the id should be supertech and the endpoint should be /supertech.

3. The name and description are used in the UI to give the user information about the technology type.

4. In the settings.gradle file add starter-microservice-supertech to the include list. This will add your project into the build lifecycle.

5. In the build.gradle file in liberty-starter-application in the last set of dependsOn commands add your technology to the war.dependsOn list. You need to add :nameOfYourProject:publishWar. This will make sure your project is built before the liberty-starter-application project.

6. In liberty-starter-wlpcfg/servers/StarterServer/server.xml add your application to the list. You need to provide the name of the war file being created in location, the context-root that matches the endpoint specified in the services.json file in step 1 and the id you specified in step 1.

If you run gradle clean build your new project should now be built and the war should be put into the apps directory of your server.