OpenAM: Deploy on GlassFish v2

OpenAM 10.0.0 supports GlassFish v2 as a container.

Before You Deploy

1. Install GlassFish v2. I found a file called glassfish-installer-v2-b58g.jar on the download site, and installed it on Linux.
2. Start GlassFish and login to the admin console (default port: 4848).
3. Under Application Server > JVM Settings > JVM Options, adjust at least the heap and permanent generation sizes, and use the server option. The following list shows changes for evaluation:
   • Change -XX:MaxPermSize=192m to -XX:MaxPermSize=256m.
   • Change -client to -server.
   • Change -Xmx512m to -Xmx1024m.
4. Restart GlassFish for your changes to take effect.

Deploying OpenAM

1. OpenAM needs an FQDN at configuration time.
   To get started quickly, fake an FQDN on your laptop or desktop by giving the system an alias such as laptop.example.com or desktop.example.com. If you have never done so before, it’s not too hard. See the Wikipedia entry on the hosts file.
2. Login to the GlassFish admin console.
3. Under Common Tasks > Deployment, select Deploy Web Application (.war).
4. Deploy the OpenAM .war. (I usually rename this one to openam.war.)
5. Launch OpenAM after deployment, and configure OpenAM.

Enjoy.

Kindle: Formatting Code and Commands?

Although Amazon’s policy around the Kindle could stand to be revised, the device itself works for me. Good for text, lightweight, long lasting battery charge, built-in Wifi, large storage (for text), relatively cheap, the Kindle suffices as a book replacement. Since I bought one last summer, 33 out of the probably 40 books I read for recreation were on the Kindle.

The Kindle should be a great way to carry around a bunch of ForgeRock documentation, too. Yet for <pre>-style text like code, long commands, wide literal identifiers like com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list, and lists that use indentation for formatting, the Kindle is not so great.

The default fonts seem to allow for about 45 characters in portrait layout. Even on the 7.5′ x 9′ pages we have been using for PDF, 80 characters of monospace font can fit without sprawling into the wide left margin.

This brings me to my questions:

• How should non-trivial DocBook output be styled for the Kindle? (While this is less of a problem on something like an iPad, it may be even more of a problem on something a sys admin is sure to have when most everything else drops offline: a phone. There’s an interesting discussion on APK at docbook-apps. But what size font will you have to use to read lists, wide literals, command lines, etc.)
• And by the way, what’s the right way with Maven to build Kindle-ready output from DocBook directly?

Github: Highly Recommended

Do you work on more than one computer? Do you work on shared files with other people? Do you ever make mistakes?

Okay, enough rhetorical questions. This is not exactly news, but… Unless you need to hide your work, GitHub can help.* This is especially true for work on code, because the underlying tool, git, is built for distributed version control and source code management. Thus for work on text files where all the formatting matters, you can compare, look at what happened over time, merge independent changes, and so forth. GitHub adds the advantage giving you a place to store stuff in a way that is easy to view and to share. That’s handy even for — yuck! — binary files.

Plenty of other little features from automatically formatting a Markdown-based README to a nice source browser make GitHub more fun/less a pain in the nether regions than other solutions. If you also use another version control system, such as Subversion, then in theory you can use both together without losing any history. For my small projects, I found this not to be worth the effort.

*GitHub can also help if you need to hide your work, but you’ll have to pay for it.

OpenAM: Deploy 10.0.0 on GlassFish 3.1.2

GlassFish 3.1.2 and OpenAM 10.0.0 have some library conflicts that you can resolve. The key part of this explanation — removing glassfish-full-profile and metro packages — is from Peter Major.

Before You Deploy

Note that this is not currently a supported configuration. As Peter mentions in OPENAM-33, you might have problems in the Web Services parts of OpenAM.

Remove glassfish-full-profile and metro packages before deploying OpenAM 10.0.0. Do this either when you install GlassFish, or after you have stopped the server.

$ cd /path/to
$ unzip ~/Downloads/glassfish-3.1.2.zip
...
$ /path/to/glassfish3/bin/pkg uninstall glassfish-full-profile

The software needed for this command (pkg) is not installed.
...
Software successfully installed. You may now re-run this command (pkg).
$ /path/to/glassfish3/bin/pkg uninstall glassfish-full-profile
PHASE                                        ACTIONS
Removal Phase                                  19/19
$ /path/to/glassfish3/bin/pkg uninstall metro
PHASE                                        ACTIONS
Removal Phase                                  36/36
$ /path/to/glassfish3/bin/asadmin start-domain domain1
Waiting for domain1 to start ....
Successfully started the domain : domain1
domain  Location: /path/to/glassfish3/glassfish/domains/domain1
Log File: /path/to/glassfish3/glassfish/domains/domain1/logs/server.log
Admin Port: 4848
Command start-domain executed successfully.

Deploying OpenAM

1. OpenAM needs an FQDN at configuration time.
   To get started quickly, fake an FQDN on your laptop or desktop by giving the system an alias such as laptop.example.com or desktop.example.com. If you have never done so before, it’s not too hard. See the Wikipedia entry on the hosts file.
