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
XPages on IBM Bluemix: The Do‘s and 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Create or login to your Bluemix account
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
XPages NoSQL database service
• Add a service
• Scroll down to „Bluemix Labs Catalog“
• Find „XPages NoSQL Database“
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Bluemix prefs in Domino Designer
• File, Preferences, Domino Designer, IBM Bluemix
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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>
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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!
• Caveats and restrictions
• Tipps & tricks
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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)
XPages on IBM Bluemix: The Do‘s and Don‘ts
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>
XPages on IBM Bluemix: The Do‘s and Don‘ts
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!)
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
The manifest.yml editor
• Gives you the basic configuration for a single XSP runtimeapplication
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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!
XPages on IBM Bluemix: The Do‘s and Don‘ts
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!
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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!
+
XPages on IBM Bluemix: The Do‘s and Don‘ts
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)
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Using plugins: deployment
• Deploy the application (cf push)
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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'
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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'
XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Don‘t want to type?
• Use the editor to set those up ;-)
XPages on IBM Bluemix: The Do‘s and Don‘ts
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
XPages on IBM Bluemix: The Do‘s and Don‘ts
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!
XPages on IBM Bluemix: The Do‘s and Don‘ts
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)
XPages on IBM Bluemix: The Do‘s and Don‘ts
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