This is the first of a series of postings on using EWD 3, specifically using the ewd-xpress module which allows you to run browser-based applications.
The first thing you'll need is a working platform on which to install and run it. Here I'll explain how to set up a Ubuntu / Cache system. I'll assume you're starting from scratch with a new, virgin Ubuntu system. If not, adjust the steps according to your configuration.
If you're using another operating system or Linux version, you'll need to adjust some of the steps appropriately.
I'll list the steps here, but I've also created a downloadable file containing the steps as a script file. However, you won't be able to run it as a script because, by necessity, it assumes you must do two things manually:
- downloading and saving a copy of Cache that you've obtained from InterSystems
- copying your Cache key that you've purchased from InterSystems.
Note: you can, just about, run EWD 3 / ewd-xpress with a single user demo license for Cache, but you'll be limited to a single ewd-qoper8 worker process, and while ewd-xpress is running, you'lll not be able to access Cache from any other client (eg Terminal, Studio etc). So it's somewhat impractical to use EWD 3 / ewd-xpress unless you have a proper Cache license.
OK let's get started.
On a new Ubuntu system, it's always a good idea to update the apt-get repository, and then install a few pieces of software that you'll need:
sudo apt-get update
sudo apt-get install -y build-essential
sudo apt-get install -y wget gzip openssh-server curl
If you haven't already installed Cache, you'll first need to adjust the shared memory settings. The following work well
sudo sysctl -w kernel.shmall=536870912
sudo sysctl -w kernel.shmmax=536870912
sudo /bin/su -c "echo 'kernel.shmall=536870912' >> /etc/sysctl.conf"
sudo /bin/su -c "echo 'kernel.shmmax=536870912' >> /etc/sysctl.conf"
You'll now need to obtain a copy of a Cache installation kit from InterSystems and save it in your home directory. For example: cache-2015.2.tar.gz
If you're installing Cache on a Ubuntu Linux system, then I've found that the easiest kit to use is the one for Suse Linux.
Assuming you've saved your copy of a Cache installation kit into your home directory, you can install it using the following code.
mkdir /tmp/cachekit
cd ~
gunzip -c cache*.tar.gz | ( cd /tmp/cachekit ; tar xf - )
cd /tmp/cachekit
sudo ./cinstall
During installation, you'll be asked a series of questions. Here's how I'd respond to them, but feel free to adjust your responses if you're familiar with Cache and need a different setup:
# Accept 1 - Suse Linux
# Accept instance name of CACHE
# Installation directory assumed to be /opt/cache
# Accept 1 - Development server
# Say yes to Unicode
# Accept Minimal Security settings (1)
# If using EC2, group to use is ubuntu, otherwise your username
# Accept No to license - install your own later into /opt/cache/mgr
# Then accept settings
Once the installation completes, you'll need to install your Cache license which you should have obtained from InterSystems. It will be named cache.key and you should copy it into the /opt/cache/mgr directory.. If you installed Cache to another directory, copy your key to the appropriate /mgr directory.
You should now restart Cache so that it takes your new key settings:
ccontrol stop cache restart quietly
OK, so now it's time to install Node.js. I'm going to install the latest LTS version: 4.4 at the time of writing, but any earlier version will also do. The key criterion is that there is a corresponding or compatible version of the Cache/Node.js interface file (cache.node) available for the version of Node.js you install. If in doubt, ask your InterSystems rep.
I find that the Node Version Manager (NVM) is the simplest and easiest way to install Node.js on Linux systems, particularly because it makes it easy to upgrade to new versions of Node.js as they become available. Here's how I do it:
Change the 4.4 in the code above to whatever version you want (eg 0.12) if necessary
It's a good idea to ensure that NVM automatically sets you up with the correct version of Node.js whenever you log in. The following code modifies your .profile file to make this happen:
echo 'nvm use default' >> ~/.profile
On other Linux systems, eg Centos or RHEL, you may need to modify your .bash_profile file instead.
Now, the installation steps we used will have set root permissions for Cache, so we'll need to use the sudo command whenever we want to run our EWD 3 Node.js scripts to ensure that they have the permission to access Cache. Unfortunately, Node.js isn't automatically available via 'sudo node'. The following steps will rectify that:
sudo ln -s /usr/local/bin/node /usr/bin/node
sudo ln -s /usr/local/lib/node /usr/lib/node
sudo ln -s /usr/local/bin/npm /usr/bin/npm
sudo ln -s /usr/local/bin/node-waf /usr/bin/node-waf
n=$(which node);n=${n%/bin/node}; chmod -R 755 $n/bin/*; sudo cp -r $n/{bin,lib,share} /usr/local
So now we're ready to install ewd-xpress and its associated monitor/management application ewd-xpress-monitor
First, we'll create a directory for all our EWD 3 work - I'm going to use ~/ewd3
Now you just need to let NPM do the work:
npm install ewd-xpress ewd-xpress-monitor
You'll probably see a whole bunch of warnings about peer dependencies. Just ignore them. exd-xpress will install a whole bunch of other EWD 3 modules along with others such as
socket.io that can be used by your ewd-xpress applications. Express will also be automatically installed as a peer dependency.
In order to use Node.js with Cache, you'll need to have obtained a compatible version of the cache.node file. I'll be using the Node.js 4.2-compatible version (for 64-bit Linux) - cache421.node. So this needs to be moved into place and rename it. EWD 3 modules expect to find it in your bottom-level node_modules directory, ie ~/ewd3/node_modules in our case. This node_modules directory will have been created when you installed ewd-xpress in the command above. So, for example:
cd ~/ewd3/node_modules
mv cache421.node cache.node
Finally, you'll need to copy a few files from directories within the various EWD modules into the directories that EWD 3 and ewd-xpress will expect them to reside. First:
mv ~/ewd3/node_modules/ewd-xpress/example/ewd-xpress.js ~/ewd3/ewd-xpress.js
This command above moves the pre-built example script for running ewd-xpress. EWD 3 will expect you to invoke this from your ~/ewd3 directory. If you've been using all the steps above to install on a previously new, virgin Ubuntu system, the example ewd-xpress.js script will run "out of the box". However, if you are using an existing Cache system, you'll need to modify the access parameters that allow the cache.node interface to connect to Cache. If so, find the following lines in exd-xpress.js
var config = {
managementPassword: 'keepThisSecret!',
serverName: 'New EWD Server',
port: 8080,
poolSize: 1,
database: {
type: 'cache'
}
};
var ewdXpress = require('ewd-xpress').master;
ewdXpress(config);
There are 4 key Cache access parameters:
- path: the mgr path for your Cache system
- username: the username you'll use for accessing Cache
- password: the corresponding password
- namespace: the Cache namespace to which you want to connect
The defaults are:
- path: /opt/cache/mgr
- username: _SYSTEM
- password: SYS
- namespace: USER
If your Cache system requires different values, you specify them using the database.params object. You only need to specify those that are different from the defaults above. So, for example:
var config = {
managementPassword: 'keepThisSecret!',
serverName: 'New EWD Server',
port: 8080,
poolSize: 1,
database: {
type: 'cache',
params: {
path: '/usr/lib/cache2015/mgr',
namespace: 'VISTA'
}
}
};
var ewdXpress = require('ewd-xpress').master;
ewdXpress(config);
If you've previously used EWD.js, you'll recognise the other parameters such as port, managementPassword and poolSize:
- managementPassword: the password you'll need to use with the ewd-xpress-monitor application in order to gain access
- port: the port on which Express is listening for input
- poolSize: the maximum number of worker processes that ewd-xpress will start. Note that each worker will consume a Cache license
OK, just one last step - move the monitor application code into place. ewd-xpress assumes that the physical path that will represent Express's root URL is ~/ewd3/www. Each ewd-xpress application is saved under this www directory. So:
cd ~/ewd3
mkdir www
cd www
mkdir ewd-xpress-monitor
cp ~/ewd3/node_modules/ewd-xpress-monitor/www/bundle.js ~/ewd3/www/ewd-xpress-monitor
cp ~/ewd3/node_modules/ewd-xpress-monitor/www/*.html ~/ewd3/www/ewd-xpress-monitor
cp ~/ewd3/node_modules/ewd-xpress-monitor/www/*.css ~/ewd3/www/ewd-xpress-monitor
That's it, you should now be ready to try it out.
First, start ewd-xpress:
cd ~/ewd3
sudo node ewd-xpress
You should see the following or similar:
ubuntu@ip-172-30-1-247:~/ewd3$ sudo node ewd-xpress
webServerRootPath = /home/ubuntu/ewd3/www/
Worker Bootstrap Module file written to node_modules/ewd-qoper8-worker.js
========================================================
ewd-qoper8 is up and running. Max worker pool size: 1
========================================================
Note: unlike EWD.js, EWD 3 will not start up worker processes until they are actually needed. It's actually the ewd-qoper8 module that is responsible for the worker pool mechanics. See
https://github.com/robtweed/ewd-qoper8 for full details.
Now go to your browser and invoke the following URL (adjust the IP address appropriately to the one allocated to your Ubuntu system:
It should start and ask for your management password. Enter keepThisSecret!
You should now see the overview panel for your EWD 3 / ewd-xpress environment. Currently that's all there is in the monitor application, but you'll find that it provides a very important function - the ability to stop worker processes. You'll need to do this when you begin to develop your own ewd-xpress applications. Try clicking the worker process stop button and see what happens: immediately you'll see a new one starts up. I'll explain when and where you need to use this button in future postings.
Meanwhile, in the Node.js / ewd-xpress process, you'll see lots of activity now going on.
For now, that's it, you now have EWD 3 / ewd-xpress fully working with Cache. What you're seeing in the browser is a React.js application. if you're interested in React.js development, you can see its source code by looking in the directory:
~/ewd3/node_modules/ewd-xpress-monitor/www/
What you're actually running in the ~/ewd3/www/ewd-xpress-monitor directory is a bundled "compiled" version of all these React.js components (and many more client-side modules) - hence you'll just see the following files in the working /www/ewd-xpress-monitor directory:
- index.html
- bundle.js
- Select.css
I'll explain all about developing React.js applications with EWD 3 / ewd-xpress in a future posting.
One last thing - provided you have a suitable Cache license, you can take a peek at where and how EWD 3 creates and stores its Session information. Use your favourite tool for examining Globals and look in the USER namespace for the Global ^CacheTempEWDSession
Each time you invoke the monitor URL (see above), you'll see it create a new Session in this global. Note: you should never modify the contents of this Global manually - use the EWD 3 session APIs and let EWD 3 manage. maintain and garbage-collect it.
Enjoy EWD 3!
Rob
