Table of contents

• Introduction
• Details
• Java 6
• Browsers
• Cygwin
• Apache Tomcat
• Eclipse
• Building Open eSignForms Using Eclipse
• Passwords
• Database using PostgreSQL
• Create the database
• Running the Application in Eclipse
• SMTP and IMAP
• Other tools
• Linux setup
• Mapping code from the Eclipse project to Linux paths

Introduction

These instructions are pretty high level right now, so we'll want to nail it down to a more easily repeatable set of instructions, but we had to start somewhere!

Yozons offers low-cost hosted solutions for those who prefer to just get up-and-running. Yozons also offers private web servers for those who want their own domain name (and SSL cert).

Details

Java 6

We start by installing the latest version of Java 6 SE available. It appears that these days you just need the JRE. The version tested here was 6.0.26.

Because of the sophisticated encryption we use, you'll need the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files installed in your jre/lib/security folder. Note that encryption entails issues with the U.S. government's misguided and impractical export rules. For Windows, be careful you may have 32-bit and 64-bit JREs installed and you'll want to update both as much depends on which Eclipse uses when it starts Tomcat, of if you run Tomcat directly yourself. You can download these files from the Java download site (often at the bottom of the page).

Browsers

You can test as you see fit, but we're basically running the latest releases of Firefox, IE, Chrome, Safari and Opera. Earlier versions likely work, but with a Web 2.0 interface, a modern browser is best and fastest.

Cygwin

We use Cygwin on Windows so we have a Unix/Linux-like environment for our shell scripts. We actually use very few since we only develop on Windows and have never deployed in production on Windows (though it certainly should be doable), but the scripts for DB setup and the like are still driven by shell scripts. Generally, the standard install works well for our needs.

We generally add 'vim' from the Editors choices if you know how to use 'vi'. We often add links, too, if you ever need a command line web browser for simple testing needs.

We like to modify the shortcut properties Options to increase the command history buffer size from 50 to 500, and include 'QuickEdit mode'. We also modify Layout to use width 220 in both locations and a screen buffer height of 5000 so we can scroll back easily. We also set the Font to 8x12.

Of course, those on Linux/Unix don't need to worry about this.

Install the 'scripts' files in the cywgin/Linux-user account's 'bin' folder. You can also use a 'scripts' folder, but then be sure to add the scripts folder to your PATH.

For Windows, you'll need the .cygwin variants (we delete the file without the extension and then rename the .cygwin variants by removing that extension). All cygwin files typically need to a dos2unix * done on them so they'll run correctly. (See below for Cywin details.) Note that script files bashrc and profile should be in the home directory, not 'bin'. You can then update .bash_profile to include . ~/profile and .bashrc to include . ~/bashrc.

