More IBM Docs Fun And Games

…a few more notes from my latest IBM Docs install.  Previous installs including in test at this customer proceeded with no problems but this one presented several challenges so I’m sharing them here in case anyone else has the same.  Firstly since there’s a Windows machine involved let’s rule out the biggest possible issues

1. Make sure Windows is activated. Microsoft does restrict behaviour and performance in non activated Windows. No I don’t have proof I just have solid evidence of that behaviour.  Activating Windows often makes the pain go away

2. Make sure you disable the Windows local firewall.  Even if you can only do so during the install.  The server is going to have to talk to - and be talked to - the deployment manager at least and with Windows firewall enabled your install will fail

3. Make sure every server can ping every other server, even itself. And using an IPV4 not IPV6 routable address

4. Disable UAC.  PLEASE.  In Windows 2012 that’s a registry hack where you set EnableLUA to 0 under “HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\system”

So now we’re ready to install.  There are two options - Installation Manager and using the manual scripts.  Obviously Installation Manager is easier, if you’re installing all components at the same time and if it works.  Here are the standard components I’d usually install for full IBM Docs in a Connections environment with no CCM.

My problem was that in this instance the installer failed during the Docs Proxy server install.  I could see in the logs (found under the IBM Docs Conversion install directory - in my case D:\IBM\ConnectionsDocs\Conversion\logs) that Conversion, Docs and Viewer all installed and deployed with no problems.  However since I chose six components, when it failed on one it rolled back the entire thing.

The error was “Target with name docsserver.domain.com was not found“.  Why would it say that when the script is running on doscserver.domain.com and it can certainly find itself?  The answer is in how the installer works.  It has local python scripts that are actually called by the Job Manager in your Deployment Manager so the error (which exists only on the docs server) is basically saying “the Deployment Manager cannot run the python script on this server”. That’s curious.  Then I realise that to run a remote script the Deployment Manager must contain a job target.  A configuration setting that tells it how to reach a remote server and gives it credentials to run the code.  I checked and although the installer had created a job target , when I  tested there were no stored credentials.  My guess is this was from an earlier attempt when UAC wasn’t fully disabled and the job target was created incompletely.  I re-created it to make sure it worked ok (it tests on save).

So back to square 1 (or snapshot 1).  I removed the half created clusters for Docs, Conversion and Viewer, I removed the Docs Proxy cluster, but I left the job target in place and relaunched the install.  This time my plan was to install in stages taking snapshots between each one.  This was a VERY bad idea.  Docs and Conversion installed and tested perfectly.  However when I went to Installation Manager and chose “Modify” to add the Viewer component it failed.  It took 8hrs to fail, during which time I monitored the logs carefully and this is what it did.

  • To modify an existing IBM Docs install and add a new component the install first UNINSTALLS all existing components even the working ones you may have installed months before
  • It then reinstalls the components it just uninstalled and attempts to install the new component as well
  • When that failed , it uninstalled all the components again and then reinstalled the original two. Leaving me back where I started 8 hrs later

It wasn’t so much the time lost as my fear that during the whole uninstalling / reinstalling of perfectly good servers it would somehow fail and break something that worked.  So.  New plan.

I now had a working IBM Docs and Conversion server to which I needed to add Viewer and Docs Proxy.  I’m staying away from Installation Manager at this point.  I want more control and I don’t want to waste another 8hrs before I can troubleshoot.  Luckily we do have the option to manually install components instead of using installation manager. To do that I extracted the installers and modified the cfg.properties files as per the documentation.  That worked fine after an initial failure.  The instructions don’t say to pre-create the Clusters and server members before running the scripts but you must do that and use the Cluster server names as in the documentation.  If you don’t, the scripts will fail when they try and connect to the deployment manager to find the servers to install onto.  If you’re using Installation Manager you don’t need to do this as the installer does it for you.

Finally there are test URLs as you install each component of <hostname>/componentname/version.txt eg http://connect.turtlepartnership.com/docs/version.txt.  To ensure this works you must regenerate and propagate the plug-cfg.xml and restart your IHS server.  Also bear in mind the syntax must be lower case /docs/version.txt /viewer/version.txt and /conversion/viewer.txt.

So there you go.  This was probably the 5th 1.0.7 install I’ve done and the first one to hit a problem. Try it first with Installation Manager. Make sure you backup (or better yet snapshot) both Deployment Manager and your  IBM Docs server before starting and if it starts failing switch to running the manual scripts.

Have fun!