xpages on ibm bluemix: the do's and dont's - ics.ug 2016

XPages on IBM Bluemix: The Do‘s and Don‘ts

www.ics.ug #icsug

XPages on IBM Bluemix:The Dos and Don'ts

Oliver Busse, We4IT GmbH


www.ics.ug #icsug

„Many Dos, not so much Don‘ts“


www.ics.ug #icsug

About me

• Working for We4IT

–Aveedo® Application Framework

• „Bleeding Yellow“ since R4.5

• IBM Champion for ICS 2015 + 2016

• OpenNTF Member Director

@zeromancer1972@we4it


www.ics.ug #icsug

Agenda

• Prerequisites

• Best practices: design and data separation

• Using the DDE plugin vs. the CF command line

• Understanding the "mysterious" MANIFEST.YML file

• Experiment: holding data in the XSP runtime

• Security considerations

• Plugins and extensions? No problem!

• Tipps & tricks


www.ics.ug #icsug

• Prerequisites







• Tipps & tricks


www.ics.ug #icsug

Prerequisites

• Create an IBM Bluemix account

• Create an XPages NoSQL database service(i.e. a Domino Server)

• Get the latest* Extension Library from OpenNTF

• Install Extlib on your local Domino Designer to get the Bluemix plugin

• Setup Bluemix preferences in DDE

*) 9.0.1v16, January 2016


www.ics.ug #icsug

Create or login to your Bluemix account


www.ics.ug #icsug

XPages NoSQL database service

• Add a service

• Scroll down to „Bluemix Labs Catalog“

• Find „XPages NoSQL Database“


www.ics.ug #icsug

Additional steps

• Open the XPages NoSQL Database service properties page

• Grab the user ID to access the Bluemix Domino instance

– slaney/Bluemix (USA)

– langan/Bluemix (UK)

– coming soon: CAN and AUS

• Optional: setup additional web users


www.ics.ug #icsug


www.ics.ug #icsug

Get the Extlib from OpenNTF

• Download and install it via the updatesite mechanism

– https://extlib.openntf.org/

– https://www.dalsgaard-data.eu/blog/deploy-an-eclipse-update-site-to-ibm-domino-and-ibm-domino-designer/

• Check Extlib version in DDE and server


www.ics.ug #icsug

Bluemix prefs in Domino Designer

• File, Preferences, Domino Designer, IBM Bluemix


www.ics.ug #icsug

New IBM Bluemix toolbar control


www.ics.ug #icsug

• Prerequisites







• Tipps & tricks


www.ics.ug #icsug

Design and data separation

• Create the data part on the Bluemix Domino instance

– create a blank databaseor

– copy and existing database with data

• Setup ACL etc.

– Keep in mind the additional webusers you may have created before


www.ics.ug #icsug

Setup local dev environment

• Separate data and design also on your local environment

• Find and modify ALL static references to „database“ on every XPage, Custom Control and Code

– Document data sources

– View data sources


www.ics.ug #icsug

Compute „database“ references

• Utilize the bluemixContext bean

– comes with the OpenNTF Extension Library since v13

– isRunningOnBluemix()

• findDatabaseName() always returns „tododata.nsf“

– static default filename of the data part on the XPages NoSQLservice

https://www.eu-gb.bluemix.net/docs/services/XPagesNoSQLDatabase/index.html


www.ics.ug #icsug

More flexible: use a custom bean

• Compute server and filepath dynamically

– for the local and the Bluemix environment

• Allows a different filename on the XPages NoSQL service (otherthan „tododata.nsf“)

• Generic code for „database“ computation for document, viewand repeat data sources

• There is a snippet for you…

– https://openntf.org/XSnippets.nsf/snippet.xsp?id=daobean-for-xsp-on-bluemix


www.ics.ug #icsug

Examples: the DAO-Bean<xp:this.data>

<xp:dominoDocumentvar="document1"databaseName="#{javascript:dao.dbpath}"formName="greeting">

</xp:dominoDocument></xp:this.data>