If you find that scripts won't run on Linux or via Cygwin's shell, you may need to do a dos2unix * on the text files and scripts to ensure they are in encoded correctly. You may also want to do a chmod +x ~/bin/* if the scripts don't seem to have execute permission.

Apache Tomcat

For testing, we generally run Tomcat from Eclipse, so it's best to download and install Tomcat next. If you plan on running Tomcat as a Windows service, there's a special installer for it. But we just download the ZIP file and really only run it via Eclipse, extracting to C:\. The version tested here was 7.0.21. (There is a bug in Tomcat prior to this release that caused errors in the import of esf.js file because of the new javascript mime type standard that changed from text/javascript to application/javascript.)

Eclipse

Install the latest version of http://www.eclipse.org Eclipse IDE for Java EE] developers. The version tested here is Indigo. We extract all to c:\Program Files. We set our workspace to c:\project.

Install the Vaadin Eclipse Plugin as instructed on their site.

We find that for debugging on your local computer, it's nice to be able to make changes without having the webapp reload, which you can often do because of the hotspot code changes Java allows. Open the view "Servers" -- if the "tab" is not shown at the bottom of your edit area along with Problems, Console, Error, History, etc., you can use the Window->Show View->Other to pick Server->Servers. If no servers appear, right-click New->Server; then choose Apache->Tomcat v7.0 Server, click Next and choose the location where you installed Tomcat (i.e. something like C:\apache-tomcat-7.0.21). Double-click your server (named Tomcat v7.0 Server at localhost or whatever version you are using) so you display the Overview and Modules "tabs". Click on Modules, then for your project (/open-eSignFormsVaadin for us -- see below for downloading the project code first) click the Edit button to uncheck the 'Auto reloading enabled'.

Using the same Servers configuration, we make the following changes:

Overview->Ports: Change HTTP/1.1 to use port 80 (unless you prefer 8080 for testing, but you'll need to put them in all your testing URLs).

Overview->Timeouts: Change 'Start' to be 600 to give you more time if you plan on debugging code during application initialization and don't want Eclipse to timeout the startup of your webapp.

Overview->Generation Information->Open launch configuration: Add to Arguments tab, VM arguments: -Xmx512m -Desf.deploybase=C:\deployments

Tip: For production deployments, you will not use Eclipse and you won't run Tomcat inside. These are just for software developers, not for those who will run/use the system.

Building Open eSignForms Using Eclipse

Create the Vaadin Eclipse project by downloading the code from CVS, project open-eSignFormsVaadin.

:pserver:cvsanon@open.esignforms.com:/home/cvs

If you have edit/commit permission, you'll need a user account and password with SSH access to CVS with something like:

:extssh:USERNAME@open.esignforms.com:/home/cvs

It seems from a fresh install that you'll want to right click on the open-eSignFormsVaadin project, click on Properties, click on Vaadin, and even though it may show the current Vaadin JAR (6.7.5 at this time), you should do a download and APPLY to get it put into the Eclipse area where the GWT JARs are also stored.

(If you plan to do any VaadinCKEditor project work, not necessary for Open eSignForms itself, you'll need to install a subversion plugin -- we use Subversive SVN Team Provider from the Eclipse installation location and we selected the SVN Kit 1.3.5. This related project is hosted on Google Code.)

You will need to compile the Vaadin widgets before testing. Vaadin widgets compile to GWT-based javascript and are stored in the WebContent/VAADIN/widgetsets folder.

Eclipse should automatically compile all of the regular Java source code into the WebContent/WEB-INF/classes folder. If not, right-click on the project in Eclipse and select Properties, then click on the "Java Build Path", click on the Source tab, the "Default output folder" should be something like: open-eSignFormsVaadin/WebContent/WEB-INF/classes but this normally should be set automatically if you are using checked-in code or a source code snapshot release.

Passwords

The standard JAR Open eSignForms is delivered with should include the .class and .java source files that go with it.

There are also several *.properties files with passwords in them. For testing, these work out of the box, but of course in a production setting, you'll want to copy these individual .properties files into the WEB-INF/classes folder so they can have better values specified.

openesignforms.properties - Sets the two boot passwords to 'test1' and 'test2' respectively. These values must match the values given to DbSetup when a new system is deployed.

connectionpools.properties - Sets the database user and password for each deployment. The default user and password is the same for both: esignforms

Remember, in production, you never want to use such passwords.

In Linux, often the IP address 127.0.0.1 is mapped to localhost.localdomain as well as localhost. On Windows, the former is generally not present, so you either need to change the .properties files that use localhost.localdomain to be just localhost, or you need to update c:\Windows\System32\drivers\etc\hosts so that you map the address to both names.

Database using PostgreSQL

Install PostgreSQL 9 per its usual mechanisms. The version tested here was 9.0.4.

It's just a convention, but we use the DB user 'esignforms' for our admin account, and each 'deployment' (a customer system that has its own webapp and database on the server) uses a 5 character unique name that is used as that application's DB user. The name is also the base name in the deployment folder for its database tables, log files, etc.

For Windows, the installer defaults to the user 'postgres' so you can add our DB user with commands like (for production, use good passwords, of course): {{{psql -U postgres CREATE USER esignforms WITH PASSWORD 'esignforms' SUPERUSER;}}}

Create the deployment folder in the home directory (/home/esignforms/deployments) or C:\deployments. Put the 'templates' folder in there that defines the structure used for each deployment. You can delete the CVS subdirectories and DELETEME.txt files. On Windows, you will want to give all users full permissions to the C:\deployments folder when testing. We are not sure the about the exact user permissions needed, but generally you want to access those files from Windows Explorer, your cygwin user, and the PostgreSQL user.

Update the ~/profile to point to the locations where all your stuff is. The next time you run cygwin, it should have the new good values. You can test with java -version and psql template1 to see that Java and Postgresql are setup for cygwin access.

Create the database

Install of the SQL code from 'database/postgresql/ddl' into the 'ddl' folder in your home folder. We use the 5 letter deployment id for creating the database for a given webapp.

If you have a previous install and need to wipe it out first, use:
  ./drop_db

To create a DB, use:
  ./create_db
  Please enter the LOWERCASE name for the OpenESF database and user: test          (for testing, we just use 'test' for our deployid and DB user)
  Please enter the password to use for the OpenESF esfapp user test: test          (for testing, we just use the password 'test')
  Type 'y' to create the database.
  Type 'y' to create the tables.
  
  ./rundbsetup
  or
  In Eclipse, create a Java Application (debug configuration) for 'DbSetup' like below and then run it:
    Project: open-eSignFormsVaadin
    Main class: com.esignforms.open.db.tools.DbSetup
    Program Arguments: open-eSignFormsVaadin
    VM Arguments: -Xmx512m -Desf.deploybase=C:\deployments
    Working directory: C:\project\.metadata\.plugins\org.eclipse.wst.server.core\tmp2\wtpwebapps\open-eSignFormsVaadin\

    (Obviously, you'll need to tweak any of the specific locations/names to match your environment.)
    
    When you run DbSetup you'll see something like:

Copyright (c) 2009-2011 Yozons, Inc.
DbSetup - Sets up the database for Open eSignForms v1.7.0

Enter setup command (initdb,addsuperuser,initsetup,setpassword,quit) [quit] : initdb
2011-07-22 00:31:49.353 UTC-PublicKeyGenerator provider = BC version 1.46; keysize: 4096
insertDeployment - Created deployment with id: b96513a5-9618-40ab-a1cd-79abf611ea32
Enter boot password 1: test1
Enter boot password 2: test2
insertBootKey - Added new boot key
Added super group: ESF/Group/Deployment/SuperAdmin
Added system admin group: System/Administrator
Added All Users pseudo-group: ESF/Group/AllUsers
Added External Users pseudo-group: ESF/Group/ExternalUsers
createInitialProperties - Updated deployment with global properties id: adeb5303-bdbe-4d46-968e-a8787db45160; deployment properties id: d4acceb5-977c-484a-b801-9666f7e6fd07
Added template library: ESF/Library/Template

Enter setup command (initdb,addsuperuser,initsetup,setpassword,quit,convert1.5) [quit] : addsuperuser
Enter super user's email address [support@yozons.com] : super@openesfdemo.com
Enter super user's first/personal name [Yozons] : Super
Enter super user's last/family name [Support] : Openesf
Initial super user password: Test
insertSuperUser - Added new super user: super@openesfdemo.com
insertUserIntoSuperGroup - Added new super user: Super Openesf <super@openesfdemo.com>; to super group: ESF/Group/Deployment/SuperAdmin

Enter setup command (initdb,addsuperuser,initsetup,setpassword,quit,convert1.5) [quit] : initsetup
Enter Commercial DB license size in MB (enter 0 for AGPL deployment) [0] :
Enter company name: Demo Company
Enter company street address: 123 Main St.
Enter company city: Kirkland
Enter company state: WA
Enter company zip: 98033
Enter company default phone number [800.555.1212] : 800-555-4321
Enter company group EsfName [CompanyRenamePlease] : DemoCo
Enter company default email address [renameyser@pleaserenamecompany.com] : democo@david.com
Enter programmer user's email address [open-esign@yozons.com] : myprogrammer@openesfdemo.com
Created company group: com.esignforms.open.user.Group@a1c6407f
Created company programming group: com.esignforms.open.user.Group@a1c6407f
Added company programming group to Library, Package, Transaction Template and Transaction Listing views
Added company groups to list/view the template library
Created sample company library: Lib/DemoCo
Created default style and version: ESF_DefaultDocumentStyle
Set default style in template library: ESF/Library/Template
Set default style in company library: Lib/DemoCo
Created standard package document: StandardPackageDisclosures
Created image: Logo
Created image: SignHereLeftArrow
Created image: PackageDocumentCompleted
Created image: PackageDocumentFixRequested
Created image: PackageDocumentRejected
Created image: PackageDocumentToDo
Created image: PackageDocumentViewOnly
Created email template and version: SetPassword
Created email template and version: ForgotPassword
Created email template and version: PasswordChanged
Created email template and version: PasswordLockout
Created email template and version: DefaultPickupNotification
Created dropdown and version: ESF_BackgroundColor
Created dropdown and version: ESF_BorderTypes
Created dropdown and version: ESF_Font
Created dropdown and version: ESF_FontColor
Created dropdown and version: ESF_FontSize
Created dropdown and version: ESF_FontStyle
Created dropdown and version: ESF_TextAlign
Created dropdown and version: ESF_Locale
Created dropdown and version: ESF_TimeZone
Created dropdown and version: ESF_USA_PostalStatePossession
Created dropdown and version: ESF_USA_PostalStates
Created dropdown and version: ESF_PartyRenotifyTimes
Created dropdown and version: ESF_TimeIntervalUnits
Created drop and version: ESF_DateFormat
Created dropdown and version: ESF_TimeFormat
Created drop and version: ESF_DecimalFormat
Created drop and version: ESF_IntegerFormat
Created drop and version: ESF_MoneyFormat
Created propertyset and version: ESF
Created propertyset and version: MyCompany
Created propertyset and version: MyCompany
Added template package and version: ESF/Package/Template
Added template package and version: Package/Template
Added ESF template transaction template: ESF/TransactionTemplate/Template
Added company template transaction template: TransactionTemplate/Template
Created programming user: Open eSignForms Programming <myprogrammer@openesfdemo.com>

Enter setup command (initdb,addsuperuser,initsetup,setpassword,quit,convert1.5) [quit] : quit

Running the Application in Eclipse

Generally for testing in Eclipse, click Debug As->Debug On Server->Apache->Tomcat v7.0 Server. The first time you just need to point it to where you installed Tomcat above.

SMTP and IMAP

Under the System config->Deployment link in the application, you must configure the SMTP Return Path hostname, SMTP server and IMAP server to use. These are Internet standard services external to Open eSignForms, but must be available. Open eSignForms sends out notifications and invitation emails using a scheme that will associate bounces and replies to the original email sent.

Our basic configuration works like this:

• Set the SMTP Return Path Hostname to the hostname where you are runnning your SMTP server. The Return-Path SMTP header, along with the Reply-To and Sender headers, are used by receiving systems to validate that an email is legitimate and not spam sent through an open relay. In general, this is the server name where Open eSignForms is installed. On our demo system, we use the value open.esignforms.com which results in emails sent with a return-path something like: Return-Path: <deploy2_pxriwpqowoislybxlucq@open.esignforms.com> The 'deploy2' value is the deployment id so that a single server can run multiple deployments of our application for multiple customers. The 'pxriwpqowoislybxlucq' is a random, unique value that allows us to associate bounces and replies to the original email sent.

• Set the SMTP server to the server that sends out emails for your deployment. Typically this is the same as the SMTP eturn Path Hostname. You can also set the SMTP Port, SMTP Auth User, SMTP Auth Password and whether SSL should be used. For typical deployments, port 25 is fine, but for some home developer systems, you may find 587 works for you to bypass ISP firewalls. For a typical deployment where relaying is allowed only from the localhost, you may not need to set the Auth User, Password or SSL options.

• Set the IMAP Server to the server that will handle inbound emails, such as bounces and replies. This most certainly is the same value as the SMTP ReturnPath Hostname. The IMAP Port of 143 is standard. You will want to set the IMAP User and Password to be used to retrieve emails. We typically create a user account for each deployment, so in the example above, we'd have a user account 'deploy2' created. Note that this user account is only used for receiving email, and we do not allow it to be accessed from the Internet for login purposes. We recommend using SSH with a setting that restricts user login accounts, and if possible, do as we do and prohibit 'root' login and only allow logins via public key authorization so password guessing cannot be used to hack your system.

• In our deployments, we use Postfix for SMTP, configured to allow only the localhost server to send out messages (external systems cannot relay through it). We then set the /etc/postfix/virtual_alias to use values like /^deploy2_.*@open.esignforms.com$/ deploy2 This basically will match that return path value and assign it to the right user account that we'll access via IMAP for correlating bounces and replies.

• In our deployments, we use dovecot for our IMAP server.

Other tools

We also are making use of FindBugs. They have an Eclipse update site http://findbugs.cs.umd.edu/eclipse that you can use to add it to your Eclipse.

While not needed for this particular effort, we recommend PasswordSafe (sourceforge) or something similar so you can remember one great pass phrase and keep your various other passwords unique, so when your bank or the like is hacked, at least the password is not used in other sites that become vulnerable as a result.

We also like OpenOffice for our office productivity.

For Windows, we use WinSCP and Putty for SSH/SCP access to our Linux servers.

Linux setup

For Linux deployment servers, we use a layout like this in the home directory for the application. For scripts and such, you may want to run dos2unix on them.

• ~/bashrc and profile are here; tweak as necessary for your setup.
• ~/bin contains our shell scripts
• ~/deployments contains the template folder hierarchy and is used to store the PostgreSQL database per web app deployment (via PostgreSQL's tablespace directive).
• ~/java is where we install our Java 6 Runtime Environment, such as jre1.6.0_26, and we create a softlink of that to 'jdk1.6' which is referenced in the profile. This allows updates to Java by changing where the softlink points. (i.e. ln -s jre1.6.0_26 jdk1.6)
• ~/postgresql contains the location where PostgreSQL is installed. It has folders like bin, data84 (where the main db is stored, but each web app's tablespace puts those databases in the deployments folder), ddl, logs, pg84 (where PostgreSQL installs to) and postgresql-8.4.8 (were we unzipped PostgreSQL and compiled it).
• ~/tomcat where we unzipped Tomcat into a folder like apache-tomcat-7.0.20, and then we create a softlink from that version to tomcat7.0 which is referenced in the profile script. (i.e. ln -s apache-tomcat-7.0.20 tomcat7.0)
• ~/wkhtmltopdf_0.11.0 which contains the code to generate PDFs from HTML. We then create a softlink of the executable to our bin with something like ln -s ../wkhtmltopdf_0.11.0/wkhtmltopdf-i386 wkhtmltopdf-i386 (run from the bin directory).

Mapping code from the Eclipse project to Linux paths

• From ECLIPSEPROJECTNAME/database/postgresql, we put 'ddl' in ~postgresql and run dos2unix on them.
• From ECLIPSEPROJECTNAME/database, we put 'deployments' in ~.
• From ECLIPSEPROJECTNAME/scripts, we put all files in ~/bin and run dos2unix on them. You can put them in a 'scripts' folder, too, but just remember to add that directory to your PATH. You can delete the *.cygwin files. You may want to do a chmod +x ~/bin/* if the scripts don't seem to have execute permission.
• From ECLIPSEPROJECTNAME/WebContent, we put all files in ~/tomcat/tomcat7.0/webapps/WEBAPPNAME where WEBAPPNAME is what you are calling your deployment.