By following this guide, you'll set up a development environment, deploy an app locally and on Bluemix, and integrate a Bluemix database service in your app.
Git, Bluemix CLI, Maven, and a Bluemix account.
Now you're ready to start working with the app. Clone the repo and change the directory to where the sample app is located.
git clone https://github.com/IBM/liberty-outage-reporter
cd liberty-outage-reporter
Use Maven to install dependencies and build the .war file.
mvn clean install
Run the app locally on Liberty.
mvn install liberty:run-server
View your app at: https://localhost:9080/LibertyOutageReporter
To deploy to Bluemix using command line, it can be helpful to set up a manifest.yml file. The manifest.yml includes basic information about your app, such as the name, the location of your app, how much memory to allocate for each instance, and how many instances to create on startup. This is also where you'll choose your URL. Learn more...
The manifest.yml is provided in the sample.
applications:
- path: target/LibertyOutageReporter.war
memory: 512M
instances: 1
name: your-appname-here
host: your-appname-here
Change both the name and host to a single unique name of your choice. Note that the host value will be used in your public url, for example, https://your-appname-here.mybluemix.net. If you already created an app from the Bluemix UI but haven't pushed your code to it, you can use the same name value. Make sure the path points to the built application, for this example the location is target/LibertyOutageReporter.war
.
Choose your API endpoint
bluemix api <API-endpoint>
Replace the API-endpoint in the command with an API endpoint from the following list.
- https://api.ng.bluemix.net # US South
- https://api.eu-de.bluemix.net # Germany
- https://api.eu-gb.bluemix.net # United Kingdom
- https://api.au-syd.bluemix.net # Sydney
Login to your Bluemix account
bluemix login
Push your application to Bluemix.
bluemix app push
This can take around two minutes. If there is an error in the deployment process you can use the command cf logs <Your-App-Name> --recent
to troubleshoot.
Next, we'll add a NoSQL database to this application and set up the application so that it can run locally and on Bluemix.
- Log in to Bluemix in your Browser. Select your application and click on
Connect new
underConnections
. - Select
Cloudant NoSQL DB
and Create the service. - Select
Restage
when prompted. Bluemix will restart your application and provide the database credentials to your application using theVCAP_SERVICES
environment variable. This environment variable is only available to the application when it is running on Bluemix.
We're now going to update your local code to point to this database. We'll store the credentials for the services in a properties file. This file will get used ONLY when the application is running locally. When running in Bluemix, the credentials will be read from the VCAP_SERVICES
environment variable.
- In Eclipse, open the file
src/main/resources/cloudant.properties
:
cloudant_url=
-
In your browser open the Bluemix UI, select your
App
->Connections
->Cloudant
->View Credentials
(Note you may have create a set of credentials) -
Copy and paste just the
url
from the credentials to theurl
field of thecloudant.properties
file. -
Your Liberty server in Eclipse should automatically pick up the changes and restart the application.
View your app at: https://localhost:9080/LibertyOutageReporter/. Any names you enter into the app will now get added to the database.
Make any changes you want and re-deploy to Bluemix!
IBM® Eclipse Tools for Bluemix provides plug-ins that can be installed into an existing Eclipse environment to assist in integrating the developer's integrated development environment (IDE) with Bluemix.
-
Download and install IBM Eclipse Tools for Bluemix.
-
Import this sample into Eclipse using
File
->Import
->Maven
->Existing Maven Projects
option. -
Create a Liberty server definition: - In the
Servers
view right-click ->New
->Server
- SelectIBM
->WebSphere Application Server Liberty
- ChooseInstall from an archive or a repository
- Enter a destination path (/Users/username/liberty
) - ChooseWAS Liberty with Java EE 7 Web Profile
- Continue the wizard with default options to Finish -
Run your application locally on Liberty: - Right click on the
LibertyOutageReporter
sample and selectRun As
->Run on Server
option - Find and select the localhost Liberty server and pressFinish
- In a few seconds, your application should be running at https://localhost:9080/LibertyOutageReporter/ -
Create a Bluemix server definition: - In the
Servers
view, right-click ->New
->Server
- SelectIBM
->IBM Bluemix
and follow the steps in the wizard.
- Enter your credentials and clickNext
- Select yourorg
andspace
and clickFinish
-
Run your application on Bluemix: - Right click on the
LibertyOutageReporter
sample and selectRun As
->Run on Server
option - Find and select theIBM Bluemix
and pressFinish
- A wizard will guide you with the deployment options. Be sure to choose a uniqueName
for your application - In a few minutes, your application should be running at the URL you chose.
Now you have your code running locally and on the cloud!
The IBM Eclipse Tools for Bluemix
provides many powerful features such as incremental updates, remote debugging, pushing packaged servers, etc. Learn more
One deployment option is to deploy this application to kubernetes. For this option, we will provision a lite kubernetes cluster via the IBM Bluemix Container Service and deploy the service using the manifests/deployment.yml file. We will be using the IBM Container Registry to store the Docker image for our application.
- Install the IBM Bluemix Container Service plug-in.
bx plugin install container-service -r Bluemix
bx plugin list # To verify the plugin has been installed
bx cs init # Initialize the container service plugin
- Install the IBM Container Registry plug-in and login
bx plugin install container-registry -r Bluemix
bx cr login
- Create a namespace in the Container Registry service. Note this namespace needs to be unique across all users of Bluemix.
bx cr namespace-add [your namespace]
bx cr namespace-list
- Log into the Bluemix console and create a lite Kubernetes cluster named
mycluster
. This will take several minutes to provision.
- Install kubectl. Kubectl is the standard way to interact with Kubernetes clusters. You will configure
kubectl
to point to your Kubernetes cluster hosted on the IBM Bluemix Container Service. - When the Bluemix Console shows that your cluster is ready, list the clusters from the command line. You should see the cluster you created:
mycluster
. If you don't, make sure you have waited enough time for the cluster to be provisioned.
bx cs clusters
- Configure your
kubectl
to point to your Kubernetes cluster. First print the configuration for your cluster.
bx cs cluster-config mycluster
This should give you an export KUBE_CONFIG
line. Copy and paste this to configure your kubectl
to point to your Kubernetes cluster.
For example:
export KUBECONFIG=/Users/johnzaccone/.bluemix/plugins/container-service/clusters/mycluster/kube-config-par01-mycluster.yml
- Verify that your
kubectl
is configured. The following should show:mycluster
.
kubectl config get-clusters
You can now send commands to your Kubernetes cluster!
We will use the Bluemix CLI to create a binding between our Cloudant instance and our Kubernetes cluster.
- List the Cloudant service that you created eariler in this lab. If you haven't created one, refer back to the Add a Database section.
bx service list | grep cloudant
- Use the name of your Cloudant service in the command below to bind the service.
bx cs cluster-service-bind mycluster default [Cloudant service Name]
The command above loads a Kubernetes secret into your cluster that contains information to connect to your Cloudant instance. By managing your Cloudant credentials via secrets, you avoid saving them in plain text inside your source code repository.
- List the secrets of the Kubernetes cluster. There might be a few, but you should see the one that was just created for your Cloudant database. We are going to reference the name of this secret in our deployment in the next step.
kubectl get secrets
You need to configure your application to read the Kubernetes secret you just created. This will require two changes.
- Open the
src/main/resources/cloudant.properties
file. And uncomment the line that specifies the Kubernetes secret file. Also, comment out the line that explicitly sets the Cloudant URL. Your resulting properties file should look something like this:
# These properties are meant for local development only and will not be read when application is running in Bluemix.
# When running in Bluemix, the credentials of bound services are available in the VCAP_SERVICES environment variable.
# cloudant_url=
# You can bind Bluemix services using the `bx cs cluster-service-bind` command.
# Using this command to bind your cloudant database will load connection information into your kubernetes cluster as a kubernetes secret.
# Uncomment the following line to tell this app to load the cloudant username/password from the kubernetes secret.
kubernetes_secrets_file=/etc/cloudant-secrets/binding
The location for the secret is: /etc/cloudant-secrets/binding
. This is configured for you already in the manifests/deployment.yml
file. There is no need to change this path at this time.
- Open the
manifests/deployment.yml
file. Replacemy-secret
in the container spec with the name of your secret. You can get a list of secrets loaded into your cluster withkubectl get secrets
. Note that theetc/cloudant-secrets/binding
path has already been configured for you. Close and save the file.
- Build your application
mvn clean install
- Build and push the Docker image you the IBM Container Registry. Use the namespace you created earlier in the following command. You can list the namespace you created using
bx cr namespace-list
.
export CR_NAMESPACE=[your namespace]
docker build -t registry.ng.bluemix.net/$CR_NAMESPACE/liberty-outage-reporter .
docker push registry.ng.bluemix.net/$CR_NAMESPACE/liberty-outage-reporter
- Edit the
manifests/deployment.yml
to reference the name of the image that you just pushed. Search for the line
image: registry.ng.bluemix.net/mynamespace/liberty-outage-reporter
And replace mynamespace
with your namespace. For example, if you used namespace dev
the line would be:
image: registry.ng.bluemix.net/dev/liberty-outage-reporter
- Use `kubectl to deploy the application:
kubectl apply -f manifests
It should take a few minutes for the application to deploy. You can check the status by using kubectl get deploy
.
- Check that your application has been started by printing the logs.
kubectl get pods
NAME READY STATUS RESTARTS AGE
liberty-outage-reporter-495303238-65dfm 1/1 Running 0 2m
kubectl logs -f liberty-outage-reporter-495303238-65dfm
The deployment uses NodePort to expose the application on all nodes in the cluster. To access the application, first get the IP of the worker node in the cluster.
kubectl get nodes
NAME STATUS AGE VERSION
184.172.247.191 Ready 8d v1.5.6-4+abe34653415733
Then lists the services to get the port for your application.
kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
liberty-outage-reporter-service 10.10.10.177 <nodes> 9080:30052/TCP 20min
In this example, the application is running at: https://184.172.247.191:30052/LibertyOutageReporter
.