<xp:repeatid="greetings"rows="9999"var="greeting"indexVar="index"><xp:this.value>

<![CDATA[#{javascript:dao.getViewEntries("greetings")}]]></xp:this.value>

…</xp:repeat>


www.ics.ug #icsug

• Prerequisites







• Caveats and restrictions

• Tipps & tricks


www.ics.ug #icsug

What the DDE Plugin does

• When running for the first time

– It will ask for a local folder

– It will create a copy (or replica) of the XSP part

– It will create a manifest.yml file

– It contacts the Bluemix XSP runtime and uploads the 2 files

• Afterwards

– It updates the local copy / replica

– It modifies the manifest.yml file

– It contacts the Bluemix XSP runtime and uploads the 2 files


www.ics.ug #icsug

What the DDE Plugin also does…

• It won‘t display error messages or log outputs duringdeployment

– hard to troubleshoot

• Sometimes it may not work when running a second, third, … time

– DDE restart will solve this problem


www.ics.ug #icsug

The CF command line

• CF = Cloud Foundry

• Download and install the command line

– https://github.com/cloudfoundry/cli/releases

– http://docs.cloudfoundry.org/devguide/cf-cli/

• You can create a batch file to accellerate deployment

• Verbose output of any action during deployment process

• Access to the XSP runtime file system (e.g. for reading systemlogs)


www.ics.ug #icsug

A simple triplet of commands

• cf api

– use api.bluemix.net or api.eu-gb.bluemix.net

– cf api https://api.bluemix.net

• cf login

– provide username and password

– cf login –u username –p password

• cf push

– will upload your local droplet instantly using the manifest.yml file

– cf push

– cf push <applicationName>


www.ics.ug #icsug

Benefits using the CF command line

• Full control of what‘s being done

• Understand how cloud deployment works

• Create new XSP runtimes and instances on the fly (wait for it!)

• Deploy plugins and other resources (wait for it!)


www.ics.ug #icsug

Disadvantage using the CF command line

• You have to create the local NSF copy / replica manually

– beware of local encryption!

• You have to type in a console… ;-)

– I recommend using CMDER command line replacement for Windows


www.ics.ug #icsug

• Prerequisites







• Tipps & tricks


www.ics.ug #icsug

The manifest.yml file

• The manifest.yml file is a simple text file (not even XML)

• It contains fundamental definitions for the runtime and theservice(s) used

• When using hybrid it contains credentials!

– do not commit the file to a repository!

• Domino Designer Plugin comes with a versatile editor for themanifest.yml file


www.ics.ug #icsug

The manifest.yml editor

• Gives you the basic configuration for a single XSP runtimeapplication


www.ics.ug #icsug

Example: manifest.yml

---applications:- name: greetshost: greetsinstances: 1memory: 512Mtimeout: 180buildpack: xpages_buildpackcommand: /app/launch_xpages_webcontainerenv:APP_HOME_URL: /greets_xsp.nsfAPP_PRELOAD_DB: greets_xsp.nsf

services:- IBM XPages NoSQL Database-UK

= custom setting

= default setting


www.ics.ug #icsug

Did you know?

• The manifest.yml file can deploy more that one application tothe XSP runtime

– APP_PRELOAD_DB: xsp1.nsf, xsp2.nsf, xsp3.nsf

• By setting values manually you can modify and / or create newXSP runtimes, e.g.

– scaling instances and memory

– setting up new XSP runtimes and hosts


www.ics.ug #icsug

• Prerequisites







• Tipps & tricks


www.ics.ug #icsug

Experiment: data in the XSP runtime

• This is not supported!

• This may work flawlessly, but don‘t rely on it

• Maybe useful for configurations, not for production data

• XSP Runtime is a slim Domino environment, so everything ispossible regarding data

• Faulty behavior of pager


www.ics.ug #icsug

Pros and cons

+ Direct and fast access to commonly used data sets (e.g. application and user profiles)

+ No data separation necessary

+ No changes needed in an existing application

- Data will be overwritten

- every time you re-deploy

- every time you re-scale the application

- every time the runtime restarts


www.ics.ug #icsug

• Prerequisites







• Tipps & tricks


www.ics.ug #icsug

Security considerations

• You have to manage at least two ACLs

– XSP Runtime (design part)

– XPages NoSQL service (data part)

• Design part

– manage Anonymous access only to force a login page

• Data part

– Manage ACL corresponding to the user ID and web users you may setup in the XPages NoSQL service

– Other known ACL rules such as user roles apply here

– You can lock yourself out from that ACL – be careful, Full Access Admin is NOT available to unlock!


www.ics.ug #icsug

Locked out from data NSF?

• Deleting and re-creating the service has no effect, NSFs will re-appear!

• You have to contact IBM support for unlocking or deletingthe NSF!

• Locked out from design NSF?• remove the runtime and re-deploy – phew!


www.ics.ug #icsug

• Prerequisites







• Tipps & tricks


www.ics.ug #icsug

Imagine…

• to use your favorite extensions even on IBM Bluemix

• to enrich your application with genius software like theOpenNTF Domino API or the XLogger

• You can do this!

+


www.ics.ug #icsug

Using plugins: preparation

• Create a folder „shared-plugins“ in the local deploymentfolder

• Download the plugin or extension, unzip it

• Locate the updatesite version of the plugin

• Copy the content of the plugins folder into the “shared-plugins” folder (.jar-files)


www.ics.ug #icsug

Using plugins: deployment

• Deploy the application (cf push)


www.ics.ug #icsug

• Prerequisites







• Tipps & tricks


www.ics.ug #icsug

Using the XPages Toolbox

• Versatile profiling tool for performance monitoring

• Available on OpenNTF for on-premises use

– https://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20Toolbox/

• Setup automatically by modifying the manifest.yml file

• Add this to the env section:

– APP_INCLUDE_XPAGES_TOOLBOX: '1'


www.ics.ug #icsug

XPages Toolbox (Profiler)


www.ics.ug #icsug

Grant restricted access of the JVM

• Like in on-premises environments you may want to enable fullaccess for the JVM when using e.g. Java reflections.

• Instead of setting the java.pol file you simply add this to themanifest.yml

– APP_JAVA_POLICY_ALL_PERMISSION: '1‘

• Keep in mind that this may be a security issue


www.ics.ug #icsug

Verbose mode while deploying

• When using the CF command line the following added to themanifest.yml file will deliver detailed messages during thedeployment

– APP_VERBOSE_STAGING: '1'


www.ics.ug #icsug

Don‘t want to type?

• Use the editor to set those up ;-)


