Using your own PC as a test machine for Valence apps

Ever wished you could save and test your front-end development work locally, on your own PC or laptop, then push it to your IBM i only when it’s ready for user testing or production? Turns out this is indeed something you can do! Using this process, the changes you make during development are completely local to your PC, thereby not affecting any deployed Valence app in the interim. This approach is also particularly handy when you’re developing apps with Sencha Architect, as the volume of data that must be pumped to the IFS can make each save a sluggish experience, particularly when working remotely (i.e., through VPN). It also means the non-cached app in development can load a bit faster. The process involves setting up a local Node server on your PC, then configuring it to serve your app locally, instead of being served by your IBM i Apache Server.   Here are the steps:

Windows Installation Instructions

  1. Install Node.js
    • Download here and follow the installation prompts (make sure you select the Windows installer)
    • Restart your computer.
    • Test that Node.js is installed by running the following command in the command prompt:
      node -v
    • If it’s installed successfully it should print out the current version.
  2. Install Forever, a tool for ensuring that a given script runs continuously (more info)
    • Open command prompt, make sure you’re in your home directory, then run the following command:npm install forever -g
  3. Install express for HTTP utilities (more info)
    • Open command prompt, make sure you’re in your home directory, then run the following command:npm install express
  4. Install http-proxy for the ability to proxy requests (more info)
    • Open command prompt, make sure you’re in your home directory, then run the following command:npm install http-proxy

Mac Installation Instructions

  1. Install Node.js
    • Download here and follow the installation prompts (make sure you select the Mac installer)
    • Test that Node.js is installed by running the following command in Terminal:
      node -v
    • If it’s installed successfully it should print out the current version.
  2. Install Forever, a tool for ensuring that a given script runs continuously (more info)
    • Open Terminal, make sure you’re in your home directory, then run the following command:sudo npm install forever -g
  3. Install Expressfor HTTP utilities (more info)
    • Open Terminal, make sure you’re in your home directory, then run the following command:sudo npm install express
  4. Install http-proxy for the ability to proxy requests (more info)
    • Open Terminal, make sure you’re in your home directory, then run the following command:sudo npm install http-proxy

 

Post-Install Setup

With Node successfully installed, create a directory on your machine that will contain your applications when doing local development.  Inside the root of this directory, add a new javascript file called ‘server’ (so when looking at the directory you should see a ‘server.js’ file).  Copy the below Node.js server source and place it in your new ‘server.js’ file.  Replace the host and ports as required to match your IBM i configuration:

//
// node server configuration
 
// set up basic settings...
var host = 'http://yourIBMiIPAddress',
   hostport = 7041,
   localport = 7041; // note: ports should match the port your Valence instance uses
 
// define server proxy...
var express = require('express'),
   app = express(),
   httpProxy = require('http-proxy'),
   routingProxy = new httpProxy.createProxyServer(),
   valenceProxy = function(req, res) {
       routingProxy.web(req, res, {
           target : host + ':' + hostport
       });
   };
 
// route valence calls through proxy...
app.all('/valence/*', valenceProxy);
app.all('/portal/*', valenceProxy);
app.all('/resources/*', valenceProxy);
app.all('/build/*', valenceProxy);
app.all('/desktop/*', valenceProxy);
app.all('/extjs5/*', valenceProxy);
 
// serve static folders from this local machine...
app.use('/', express.static(__dirname));
 
// begin listening on local port...
app.listen(localport);

Figure 1: server.js source

Now you should be able test your new Node.js server. On your PC, open your Terminal or command prompt, make sure you’re in your home directory, then run the following command: node server.js You should see your terminal/command prompt lock up at this point because it’s now running your server. Lets now use “forever” to run the server for us so we don’t have to have the terminal/command prompt always running.  Do this by canceling the node server.js (ctrl-C) and then runing the following command, based on your OS:

  • On Mac:  sudo forever start –uid “my-xxx-server” -a server.js
  • On Windows:  forever start –uid “my-xxx-server” -a server.js

With your server running, you should now be able to go to your browser and enter the following url (this is assuming you’re running your Valence instance on port 7041 — adjust accordingly based on the port you placed in your server.js): http://localhost:7041/portal/   This should get you to the familiar Valence Portal login page.  The last step is to go into the Portal Admin app and create a new Valence app record to run your local application.  Your app should use the localhost path instead of your regular IBM i path.  Once this is done, that app (and any other app pointing to localhost address) will be served from your PC rather than from your server.  When you’re done doing development on the app, you can then copy the front-end folders to the appropriate spot on your IBM i and adjust the Valence app path accordingly.   Finally, whenever you want to end your local server, simply issue the following command:

  • On Mac: sudo forever stop “my-xxx-server”
  • On Windows: forever stop “my-xxx-server”