2. In your browser, open the GlassFish admin console.
3. Under Common Tasks > Deployment, select Deploy an Application.
4. Deploy the OpenAM .war. (I usually rename this one to openam.war.)
5. Browse to OpenAM and configure your server.

Domain Settings

As mentioned in the Installation Guide, “OpenAM core services require a minimum JVM heap size of 1 GB, and a permanent generation size of 256 MB.”

$ /path/to/glassfish3/bin/asadmin stop-domain domain1
Waiting for the domain to stop ............
Command stop-domain executed successfully.
$ cp glassfish3/glassfish/domains/domain1/config/domain.xml glassfish3/glassfish/domains/domain1/config/domain.orig
$ vi glassfish3/glassfish/domains/domain1/config/domain.xml
$ diff glassfish3/glassfish/domains/domain1/config/domain.xml glassfish3/glassfish/domains/domain1/config/domain.orig
153c153
<         -XX:MaxPermSize=256m
---
>         -XX:MaxPermSize=192m
155c155
<         -server
---
>         -client
163c163
<         -Xmx1024m
---
>         -Xmx512m
$ /path/to/glassfish3/bin/asadmin start-domain domain1
Waiting for domain1 to start ......................................
Successfully started the domain : domain1
domain  Location: /path/to/glassfish3/glassfish/domains/domain1
Log File: /path/to/glassfish3/glassfish/domains/domain1/logs/server.log
Admin Port: 4848
Command start-domain executed successfully.

After the restart, OpenAM should be ready to use.

OpenAM: 10.0.0 Released

OpenAM 10.0.0, the latest major version of ForgeRock’s open source authentication, authorization, entitlement and federation solution, is out of testing and available for download.

OpenAM 10.0.0 includes many fixes, improvements, and new features, as detailed in the release notes. The full OpenAM 10.0.0 core documentation set is available at docs.forgerock.org.

Thanks to everyone who helped with testing and doc review along the way!

Does documentation improve quality?

Sunday I read a Slashdot post on (software) Documentation As a Bug-Finding Tool. The object was a blog entry on detecting quality problems by documenting code.

Wherever you stand regarding the practice of documenting code, you might agree that writing user documentation can uncover quality issues.

• As perhaps one of the first “users” of new functionality, a writer can expose usability problems.
  Sometimes a good way of exposing a usability problem is to document thoroughly and correctly how to use the software.
• When creating examples, writers sometimes break the software.
  Breaking software when creating legitimate examples is a source of helpful bug reports. If the writer finds severe bugs, software that breaks on a legitimate example is also a sign that the software is not finished.
• Sometimes careful documentation uncovers discrepancies in how the software works vs. how the builders really want it to work.

If you also get the people building the software to review what you write thoroughly, you no doubt will manage to uncover more issues in the software, not only in the documentation. For active projects, even just reviewing the list of known issues in the release notes can help expose things everybody might otherwise fail to notice.

OpenIDM: 2.0.3 Now Available

OpenIDM is ForgeRock’s open source, open standards based identity management solution. Today we released OpenIDM 2.0.3, which is the latest update release on the 2.0.x branch.

Download OpenIDM 2.0.3 from http://forgerock.org/openidm.html. Also see the release notes, which include a the long list of improvements and fixes that have gone onto the 2.0.x branch.

If you just want to kick the tires and get started with OpenIDM, see the install guide, which describes how to set up the samples that you get with the download.

The system integrator’s guide will help you move beyond the basics.

ForgeRock: We’re Hiring

Perhaps you know people who would like to join us full time at ForgeRock. If so, please let them know that we’re hiring for a variety of jobs in sales, business development, support, and engineering. The web page behind the link has instructions on how to apply.

Why work at ForgeRock? ForgeRock has a healthy attitude, flat hierarchy, and a huge potential for growth. The work keeps you interested and engaged, with strong software and a lots of good things coming up on the roadmap. The people are at the top of their game, smart, effective, open-minded, motivated. (Not just people who work for ForgeRock, but community members, customers, and partners, too.)

Core docs: Refactoring

The docbkx-tools Maven plugin has been a great boon for building core documentation for OpenAM, OpenDJ, OpenIDM using DocBook XML source. There’s lots of flexibility in DocBook XSL configuration, and also plenty that can be done with ant content in the Maven pom.xml.

With the flexibility comes a propensity for longer and longer sections in the pom.xml. Plus, maintaining the customizations in sync for all projects gets messy when done by copy/paste. (And would get messier as we add to projects like OpenIG, OpenICF.)

So I’ve moved to using a Maven plugin that relies on mojo-executor to call docbkx-tools. The plugin also does some other work as well.

Perhaps there’s something off-the-shelf that I could’ve taken. I didn’t find it, though building something has made it a bit easier to understand what I’m looking for.

OpenDJ: 2.4.5 Released

OpenDJ 2.4.5 got the QA go yesterday. Download OpenDJ 2.4.5 from http://www.forgerock.org/opendj.html.

This release brings you improvements in how OpenDJ handles replication metadata and SSL connections. If you upgrade from an earlier version, be sure to rebuild the ds-sync-hist index after you upgrade but before restarting OpenDJ.

For more information, see the release notes.