www.ics.ug #icsug

Missing view icons

• When using view icons in XPages view panels the icons aremissing

• They won‘t be displayed even if you use @ViewIconUrl SSJS function

• However, you can add them manually


www.ics.ug #icsug

View icons: lost but found

• Open the deployment folder of the XSP part

• Create the folder notesdata/domino

• Copy the folder <NotesData>/domino/icons to it

• The folder will be published to the XSP runtime

• The view icons will re-appear!


www.ics.ug #icsug

Q & A


www.ics.ug #icsug

Thank you!

Special thanks to:

Tony McGuckin, Martin Donnelly, Brian Gleeson(IBM Ireland Labs, XPages and Bluemix Dev Team)

Pete Janzen(IBM, Sr. Product Manager, IBM Enterprise Social Solutions)


www.ics.ug #icsug

Resources

• https://openntf.org/XSnippets.nsf/snippet.xsp?id=daobean-for-xsp-on-Bluemix

• http://notesx.net:8090/obusse/Greets

• http://greets.eu-gb.mybluemix.net/

• http://cmder.net/

• https://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20Toolbox/

• http://oliverbusse.notesx.net/hp.nsf/blogpost.xsp?documentId=10C2

xpages on ibm bluemix: the do's and dont's - ics.ug 2016

Software