Rev 0.4.1 (for tolven-1.0.0.beta1)
Please see the release notes if you are updating your current installation from source code.
This installation guide is for Tolven developers using source code from CVS. It also provides explanatory material about Tolven's operational environment that you may find useful. If you don't need Eclipse and CVS, consider the simpler process provided by the Tolven Installer.
In addition to Installation-specific tasks, this document provides some background information on the operational capabilities of Tolven including configuration parameters. A number of post-installation tasks are also included below.
To ensure a successful first install of tolven, you should follow the instructions as written including using exact file location, password, and configuration option suggestions. Once installed and working, you can make changes as needed.
Previously, IzPack was optional. Now, it is required. This allows the deployment process to be identical to the installation and configuration of the Tolven binary kit. We've change the kit so that it IzPack is bundled
The steps needed to create and deploy SSL credentials is now taken care of by the GUI-based config tool. The ant tasks stage-init-all, deploy-from-stage, and others have been removed.
In this installation procedure, source code is extracted directly from CVS on sourceforge, compiled, packaged, and deployed to the application server. This type of install puts you in synchronization with the Tolven development team. However, unless you have write permission to CVS, you will not be able to commit source code changes back to CVS.See Creating a Patch File if you want to submit a change to Tolven source code.
The procedure in this document shows you how to:
Subsequent sections will then show you how to:
The installation steps are described as if Eclipse is the IDE being used, but since Tolven has no specific dependency on Eclipse, you may use any other Java development environment you wish. But we recommend that you use Eclipse for the first time through. The drive letter and folders used in this guide are examples.
We recommend that for the first time through you follow the suggested folder naming, password names, and other instructions to the letter.
While Tolven can be used in a distributed, clustered configuration, this procedure is written to install the database server, LDAP server, and application server all on a single Windows XP box. Java, PostgreSQL and openLDAP have installation kits for other platforms. The java-based components such as JBoss and Tolven are platform independent as is the case with all Java components.
Windows note: This process will only work on an NTFS file system, the older FAT does not have the security features needed by some of the components. Other operating systems should not have a problem. Please note: Some of the components Tolven depends on have trouble with file names with spaces in them. Therefore, in both ant-build.properties and tolven.properties files, avoid using file names or directory names with embedded spaces. Tolven can be installed on XP Professional and Windows 2000. Although not recommended, Tolven can also be installed on XP Home for non-production purposes.
Linux note: openLDAP and PostgreSQL come pre-installed on many Linux platforms. You should not have to install those products again. If your Linux platform comes with Java 1.5 or later, you do not need to install it again either.
When editing ant-build.properties with directory and file names, Ant always wants forward slashes. Ant will then determine how to present the slashes, forward or back, to the operating system based on platform.
Prior to installation, all the download files occupy less than 300MB of disk. The installed products require about 620MB. So a safe amount of disk to work with that won't require shuffling is about 1GB.
Tolven can be installed on a modest configuration of 256MB and ~1Ghz CPU, even a laptop. However, performance will suffer. As a database application, Tolven benefits from the database server having fast disk IO including 10,000RPM or faster drives, SCSI controllers and of course plenty of memory, 1GB per CPU or greater is recommended.. Moving the database to a separate server on a dedicated high-speed LAN will help as the load increases. LDAP can also be on a separate box but that probably won't help much unless you're expecting a very large number of logins.
Multiple instances of the tolven application server can be deployed in both a clustered and non-clustered configuration. However, for the initial installation, we suggest that you just use a single application server.
For security purposes, postgreSQL must run under a non-privileged (non-root) system user. PostgreSQL will create the operating system user account for you but you should never have to log into that account. For this installation procedure, accept the default username of postgres with a password of postgres. You should not have to log into that account.
Remain in your own administrator (root) account to perform the installation. You can either create a new account or use your existing Windows account if you prefer, as long as the account has administrator permission.
Note: The Java, openLDAP, and postgreSQL components installed here are the same as installed in the regular Tolven installer instructions. Thus, you do not need to install these components again if you've already done so once before.
The table below indicates the products that must be installed prior to installing Tolven. In this step you should download each of the components to a temporary directory (I'll use c:/download in the examples) in preparation for installation.
| Component | Minimum Version | URL |
|---|---|---|
| Java JDK | 1.5.0_06 | http://java.sun.com/javase/downloads/index.jsp (Notice that this is not the EE version) |
| PostgreSQL | 8.0 | http://www.postgresql.org/ |
| openLDAP | 2.2.x | Windows Binary: http://download.bergmans.us/openldap/ (as shown in this guide) |
| JXplorer | 3.1 | http://www.jxplorer.org/ |
| Eclipse Java IDE | 3.2 | http://www.eclipse.org/downloads/ |
| Wireless Toolkit | 2.5 | (Optional) Sun Java Wireless Toolkit |
The directory should look something like this after you've downloaded all of the components:
Install the Java JDK if you don't have it installed already. Tolven requires version 1.5.0 or newer. The JDK location is your choice, I prefer something like this (depending on the version):
c:\jdk1.6.0
This kit will also install the corresponding Java Runtime (JRE) - this is the JRE that Eclipse will use. I usually accept the default location for the JRE. Tolven does not use any applets or Java-based browser plugins.
After installing Java, the JAVA_HOME environment variable should point to this (new) JDK. You can verify this on Windows as follows:
Start > Control Panel > System > Advanced > Environment Variables
The PostgreSQL documentation describes building PostgreSQL from source but that is not needed for Tolven. The binary kit is adequate.
Unzip postgresql-8.2.3-1.zip (or the current version of the Windows version of postgreSQL) into a temporary location such as
c:\download\postgres
The directory should look something like this:
I've attached screen shots of the dialog I followed to install postgreSQL starting by double clicking:
postgresql-8.2.msi
On the installation options step, I did not change any options from the default but I did change the installation directory to:
c:\postgreSQL\8.2\
by clicking the Browse button...
In the Service Configuration dialog, I've accepted the account name, supplied a password of postgres, and have asked for postgres to be installed as a service.
The Initialize database cluster will create the initial database, which Tolven will use.
Change the encoding to UTF-8.
I've supplied a password of postgres for the default database super user postgres. This means we'll have a database named postgres and a super user named postgres..
I've accepted the default procedural language settings. Tolven doesn't need anything special in this area. Tolven has no dependencies on any PostgreSQL-specific features.
For the contrib options, I have accepted the default which includes the administrative tools which you will find very handy.
If the installation completes successfully, you should see this:
At this point your database should be up and running. We'll need to shut it down to configure security.
Run the PGadminIII tool which should look like this:
This tool will allow you to start and stop the database server when the time comes and to look at the database contents. To connect to the database, provide the super user and password. I used postgres for the username and password.
The postgres installation is complete. We'll add some configuration shortly: digital certificates for secure communication via SSL.
Now that you've had a look around the empty database, we will stop the database server:
You can now delete the temporary directory you created. Mine was:
c:\download\postgres
In a later step, the Tolven configuration Manager will add add SSL certificates to the postgres directory and add schemas to the PostgreSQL database. Here, you must configure postgreSQL to use SSL.
Use Notepad or wordpad to modify postgreSQL/8.2/data/pg_hba.conf to allow network access to the database. JDBC, even from localhost, requires network access to the database. Documentation is included in that file. The uncommented line should look something like this:
# TYPE DATABASE USER CIDR-ADDRESS METHOD
host postges postgres 127.0.0.1/32 md5
You are done with the pg_hba.conf file although remember to change this file if you need to access postgreSQL from clients not on localhost.
Next, edit the postgreSQL/8.2/data/postgresql.conf file so that its security configuration enables SSL.
In the postgresql.conf file this line
# ssl = off
should be changed to
ssl = on
(remove the # and change off to on)
Installing openLDAP is straightforward. We expect many Tolven installations will have an existing production LDAP. Yet for this step, you will be installing openLDAP. It will be configured to use port 636 (ldaps) and digital certificates for mutual authentication between it and the application server.
The opening screen, after answering security and language questions, should look like this:
Accept the license terms.
Change the openLDAP installation directory to:
c:\OpenLDAP
as shown:
For the Select Components step, you must not select the option to install openLDAP as a service. By default, LDAP is installed using the unencrypted port which we will reconfigure to be encrypted.
Assuming everything goes well, the final screen should look like this:
We'll come back to openLDAP to configure the security aspects and Tolven schema. In the meantime, a very convenient tool to view LDAP is the JXplorer.
After answering the security question, the first screen should look like this:
I've chosen to install JXplorer to:
c:\JXplorer
as shown:
And I've chosen the defaults on the Shortcut step
When finished, you should see the following screen:
Issue: Some versions of JXplorer are not compatible with Java JDK 1.6 causing JXplorer to not start correctly from the installed Windows shortcut.
Workaround: Run JXplorer from the jxplorer.bat file in the top-level directory.
To install Eclipse, just unzip
c:\download\eclipse-SDK-3.2.2-win32.zip
(or similar) into a directory. Extracting it to c::\, it will result in c::\eclipse which should look something like this:
This yields a default Eclipse installation. You may want to put a shortcut to
c:\eclipse\eclipse.exe
on your desktop for easy access.
Run eclipse. In the workspace launcher dialog, override the default and enter:
C:\tolvenDev
as shown:
Verify that the compiler will be using Java 5 syntax checking and that the 1.5.0 (or 1.6.0) JRE is the default runtime.
go to Window>Preferences
Select the Compiler preference. This is usually set to 1.4. Change it to 6.0 (or 5.0 if you prefer).
then select the installed JREs. Make sure the JRE you just installed or at least a recent version of Java 5 or 6 is selected as the default as shown (you can leave other JREs in the dialog, if present).
When making this change, Eclipse may prompt you to do a full rebuild. Answer yes (you don't have a project yet so there's actually nothing to rebuild yet).
Two changes are needed to enable Tolven to be built from within Eclipse:
The Ant built into Eclipse doesn't always come pre-configured to compile Java.
In Eclipse, go to Window > Preferences > Ant > Runtime and Add an external Jar file
tools.jar from your JDK directory. the result should look something like this:
The second step is performed in the properties tab of the ant runtime preferences. Add a new property named tolven.home and give it a value of ${workspace_loc}. This will tell the build procedures where tolven is.
Tolven has no runtime dependency on Eclipse. Tolven uses Eclipse strictly as a development environment and therefore other IDEs should work just as well.
In this step, you will connect Eclipse to sourceforge's CVS server. Tolven is composed of several CVS "modules" and in this step, we will make each one correspond to an Eclipse project. You will need to switch Eclipse from the Java perspective to the CVS perspective.
Window > Open Perspective > Other...
and select CVS Repository Exploring
In the CVS Repositories view, right mouse and select New > Repository location
In the Add CVS Repository dialog enter:
Host: tolven.cvs.sourceforge.net
Repository Path : /cvsroot/tolven
User: anonymous
Password: <leave-blank>
Connection Type: pserver
You screen should look like this:
Click Finish and the contents of the Tolven CVS repository should display in the CVS Repositories view.
Open HEAD. You will will create an Eclipse project for each of the following modules. The tolven module will become a plain project while all the others will be Java projects:
The first project is not a Java project, so it will be different from the others:
Right mouse the module and select Check Out As... (plain Checkout will not work properly).
Accept the defaults and click Finish. (It is important that you use the Check out as a project configured using the New Project Wizard option.) The New Project wizard should display. Select a plain (not Java) project.
Name the project the same as the module name (tolven in this case).
Now create Java projects for the rest of the modules
as follows:
Right mouse the module and select Check Out As....
Accept the defaults and click Finish. (It is important that you use the Check out as a project configured using the New Project Wizard option.) The New Project wizard should display.
Select Java project and click Next >
Enter the name of the project which should correspond to each module name. tolvenBroswe, tolvenClient, etc. Also, check the Create separate source and output folders option.
Accept the defaults and the Tolven modules will be downloaded from Sourceforge to your system. Repeat this for each module in the list.
Eclipse may ask if you want to switch to the Java perspective.
You should decline the offer until you have each of the CVS modules created as an Eclipse project. Then you can switch to the Java perspective:
Window > Open Perspective > Java
If you see a little box with a red X next to each project, don't worry, we will fix that shortly.
Tolven uses Ant, not Eclipse, to compile, package, and deploy the Tolven application. So while Eclipse is helpful while coding, it is the Ant build script that actually matters in the end. And since the Ant script takes care of a lot of the configuration work for use, we'll set it up now.
Select Window > Show View > Ant. This should display an empty Ant window. Click the add build files Icon (indicated):
On the dialog, drill down and select the tolven build.xml file as shown: (Note: Tolven has a number of build files but you normally only need to use the top-level tolven build file directly which calls other build files as needed).
After expanding the tolven build file, your Ant pane should look like this:
NOTE: There is an ant-build.template file which you should not edit. While Tolven will update these two template files, we will not overwrite your properties files. As new releases are made, you should be careful to add changes from the template files manually to your now customized properties files.
In the Ant view, double click the ant target createPropertiesFiles. You only have to do this once.
If you are not planning to look at or modify Java source code with Eclipse, then you can skip this step.
As mentioned above, the Tolven projects have errors showing in the Eclipse project explorer. There is nothing wrong with the code itself, only that we have not told Eclipse about the libraries that each project needs. these errors will not affect the build, which is done by ant, but development and navigation is much harder in Eclipse without these additional settings.
In Eclipse, select Window > Preferences > Java > Build Path > User Libraries
Click New to create a new library named bouncy-castle (not a joke)
Click Add Jars, navigate to
C:\tolvenDev\tolven\lib\bouncy-castle
and multiple select all jars in that directory.
Now, do the same for all of the following User libraries. Everything here is included within the tolven distribution. There is nothing more to download.
| User Library | Include all JARs from here | And here |
|---|---|---|
| bouncy-castle | C:\tolvenDev\tolven\lib\bouncy-castle | |
| commons-codec | C:\tolvenDev\tolven\lib\commons-codec | |
| commons-fileupload | C:\tolvenDev\tolven\lib\commons-fileupload | |
| commons-lang | C:\tolvenDev\tolven\lib\commons-lang | |
| commons-math | C:\tolvenDev\tolven\lib\commons-math | |
| commons-io | C:\tolvenDev\tolven\lib\commons-io | |
| facelets | C:\tolvenDev\tolven\lib\facelets | C:\tolvenDev\tolven\lib\facelets\lib |
| httpcore | C:\tolvenDev\tolven\lib\httpcore\lib | |
| jaxb | C:\tolvenDev\tolven\lib\jaxb\lib | |
| jboss-client | C:\tolvenDev\tolven\lib\jboss\lib\client | |
| jboss-rules | C:\tolvenDev\tolven\lib\jboss-rules | C:\tolvenDev\tolven\lib\jboss-rules\lib |
| jfreechart | C:\tolvenDev\tolven\lib\jfreechart | |
| jsch | C:\tolvenDev\tolven\lib\jsch | |
| swing-layout | C:\tolvenDev\tolven\lib\swing\swing-layout |
After creating all of the user libraries listed in the table above, your User Libraries window should look something like this:
The next step is to configure each project. You will edit the build path for each project, one at a time. For each project, right mouse over the project name and select Build Path > Configure Build Path. In the build path dialog, Source is not changed. The Projects tab should include the projects specified in the table below. The Libraries tab should contain the libraries specified in the table below.
| Project | Projects |
Libraries |
User Libraries |
|---|---|---|---|
| tolven | - |
- |
- |
| tolvenBrowse | tolvenEJB |
- |
jboss-client |
| tolvenClient | tolvenEJB tolvenSecurityCommon |
jaxb |
|
| tolvenEJB | tolvenSecurityCommon |
JUnit* |
commons-codec commons-lang commons-math httpcore jaxb jboss-client jboss-rules |
| tolvenMobileServer | tolvenEJB |
- |
jaxb jboss-client |
| tolvenSecurityCommon | JUnit* |
bouncy-castle commons-codec commons-io jaxb jboss-client jsch |
|
| tolvenSecurityWeb | tolvenSecurityCommon |
- |
jboss-client swing-layout |
| tolvenWEB | tolvenEJB tolvenSecurityCommon |
JUnit* |
commons-fileupload |
* In the case of JUniit, the library is a built-in library rather than a user library.
JAXB: Tolven depends on JAXB 2.1. JBoss ships with JAXB 1.0 and Java 1.6 ships with JAXB 2.0. Where jaxb is used, it must be ahead of jboss-client in class-loader search order. Tolven ant build handles this problem for the components it builds. A bat file (sh on Linux) which handles the conflict is provided to run the tolvenClient credentialManager. For any other JAXB situation, adding the command line argument -Djava.endorsed.dirs=<path to JAXB> should work for 1.6. Using this argument on Java 1.5 does no harm.
tolvenMobileClient is not shown here because it requires a special setup as described in the previous step.
This is what the tolvenEJB project build path dialog should look like when done. The other projects will be similar although with fewer libraries.
Previous versions of Tolven deployed directly to a Jboss installation. This practice has been abandoned as it often caused configuration incompatibilities.
Tolven contains a task that will construct an installer jar file. This installer is needed in order to deploy, configure and run Tolven. In effect, the final step in the development process, just prior to testing, is to build and run a Tolven installer. In fact, running this installer from the development environment is the same as a customer only installing from the binary kit downloaded from Sourceforge.
The installer provides a convenient, single-file kit, including Tolven, JBoss and all dependent components except Java, openLDAP and PostgreSQL (which are presumed to already be installed and rarely need to change after the initial configuration).
The installer can optionally create a script containing the answers to all questions. This further narrows the optionality of the install and also works nicely for "headless" installations such as Linux servers that have no GUI capability. But we won't use that option here.
You will be prompted for the name of the kit. The result will be stored as an executable jar file named C:\tolven/installer\<your name>\<your name>.jar
This particular target will actually run the new installer for you which we describe next.
If not already done for you, double click or run the tolven installer from the command line:
java -jar <download-directory>/tolven-1.0.0.beta1.jar
Accept the default and press OK.
Several obvious dialogs are presented, including where you want to install tolven. All defaults should be fine.
At the conclusion of the install, a Tolven shortcut will be added to the Start Menu. The tolven installation is complete.
From the Tolven menu under All Programs in the Start Menu, select Configuration Manager.
In general, the Configuration Manager follows a two-phase setup + deploy pattern. In other words, you will be given the chance to see what is going to happen to directories outside of the tolven-config directory before any changes are actually deployed to those directories (or to the database). A status column will inform you if the target is currently out of date or not and if the configuration tool is unable to determine the status of the target.
Tolven attempts to deliver an out-of-the-box configuration that is sufficient for testing and some small-to-medium operational settings.
Tolven needs a lot of passwords which protect things like private keys, access to the database and ldap tools, etc.
Rather than ask for each of these passwords each time they are needed by the Configuration Manager, they are typically stored in a secure file called a key store. This entire key store is itself protected by a password.
When prompted, enter a group id of admin and enter the admin password which is sysAdmin by default. If you choose not to answer these questions, the Configuration Manager will ask you for individual passwords as they are needed (you will quickly find this tedious).
The actual passwords stored in this file include the following (if you supply the admin password, you will not need to supply these passwords)::
| Password | Default |
|---|---|
| A password for each of the self-signed certificates that will be created | tolven |
| The LDAP root password | secret |
| A password to protect the LDAP keystore | tolven |
| The messaging password | mdbuser |
| A password to protect the messaging keystore | tolven |
| The postgres root password | postgres |
| A password to protect the Postgres keystore | tolven |
At this time, the tolven application server, openLDAP, and PosgreSQL servers should not be running. If they are, you should stop them.
In short, this step will create a public key infrastructure so that the database, LDAP and application server can communicate with each other with mutual authenticated ssl certificates. All of this will be created in a staging area under c:\tolven-config without actually changing any of the components. At the completion of this step, you can peruse the credentials prior to deploying them.
Here is what the screen looks like prior to generating credentials.
When you press the Generate Credentials button, the screen should look something like this:
You must exit and restart the Configuration Manager so that it can use the credentials just created.
This one-time step creates a certificate authority (like a mini-Verisign) and issues certificates in order to support the following Tolven security topology. While this is a real public key infrastructure, the root authority is self-signed since a real root certificate would need to be purchased from a commercial source.
At the same time, the security setup will take care of JXplorer and PGadminIII which must also communicate with these components. Finally, the Configuration Manager itself must also be authenticated (it too may be remote from the various components so it can be afforded no special permisssion).
The second phase of credential configuration will be to deploy the variious credentials to each of the components. This phase may be performed many times. For example, if you install a new version of the Tolven application server, or a new version of the database, then you can use this step to redeploy the same credentials to the new server location.
Note: Newly deployed credentials are not detected by openLDAP so if you happen to have openLDAP running (you were advised earlier to shut it down), you will need to shut it down before deploying (new) credentials to it.
The following shows what the screen should look like after pressing Deploy Credentials
This step only needs to occur once for a tolvenLDAP server.
c:\openLDAP> md tolvendata
Add the root elements into this new LDAP database
c:\openLDAP> slapdadd -f spald.conf -l tolveninitial.ldif
Create a desktop icon that will run openLDAP: Right mouse on the desktop, select New > Shortcut.
We want ldap to listen on the secure port (636) ldaps:// so the target should look like this:
C:\OpenLDAP\slapd.exe -f slapd.conf -h ldaps://
Click OK to save the shortcut.
Now double click that desktop shortcut to start LDAP.
openLDAP will prompt you for the pass phrase used to protect its private key. I selected tolven as a pass phrase (password) during security configuration. Enter that password and after hitting enter, LDAP should be running. LDAP is pretty quite on the screen. This is what it looks like when its running (the cursor should be at the left margin).
Your openLDAP server is up and running, listening on a secure port. You should rarely have to restart it.
At this point, you can start the database server. Install it as a service so that it runs automatically on system startup. It can run without further intervention. (If it's already started, stop it and restart it in order to pickup the new security settings).
you may also want to connect to the database named postgres using that same menu. Doing so will allow you to browse the database and thereby ensure that the database server is up and healthy.
Note: The Tolven Configuration Manager will add schemas to the database but the actual tables are not created until JBoss deploy time (Hibernate is doing the actual work). Each subsequent Tolven deployment might add new columns or new tables during deployment. However, it won't delete anything.
JBoss is configured in this step. As usual, there are two phases: generate files, which is normally only done once. And Deploy, which is done each time a new JBoss (Tolven application server) is installed.
Here is what the generate phase looks like after pressing Generate
And this is what the Deploy step looks like after pressing Deploy:
The Configuration Manager allows you to test connectivity to the key servers. This test will help you zero in on any configuration problems. Of course at this point we don't expect the JBoss application server to be running, but both postgres and openLDAP should be.
The configuration manager will create the basic LDAP elements needed by Tolven. If the schemas are not up to date, click the Create Schemas button. Doing this again will cause no harm.
Before running the Tolven application server for the first time, you will need to create schemas that will accept the tables created by the object-relational mapping tool. Clicking the Create Schemas button will create these schemas. (Clicking the button again does no harm).
At this point, the Tolven Application Server can be started. This can be done by selecting Start Tolven JBoss from the Tolven menu under the Start Menu > All Programs. There will be a lot of chatter output from the command window that opens.
You will now be prompted for passwords that are needed to unlock various keys needed by Jboss to connect (securly) to LDAP, DB, and for message processing. In the default configuration supplied by tolven, all passwords are tolven.
Other prompts are similar.
You can verify that the application server started correctly by going back to the Connections tab in the Configuration Manager and checking the JBoss connection. At this point, everything is up and running. The next step will be to configure the Tolven runtime properties.
This step will configur the Tolven runtime properties. An initial set of properties will be created which you can deploy to the database. Thereafter, you can change these properties when needed, even while the application server is running. Here is a screenshot of the runtime properties after some changes.
When ready, click the Update Properties to deploy to the database. Once set, you should rarely have to change most of these properties. However, you can edit the property values directly in the Value column (Double click the cell).
An import button is provided for properties not initially supported by the Configuration Manager. The import file must be in standard "',properties" file format, that is
attribute=value
with no quotes.
Tolven needs to communicate with LDAP in order to create users. The default setting in this file should be fine as long as you've been following this installation guide.
tolven.ldap.url=ldaps://localhost tolven.ldap.baseDN=ou=people,dc=tolven,dc=com tolven.ldap.genGroupDN=cn=gen,ou=groups,dc=tolven,dc=com tolven.ldap.rootDN=cn=Manager,dc=tolven,dc=com
[If you skip this step, you will only be able to create demo users (regular users that have not had email activation)]
Mail is used for sending invitations and notifications in Tolven. You must tell tolven.properties about your mail server. Usually the mail server is maintained by your ISP or web hosting service or can be an in-house mail server. You may notice that the mail.* properties are those used by JavaMail to transport the message. Tolven does not modify those parameters, it just passes them straight through to JavaMail. The tolven.mail.* properties are used directly by Tolven to construct the message itself.
You do not need a special mail server for Tolven. JavaMail is used as a mail client only. If you are evaluating Tolven, you can probably use your own personal email account. But for production you'll want to setup a send-only account specifically for this purpose. In any case, be careful of the plaintext password stored in this file (when required by your mail server). This configuration should be similar to the way you setup your Outlook or other SMTP-based mail clients. (Tolven doesn't read mail so it does not require POP3 or IMAP configuration).
Name |
Value |
Description |
|---|---|---|
| mail.smtp.host | smtp.bizmail.yahoo.com | The address of your SMTP server |
| mail.smtp.auth | true | If the server requires authentication or not. Many public servers now require authentication. |
| mail.debug | false | To get a bunch of log file chatter when establishing a mail connection and sending a message |
| tolven.mail.from | notify@mycompany.com | The from address of the email |
| tolven.mail.fromName | My Company | The name of your business or agency |
| tolven.mail.user | notify@mycompany.com | The username under which the mail will be sent |
| tolven.mail.password | mypassword | If mail.smtp.auth=true, the password of the account sending the mail |
The gmail mail server, for example, requires that the mail client talk to it via SSL on port 465. The JavaMail configuration should therefore look something like this:
mail.transport.protocol=smtps mail.smtp.host=smtp.gmail.com mail.smtp.auth=true mail.smtp.socketFactory.port=465 mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory mail.smtp.socketFactory.fallback=false
The default is fine for demo purposes. This must be an globally unique OID (or possibly a UUID) that will be added to any identifier created by Tolven that will be sent to other systems. Uniqueness cannot just be to Tolven, it must be to the instance of the repository. For example, if you create two Tolven repositories, they must each have a unique OID so that identifiers shared between them, or with other systems, are not confused.
tolven.repository.oid=1.2
[If you've skipped the email configuration, you can also skip this invitation configuration.]
Tolven invitations are constructed in an asynchronous process (in a Message Driven Bean) fed by messages sent through a JMS queue. This process, in turn, calls back into the Tolven application to construct the HTML content of the message. In effect, this callback resembles a user sitting at a browser but Tolven captures the response and stores it in the message body. In order to facilitate this connection back to itself, Tolven must know what the host, port, and context root is of the application. (In a larger implementation, this might actually point to a separate Tolven server that won't interfere with live HTTP traffic.)
Name |
Value |
Description |
|---|---|---|
| tolven.invitation.host | mycompany.com | The address of your SMTP server |
| tolven.invitation.port | 8080 | If the server requires authentication or not. Many public servers now require authentication. |
| tolven.invitation.root | /Tolven | To get a bunch of log file chatter when establishing a mail connection and sending a message |
| tolven.invitation.replyTo | http://mydomain.com:8080/Tolven | When an invitation is sent, this url will be included in the message to allow the receiver to get back into the Tolven application and take action on the message. The host and port (if not 443) should point the user directly back to your running Tolven application. Use either a DNS name or numeric IP address. Localhost won't work unless you only send invitations to yourself (the sys admin). |
Here is an example of what the invitation configuration would look like if you only wanted the application to work for users logged into the same system as the jboss (web) server. While not very practical, it is easy to change later by substituting localhost with the IP address or DNS name of the server and restarting the server:
tolven.invitation.host=localhost
tolven.invitation.port=8080
tolven.invitation.root=/Tolven
tolven.invitation.replyTo=https://localhost:8443/Tolven/private/dispatch
The login page has two different registration links, one for a normally activated login using email and the other creates a demo user without needing email activation. Two tolven.properties allow you to configure either or both of these options. (Turning both off means users can only login to pre-existing accounts). For example, the following settings remove the email-activation step.
tolven.login.create.demoUser=true
tolven.login.create.activatedUser=false
The two kinds of user registration pages are separate pages. The fields in each are customized to the type of registration. For example, creating a demo user account has a separate username (which is NOT an email address) and an email mail address field which is not verified. The full email-activation page, on the other hand, requires an email address as user id and it verifies the address via email.
If you would rather not use email activation, just disable it by setting the property:.
tolven.login.create.activatedUser=false
Tolven eMail registration is designed to reduce the need for administrative intervention. One thing that can occur that might otherwise require intervention is when a user creates a login but enters an incorrect email address and/or forgot their password. What the following setting does is set a timer so that if the user does not respond to the activation email within, say, one hour, the new login is automatically deleted. Thus, without intervention, if the user were to try again in an hour, it would be as if they had never been on the system in the first place.
tolven.register.expiration=3600
When displaying dates and times, Tolven uses the following algorithm to determine which timezone to use:
If you specify the timezone in tolven.properties, use the fully specified timezone format such as one of the following for correct daylight savings time handling:
tolven.timezone=America/Los_Angeles tolven.timezone=America/Phoenix tolven.timezone=America/Denver tolven.timezone=America/Chicago tolven.timezone=America/New_York tolven.timezone=Europe/London tolven.timezone=Europe/Paris tolven.timezone=Asia/Singapore tolven.timezone=Australia/Sydney etc
After making the changes, save this file. It will be copied into jboss so that it is available to the running Tolven.
Tolven allows users to create random data in order to test the functionality of Tolven without having to manually enter a lot of data. The setting specifies how many patients can be generated in any one request by any one user for a clinical account.
tolven.gen.patient.max=1000
This limit is not a total, only the number that can be created each time the user creates such accounts. This limit only applies to Clinical accounts since personal accounts get just a single family and that family will have between one and about six people.
Sponsorship provides a means to control new registrations. It is a completely optional feature. If not active, users are free to register a new login without restriction. With Sponsorship enabled, the administrator of an account (the issuer) asks the system for a code which they can distribute as they see fit. Anyone with that code can then create a new Tolven login. The issuer does not need to know the user's login id. The new user is not a made a member of the issuer's account.
An example where this feature is useful is an employer that wants to make a personal health record available to employees but does not want to have any access to the employee's health data. Thus, the number is a "free pass" to use Tolven.
Tolven Invitations are different from Sponsorships: Invitations are direct communications between known Tolven accounts.
The only connection between the issuer and any users that use the code from that issuer is that the issuer can get a list of each user's email address, first and last name that used the code to create a Tolven login. The issuer has no access to the user's data in any way.
A new tolven.properties property has been added to support sponsorship. It's name and default value is:
tolven.register.referenceRequired=false
If true, users will be required to provide a "reference code" in order to create a new Tolven Login. (The code is not required to login).
Before setting this flag to true, bootstrapping is needed. Don't set this flag to true until you've logged in, created an account, and in the account administration page created at least one sponsorship reference code. Make a note of this code so you can hand it out to other people. Once you set:
tolven.register.referenceRequired=true
all subsequent registration requests will require a valid reference code. Once a user login is created, the reference code is no longer needed, it is not required to login. But other users may be able to use the same code.
Turning sponsorship off (tolven.register.referenceRequired=false) and on is allowed. When turned off, references already created will be retained but new references will not be needed or asked for.
Tolven is designed to avoid any client-side configuration, storage or browser plugins. However, because Tolven takes advantage of certain browser features that improve the user experience and reduce response time, a recent web browser version that supports javascript and XmlHttpRequest (the AJAX features), such as IE 6 or Mozilla Firefox 1.5, is required.
For Mozilla BrowsersUnder Tools -> Options -> Advanced -> Encryption (tab).
- Ensure that Tolven is not listed as a certificate authority
- Make sure that both the checkboxes are checked for the "Use SSL 3.0", and "Use TLS 1.0"
In your browser, enter:
http://localhost:8080/Tolven
This should redirect immediately to a secure connection which, because the server certificate is self-signed, will display a warning.
For production, you'll use a certificate from a commercial authority which eliminates the warning.
Once you get past the security barriers, you'll have a login screen that looks something like this:
Since there are no users in the system, you'll want to register one. Select the Create Demo User link. this will skip the email activation step which avoids JavaMail and issues you might have connecting to your mail server. You can then login immediately with the username and password you provided during registration.
Once you login, you will need to create an account.
Be sure to generate some test data for the new account you created by checking the checkbox on the select account page.
At this point, tolven is ready to use.
The following steps are optional or provide additional capabilities.
Although not required, it would be nice to see what's going on in LDAP. So we'll startup JXplorer. This should have been installed in the Windows start menu.*
*Issue: Some versions of JXplorer are not compatible with Java JDK 1.6 causing JXplorer to not start correctly from the installed Windows shortcut.
Workaround: Rather than using the Start menu, run JXplorer from the jxplorer.bat file in the top-level directory.
Click the connect icon (or File>Connect) for the connection dialog and enter the connection information.
Port should be changed to
636
BaseDN:
dc=tolven,dc=com
Level should be changed to
ssl + user + password
user DN is:
cn=Manager,dc=tolven,dc=com
The password, which is specified in c:\openLDAP\ slapd.conf, is
secret
The first time you connect, JXplorer will be unable to determine the authenticity of the self-signed certificate and so will prompt you to accept the certificate. You may look at the details (which can be changed in the ant-build.properties file you configured earlier). Select Always (or This Session Only)
There's nothing too interesting in LDAP yet but this is what it looks like:
As soon as users are added to Tolven, they will show up as people in LDAP.
If you are not planning to access tolven from mobile devices, then you can ignore this step.
The tolvenMobileClient project is different from the other Tolven projects. While it uses the compiler from JDK1.6.0, the libraries it uses are different from the usual libraries. As Sun puts it, the write once, run anywhere Java concept doesn't apply to mobile, mainly due to footprint and communication bandwidth limitations.
First, if you haven't done so already, install the Wireless Toolkit located in the download directory:
C:\download\sun_java_wireless_toolkit-2_5-windows.exe
which you should have already downloaded from:
http://java.sun.com/products/sjwtoolkit/download-2_5.html
You can accept all of the defaults. The kit should be installed in:
c:\wtk25
In Eclipse, open tolven/resources/ant-build.properties and uncomment the wtk.home property. If you installed the tollkit to a different location, then changes the location in wtk.home.
In the Eclipse Ant pane, right mouse and add the build file in tolvenMobileClient:
Right mouse over the tolvenMobileClient project and select Build Path > Configure Build Path...
Remove the JRE system library and add the two JARs containing the mobile APIs as shown:
You can now create the mobile client tolven.jar and tolven.jad files by clicking packaging under the tolvenMobileClient Ant build file. These files will then be picked up by the deployment process so that they are available from the server for download to the phone.
You may also notice an emulator Ant task. This will run the mobile client in an emulator on your system without needing an actual mobile device. But the emulator still depends on having access to a running Tolven server.
Further details here.
Until you have more than around 10 or 20,000 patients in the database, this step won't help much. However, it is an easy step to forget later so it is a good idea to take care of it now so you don't think Tolven has a performance problem later.
Open pgAdminIII tool, connect to the database server and select the postgres database.
Open a SQL window. Now, in Eclipse, open tolven/postgres-config/indexes.sql
This file has drop index commands at the beginning which you can ignore the first time through. Copy and paste everything else into the SQL window and execute it. It should complete in a few seconds, maybe longer if you've already added a lot of data to the database.
After your system is up and running, you may want to grab updated source code from time to time.
In Eclipse, multiple select the Tolven projects, right mouse and select Team>Update (if you have made local source code changes, select Team Synchronize instead) This will pull fresh copies of source code from CVS on Sourceforge.
Note: The CVS repository changes as Tolven developers check in code so updates, especially to HEAD, can be very dynamic.
.
In the projects context menu (above) you will see a Replace With option which will allow you to specify or select a specific tag. This will replace your local code with that tag. Be sure you keep all projects in your workspace on the same tag.
When you first install Tolven, you run an Ant target that creates a new ant-build.properties file. During development, we may add new properties (and sometimes delete properties) from this file. While we update the ant-build.template file, we do not update the ant-build.properties file since you may have made local changes to it. Therefore, you will need to manually add any changes made to template/ant-build.template into your resources/ant-build.properties file. Alternatively, you can copy template/ant-build.template contents to resources/ant-build.properties and repeat the adjustments you might have made to the file when you first installed.
In any case, do not check in changes to ant-build.properties, only ant-build.template.
Select all of the tolven projects in Eclipse Package Explorer view as shown here. Right mouse and select Team > Synchronize. This will selectively update your source code from CVS and not disturb any local changes you may have unless you specifically select override and update. You will be pulling source from the most current versions (HEAD) of files in CVS. This is a constantly moving target and so you have little assurance of the stability of the code (although you are assured of seeing the latest code).
We tag source code nightly so that you have the option of pulling a slightly more stable "snapshot" of the source code. These snapshots are labeled with a B, the year, month, day, hour and minute of when the snapshot was done. To pull a snapshot rather than the current version of source code is simple in Eclipse. (Be sure you have no uncomitted local changes). Select all of the tolven projects in the Package Explorer, right mouse Team>Switch to another Branch or Version option. Select Select the tag from the following list and choose the tag you want to download from under Versions. This will adjust your source code environment backward or forward to match that tag. (Tags are listed below along with the notes about that release, most recent first).
Selecting an older tag than the one you've used won't have any effect on the database or LDAP servers. So you may experience backward compatibility issues. Neither forward nor backward compatibility are promised between low-level builds. Nevertheless, we will try to warn you when this is a possibility and suggest a remedy if at all possible.
New libraries are sometimes added to the build. See this section of the above for the complete project-to-library matrix so that your Eclipse Package Eplorer can do proper error checking..
OpenSSL, which is used by JBoss, PostgreSQL and openLDAP, will not accept a key file that has world read permission so you will need to hunt each one down and change it's permission. (Microsoft XP Professional and Linux. You can skip this step when installing on XP Home.
Starting with jboss:
C:\<tolven-kit>\tolven-jboss-4.0.4.GA\server\tolven\conf
Right mouse these three files and select properties:
If you don't see the security tab, cancel the properties dialog, go to Tools > Folder Options and unselect the View option "Use simple file Sharing" (at the bottom of the list of View options). Now select the files again...
Click the Advanced option which should look something like this. You'll need to uncheck the Inherit from parent... checkbox.
doing so will ask if you want to copy or remove the settings for these files:
Select Copy and then you can remove the Users group from the access list which should look something like this:
OK, now that you have the pattern, do the same thing to other files as follows:
In C:\openLDAP, three pem files need to be protected.
In
C:/postgreSQL/8.2/data
three more files need to be protected.
You'll notice in this case that the user postgres is also listed among the users that can access these files, which is good, but like the other files, you must remove access by "users" if present.
Finally, you'll need to change the credentials used by the database administration tool which are stored in the hidden portion of your documents and settings.
Note: Substitute your username for <tolvenuser> below. Look in the directory:
C:\Documents and Settings\<tolvenuser>\Application Data\postgresql
which was created when you installed PostgreSQL.
In this directory are the credentials that the PGadminIII (postgreSQL DB server client) needs to provide to the postgreSQL server. They essentially identify the user account authorized to access the database server.
Select the two files and remove world (users) access to the file as you did with all the others.
