InstallationUsingVaadin8 (obsolete)

is brought to you by

Basic YozonsESF installation instructions for developers. Updated for Vaadin 8. It is OBSOLETE as of November 2023.

Introduction

For OpenESF releases through 19.3.23, please see the prior installation guide using Vaadin 7. This guide is for YozonsESF releases starting with 19.5.11 through 23.12.15.

For YozonsESF releases after 23.12.15, please see the newer installation guide using Vaadin 8 on Amazon Linux 2023.

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 commercially licensed and supported solutions. Yozons also offers private web servers for those who want their own domain name (and SSL cert), but don't want to install, update, operate and manage their own server.

Details

Java 8 development and OpenJDK 14 runtime

Currently, the software is compiled targeting Java 8, but we use the OpenJDK 14 (and later) runtime for deployments.

We start by installing the latest version of Java 8 SE or OpenJDK 14 available. OpenJDK 14 is now supported for runtime as well, but is not yet used for development.

If using Java 8, 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, or if you run Tomcat directly yourself. You can download these files from the Java download site (often at the bottom of the page). The JCE policy files are no longer used if running on Java 9 or later.

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 RIA/Web 2.0 interface, a modern browser is best and fastest. Note that mobile browsers work fine processing your documents. Note that IE 8-10 is no longer supported as of Vaadin 8.

Apache Tomcat

For testing, we generally run Tomcat from Eclipse, so it's best to download and install Tomcat next. The version tested here was 9.0.16.

On Tomcat version upgrades, we basically make the following changes on Linux:

• profile - configure the following (only include the debug info if you remotely debug your Tomcat, and your memory values will need to match your server):

CATALINA_HOME=~/tomcat/tomcat9.0
CATALINA_OPTS="-server -Xms500m -Xmx500m -Desf.deploybase=$ESF_DEPLOYMENT_BASE"
export CATALINA_HOME CATALINA_OPTS

• webapps - Move all webapps except perhaps 'manager' up a subdirectory so that they are no longer deployed. Obviously, we put the Yozons eSignForms webapp here. You can just move them from the prior Tomcat webapps location.

  mkdir ../ORIG-webapps
  mv docs examples host-manager ROOT ../ORIG-webapps

• webapps/manager/WEB-INF/web.xml - If you use the manager webapp, add the following snippet to the <security-constraint> of the 'HTML Manager interface' and 'Status interface' to ensure it only works over SSL-protected connections.

    <user-data-constraint>
          <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>

• webapps/manager/META-INF/context.xml - If you access the manager webapp across the Internet (normal), comment out or remove the <Valve className="org.apache.catalina.valves.RemoteAddrValve">.../> or update the allow attribute to include the IP address you'll access from.
• conf/tomcat-users.xml - If you use the Tomcat manager webapp, set up the username and password to use when accessing the manager of your webapps:

  <role rolename="manager-gui"/>
  <user username="admin" password="PUT-SECURE-PASSWORD-HERE" roles="manager-gui"/>

• conf/server.xml - You can set up as you need, such as if you have an Apache HTTPD server front-end and use the APR, but for a simple stand-alone Tomcat, we make the following changes. Under the "Catalina" <Service> entry (of course, if you have SSL, you want to point to your keystore and its password). We also comment our the AJP Connector on port 8009, but you may need it if you put HTTP in front:

    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000" acceptorThreadCount="2" URIEncoding="UTF-8" redirectPort="443" />

    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true" maxThreads="200"
               connectionTimeout="20000" acceptorThreadCount="2" URIEncoding="UTF-8" maxPostSize="10485760"
               compression="on" compressibleMimeType="text/html,text/css,text/xml,text/plain,application/xml,application/json,application/javascript,application/pdf">
        <SSLHostConfig certificateVerification="none" protocols="TLSv1.2,TLSv1.3" honorCipherOrder="true"
                       ciphers="TLS_AES_128_GCM_SHA256,
TLS_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256">
            <Certificate certificateKeystoreFile="keys/mytomcatkeystore" certificateKeystorePassword="PUT-KEYSTORE-PASSWORD-HERE" type="RSA" />
        </SSLHostConfig>
    </Connector>

<!--
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
-->

• If your esign server will accept large API requests to submit data, generally this only occurs if receiving big files as named params, you can increase Tomcat's ability to process them by adding the following option to your Connector:
  maxPostSize="10485760"
  The Tomcat default is 2MB, and this will increase it to 10MB. You generally only need this on your HTTPS Connector.

• conf/server.xml - We also change the <Host> entry to turn off auto deploy:

      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="false">

• keys - We put our Tomcat SSL certificate and keys in this folder. When upgrading, be sure to copy over this folder that matches the location of specified in the SSL Connector's SSLHostConfig element's attribute 'certificateKeystoreFile' in server.xml.

Tomcat's Java Keystore for HTTPS/SSL

You are free to setup Tomcat's keystore for HTTPS/SSL using any standard scheme. But here are a few key commands you that will get this going if you are not familiar with the procedure.

1. Create the Java keystore that Tomcat will use to control SSL. In this case, the keystore file name is 'tomcatkeys'. You must use the alias name 'tomcat'.: keytool -genkeypair -keyalg RSA -keysize 2048 -alias tomcat -keystore tomcatkeys When prompted, you first enter the web site domain name, such as esign.example.com along with the other information requested. Choose a good password for the keystore, and then set the keystore file name and password in the Tomcat's conf/server.xml.
2. Generate the CSR to request your SSL certificate from your favorite CA: keytool -certreq -alias tomcat -keyalg RSA -file certreq.csr -keystore tomcatkeys You can then submit the contents of certreq.csr when ordering your SSL certificate.
3. Once your CA has issued your certificate, install it into the keystore: keytool -import -alias tomcat -trustcacerts -file YOURCERT.crt -keystore tomcatkeys
4. Restart Tomcat after you have updated Tomcat's conf/server.xml for the HTTPS connector's keystore and password.

Eclipse

Install the latest version of Eclipse IDE for Java EE developers. The version tested here is 2019-03 (4.11.0).

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 v9.0 Server, click Next and choose the location where you installed Tomcat (i.e. something like C:\apache-tomcat-9.0.16). Double-click your server (named Tomcat v9.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 (/Yozons-eSignFormsVaadin8 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 Yozons eSignForms Using Eclipse

Create the Vaadin Eclipse project by downloading the code from CVS, project Yozons-eSignFormsVaadin8.

Passwords

The standard JAR Yozons 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.

yozonsesignforms.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

log4j.properties - Be sure to fix up the location where to store the log files for your deployment, such as log4j.appender.ROOTLOG.File=${esf.deploybase}/deployid/archive/logs/esf.log

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 12 per its usual mechanisms. The version tested here was 12.2.

It's just a convention, but we use the DB role 'esignforms' for our admin account, and each 'deployment' (a customer system that has its own webapp and database on the server) uses a roughly 5 character unique name (longer/shorter deployids can be used) that is used as that application's DB role/user. The name is also the base name in the deployment folder for its database tables, log files, etc. Its base directory is set in 'profile' environment variable ESF_DEPLOYMENT_BASE.

Create the deployment folder in the home directory (/home/esignforms/deployments) or C:\deployments.

Update the ~/profile to point to the locations where all your stuff is. You can test with java -version and psql template1 to see that Java and Postgresql are setup correctly.

Create the database

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

Note that the profile script sets ESF_DEPLOYMENT_BASE to the base directory where your deployment databases (PostgreSQL tablespaces) are independently stored. On Windows, we may use C:\deployments and on Linux something like /home/esignforms/deployments. The 'templates' folder should be created in the deployment folder automatically once you run the create_db script.

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

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

    (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) 2019 Yozons, Inc.
DbSetup - Sets up the database for Yozons eSignForms vX.X.X

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@yozonsesfdemo.com
Enter super user's first/personal name [Yozons] : Super
Enter super user's last/family name [Support] : YozonsESF
Initial super user password: Test
insertSuperUser - Added new super user: super@yozonsesfdemo.com
insertUserIntoSuperGroup - Added new super user: Super YozonsESF <super@yozonsesfdemo.com>; to super group: ESF/Group/Deployment/SuperAdmin

Enter setup command (initdb,addsuperuser,initsetup,setpassword,quit,convertX.X) [quit] : initsetup
Enter Commercial DB license size in MB [70]:
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@example.com
Enter programmer user's email address [open-esign@yozons.com] : myprogrammer@yozonsesfdemo.com
Created company group: com.esignforms.yozons.user.Group@a1c6407f
Created company programming group: com.esignforms.yozons.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: Yozons eSignForms Programming <myprogrammer@yozonsesfdemo.com>

Enter setup command (initdb,addsuperuser,initsetup,setpassword,quit,convertX.X) [quit] : quit

NOTE: Be sure to update the MyCompany property set to have more appropriate values. These are configured in libraries ESF/Template/Library as well as the library setup for your branded transaction workflows.

Running the Application in Eclipse

Generally for testing in Eclipse, click Debug As->Debug On Server->Apache->Tomcat v9.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 Yozons eSignForms, but must be available. Yozons 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 Yozons 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 technically the IMAP user name (normalized to lowercase and replacing any non-alphanumeric, other than period, underscore or hyphen, by '_'), but we mirror it to also be 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. Typical settings changes we make to the /etc/postfix/main.cf is (the domain is your server's name):

mydomain = example.com
home_mailbox = Maildir/
inet_interfaces = all
mynetworks_style = host
virtual_alias_maps = regexp:/etc/postfix/virtual_alias

• In our deployments, we use dovecot for our IMAP server. With CentOS 6, we seem to need to add the following to /etc/dovecot/dovecot.conf file:

mail_location = maildir:~/Maildir
mail_access_groups=mail

Setting up Postfix for TLS

Generate the PEM file for postfix TLS (as root):

cd /etc/pki/tls/certs
make postfix.pem
mv postfix.pem /etc/postfix

And update the /etc/postfix/main.cf file to includes the following setup, which still allows non-TLS connections for:

smtp_tls_loglevel = 1
smtp_tls_received_header = yes
smtp_tls_security_level = may
smtp_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1
smtp_tls_protocols = !SSLv2, !SSLv3, !TLSv1
smtp_tls_mandatory_ciphers = high
smtp_tls_ciphers = high
smtp_tls_mandatory_exclude_ciphers = aNULL, MD5, DES, RC4, 3DES, eNULL
smtp_tls_exclude_ciphers = aNULL, MD5, DES, RC4, 3DES, eNULL
smtp_tls_cert_file = /etc/postfix/postfix.pem
smtp_tls_key_file = $smtp_tls_cert_file

smtpd_tls_loglevel = 1
smtpd_tls_received_header = yes
smtpd_tls_security_level = may
smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1
smtpd_tls_protocols = !SSLv2, !SSLv3, !TLSv1
smtpd_tls_cert_file = /etc/postfix/postfix.pem
smtpd_tls_key_file = $smtpd_tls_cert_file
smtpd_tls_mandatory_ciphers = high
smtpd_tls_ciphers = high
smtpd_tls_mandatory_exclude_ciphers = aNULL, MD5, DES, RC4, 3DES, eNULL
smtpd_tls_exclude_ciphers = aNULL, MD5, DES, RC4, 3DES, eNULL

To allow port 587 (smtp-submission), update the /etc/postfix/master.cf file to uncomment the line:

submission inet n       -       n       -       -       smtpd

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. We also make use of OWASP LAPSE.

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 LibreOffice or OpenOffice to replace any need for Microsoft Office.

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.

• ~/bashrc and profile are here; tweak as necessary for your setup.
• ~/bin contains our shell scripts. Add wherever you install these to your .bash_profile PATH.
• ~/deployments contains the template folder hierarchy and is used to store the PostgreSQL database per web app deployment (via PostgreSQL's tablespace directive). This folder is set as the ESF_DEPLOYMENT_BASE environment variable setup in the 'profile' file. Permissions on this folder and all subfolders is typically 075.
• ~/java is where we install our OpenJDK 14 (still runs on Java 8 Runtime Environment), and we create a softlink of that to 'jdk14' which is referenced in the profile. This allows updates to Java by changing where the softlink points. (i.e. ln -s jdk-14 jdk14)
• ~/postgresql contains the location where PostgreSQL is installed. It has folders like bin, data11 (where the main db is stored, but each web app's tablespace puts those databases in the deployments folder), ddl, logs, pg11 (where PostgreSQL installs to) and postgresql-12.2 (were we unzipped PostgreSQL and compiled it).
• ~/tomcat where we unzipped Tomcat into a folder like apache-tomcat-9.0.16, and then we create a softlink from that version to tomcat9.0 which is referenced in the profile script. (i.e. ln -s apache-tomcat-9.0.35 tomcat9.0). The 'profile' script also sets Tomcat's CATALINA_OPTS variable used when starting Java for Tomcat.
• ~/wkhtmltox-0.12.6 which contains the code to [wkhtmltopdf generate PDFs from HTML]. We then create a softlink of the executable to our bin with something like ln -s ../wkhtmltox-0.12.6/usr/local/bin/wkhtmltopdf wkhtmltopdf (command run from the bin directory). If you use the RPM installs, you should be good to go as long as /usr/local/bin is in your PATH.
• After you update your profile and the rest, be sure to include . profile in your .bash_profile and . bashrc in your .bash_rc file (or put both dot commands in your .bash_profile like we generally do), and if not already done, ensure that your '~/bin' is in your PATH, so .bash_profile looks something like:

  PATH=$PATH:$HOME/bin
  export PATH
  . ~/profile
  . ~/bashrc
  

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/tomcat9.0/webapps/WEBAPPNAME where WEBAPPNAME is what you are calling your deployment.

General Linux X64 server setup information

As root do the following on your new Linux instance:

• useradd esignforms (assuming you install the code under this username)
• passwd root (be sure to set good passwords)
• passwd esignforms (be sure to set good passwords)
• yum update (to ensure you are up-to-date with everything)
• yum install iptables chrony logwatch dos2unix gpg bind-utils telnet traceroute make gcc libgcc gcc-c++ glibc-devel readline readline-devel ncurses ncurses-devel zlib zlib-devel zip unzip bzip2 pam pam-devel postfix lynx dovecot rsync
• For CentOS7 and later: yum install firewalld
• See the wkhtmltopdf wiki for other components you need.
• Put ALL: ALL in /etc/hosts.deny
• Put sshd: ALL in /etc/hosts.allow
• Ensure you /etc/hosts file is correct with your hostname and IP address.
• hostname esign.example.com
• Set up for you timezone, i.e. rm -f /etc/localtime and then ln -s /usr/share/zoneinfo/America/Los_Angeles /etc/localtime
• Set ZONE="America/Los_Angeles" and UTC=true in /etc/sysconfig/clock
• Set HOSTNAME=esign.example.com in /etc/sysconfig/network. On CentOS 7 and later, put the hostname in the /etc/hostname file instead.
• Ensure your /etc/resolv.conf is set up for the name servers you can use to resolve external host names.
• Create Yozons-specific /usr/local/bin/sp script wrapper for ps (chmod 755).
• Create Yozons-specific /etc/esfprofile script for offsite backups. chmod 640 and chown root.esignforms
• Change /etc/ssh/sshd_config to use:
  • PermitRootLogin no
  • PasswordAuthentication no
  • AllowUsers esignforms

As esignforms do:

• mkdir .ssh
• chmod 700 .ssh
• cd .ssh
• Install your authorized_keys file so you can SSH in
• chmod 600 authorized_keys
• For compiling PostgreSQL, we use this configure commands:

    cd ~/postgresql/postgresql-12.2
    ./configure --prefix=/home/esignforms/postgresql/pg12 --with-pam
    gmake
    gmake install
    cd contrib/vacuumlo
    gmake
    cp -p vacuumlo ../../../bin/
    cd ../pg_standby
    gmake
    cp -p pg_standby ../../../bin/
    cd ~/postgresql
    initdb -D $PGDATA
    yostart db
    psql template1
       ALTER ROLE esignforms WITH PASSWORD 'DB-ADMIN-PASSWORD-HERE';
    yostop db    

• Allow for local access to all databases (for multiple deployments) by updating data12/pg_hba.conf:

    local all all md5
    host all all 127.0.0.1/32 md5

• A few tweaks to data11/postgresql.conf for basic operation:

    logging_collector = on
    log_directory = '../logs'
    log_line_prefix = '%m %d [%p] '
    log_connections = on
    log_disconnections = on

Restart PG: `yostart db`

As root again do:

• service sshd restart On CentOS 7 and later, systemctl restart sshd
• service chronyd start On CentOS 7 and later, systemctl start chronyd
• chkconfig chronyd on On CentOS 7 and later, systemctl enable chronyd
• Setup /etc/sysconfig/iptables something like:

# We do simple NAT here to map HTTP/HTTPS to the safer unprivileged ports Tomcat listens on.
*nat
:PREROUTING ACCEPT [0:0]
:POSTROUTING ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]
-A PREROUTING -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 8443
-A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 8080
# causes outbound connections on my public IP to also redirect like above
-A OUTPUT -p tcp -m tcp -d esign.example.com --dport 443 -j REDIRECT --to-ports 8443
-A OUTPUT -p tcp -m tcp -d esign.example.com --dport 80 -j REDIRECT --to-ports 8080
COMMIT
*filter
:INPUT ACCEPT [0:0]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]
:RH-Firewall-1-INPUT - [0:0]
-A INPUT -j RH-Firewall-1-INPUT
-A FORWARD -j RH-Firewall-1-INPUT
-A RH-Firewall-1-INPUT -i lo -j ACCEPT
-A RH-Firewall-1-INPUT -p icmp --icmp-type any -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 25 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 587 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp -s localhost.localdomain -d localhost.localdomain --dport 143 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT
# 9090 is the tomcat debug port
# -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 9090 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 8080 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 8443 -j ACCEPT
-A RH-Firewall-1-INPUT -j REJECT --reject-with icmp-host-prohibited
COMMIT

• Or for CentOS 7 and later that uses firewalld instead of iptables setups, do something like (after entering the commands, you should see these changes reflected in the /etc/firewalld/zones/public.xml file):

firewall-cmd --permanent --zone=public --add-forward-port=port=80:proto=tcp:toport=8080
firewall-cmd --permanent --zone=public --add-forward-port=port=443:proto=tcp:toport=8443

# This command is only needed if outbound connections from the server to the server needs port forwarding to work
firewall-cmd --permanent --direct --add-rule ipv4 nat OUTPUT 0 -p tcp -m tcp -d esign.example.com --dport 443 -j REDIRECT --to-ports 8443

firewall-cmd --remove-service=cockpit --permanent
firewall-cmd --remove-service=dhcpv6-client --permanent

firewall-cmd --permanent --zone=public --add-service=http --permanent
firewall-cmd --permanent --zone=public --add-service=https --permanent
firewall-cmd --permanent --zone=public --add-service=smtp --permanent
firewall-cmd --permanent --zone=public --add-service=smtp-submission --permanent

firewall-cmd --permanent --list-all --zone=public
firewall-cmd --reload
systemctl status firewalld

• Make changes to /etc/postfix/main.cf as above.
• Set up /etc/postfix/virtual_alias something like with the first being how to map individual deployments (named 'demo' in this example) as well as creating forwarding rules for the esignforms, postmaster and root users:

/^demo_.*@esign.example.com$/ demo
/^esignforms@esign.example.com$/ support@example.com
/^postmaster@esign.example.com$/ support@example.com
/^root@esign.example.com$/ support@example.com

• Add MailTo = support@example.com to /etc/logwatch/conf/logwatch.conf
• service postfix start
• chkconfig postfix on
• service dovecot start
• chkconfig dovecot on
• Here is a sample init script for auto-starting/stopping the application on boot and shutdown (so you can use service esignforms start and service esignforms stop for example). The latest Red Hat and CentOS has programs named start and stop so our start/stop scripts are often renamed to yostart and yostop along with similar changes in their contents in the bin subdirectory:

#!/bin/bash
#
# Copyright (c) 2012 Yozons Inc.  All rights reserved worldwide.
#
# Start in runlevels 3, 4, 5, with start at the end and stop at the beginning
# chkconfig: 345 99 3
# description: Init file for Yozons Open eSignForms web applications
#
INITFILE=/etc/rc.d/init.d/esignforms
LOCK=/var/lock/subsys/esignforms

# source in the function library
. /etc/rc.d/init.d/functions

start()
{
        echo -n "Starting Open eSignForms:"
        su - esignforms -c "bin/yostart all" && success || failure
        RETVAL=$?
        [ "$RETVAL" = 0 ] && touch $LOCK
        echo
}

stop()
{
        echo -n "Stopping Open eSignForms:"
        su - esignforms -c "bin/yostop all"
        RETVAL=$?
        [ "$RETVAL" = 0 ] && rm -f $LOCK
        echo
}

case "$1" in
        start)
                start
                ;;
        stop)
                stop
                ;;
        restart)
                stop
                sleep 5
                start
                ;;
        status)
                        echo Status of chronyd:
                /usr/local/bin/sp chronyd
                chronyc sources -v
                        echo Status of sshd:
                /usr/local/bin/sp sshd
                        echo Status of postfix SMTP:
                /usr/local/bin/sp postfix
                        echo Status of dovecot IMAP:
                /usr/local/bin/sp dovecot
                echo
                su - esignforms -c "bin/checkall"
                RETVAL=$?
                ;;
        install)
                echo Adding esignforms to runlevel system for auto start and stop
                cp $0 $INITFILE
                chmod 755 $INITFILE
                /sbin/chkconfig --add esignforms
                ;;
        uninstall)
                echo Removing esignforms from runlevel system for auto start and stop
                /sbin/chkconfig --del esignforms
                rm -f $INITFILE
                ;;
        *)
                echo $"Usage: $0 {start|stop|restart|status|install|uninstall}"
                RETVAL=1
esac
exit $RETVAL

• For CentOS 7 and later that don't use init scripts, you can put the above script in /usr/local/bin and use the following systemctl configuration file in /usr/lib/systemd/system/esignforms.service and then issue the command systemctl enable esignforms so it runs the script's 'start' and 'stop' options (or manually you can run systemctl start esignforms and systemctl stop esignforms:

[Unit]
Description=Yozons eSignForms
After=syslog.target network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/esignforms start
ExecStop=/usr/local/bin/esignforms stop
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

IPv6 use

We have little IPv6 expertise, but you may consider the following changes if you do not want IPv6 connections on your server if IPv6 is otherwise configured. The application has no specific knowledge of IPv6, but our testing on Mac OSX suggests it works fine.

• Add to /etc/sysctl.conf:

net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1

• For a running system:

sysctl -w net.ipv6.conf.all.disable_ipv6=1
sysctl -w net.ipv6.conf.default.disable_ipv6=1

• Change /etc/sysconfig/network: NETWORKING_IPV6=no
• You may want to turn it off for Postfix, too, in /etc/postfix/main.cf: inet_protocols=ipv4

Other considerations

If your installation reports errors like the following:

su: PAM adding faulty module: /lib64/security/pam_fprintd.so
su: PAM unable to dlopen(/lib64/security/pam_fprintd.so): /lib64/security/pam_fprintd.so: cannot open shared object file: No such file or directory

You may want to run the command to suppress them: authconfig --disablefingerprint --update

CentOS 7 and later Differences

These are just some tech notes for using CentOS 7 or later over CentOS 6.

Most 'service' commands, like 'service iptables restart', now use systemctl:

systemctl start chronyd
systemctl stop chronyd
systemctl status chronyd
systemctl restart chronyd

To make a system service permanent, instead of chkconfig, use:

systemctl enable chronyd
systemctl disable chronyd
systemctl is-enabled chronyd  (check if so)

To list all services, use: systemctl list-unit-files

---

Fonts configs moved locations from /etc/fonts/conf.avail to /usr/share/fontconfig/conf.avail

and to install them create the softlink (ln -s) from the above conf.avail in /etc/fonts/conf.d

---

Timezone setting:

timedatectl set-timezone America/Chicago
hwclock --systohc

No longer ifup/ifdown for network interface:

nmcli c up ifname $interface

List all network interfaces:

ip addr

List all IPv4:

ip -f inet addr

List all IPv6

ip -f inet6 addr

Upgrading to new releases

In general, all new release need the following pattern of updates from the release code to the corresponding deployment location.

• From your deployment area, remove/clear all files in the VAADIN folder so you get the latest themes and GWT code. Also, you may want to do the same for all prior JAR files in WEB-INF/lib. And if you have any patched code in WEB-INF/classes (besides the standard .properties files), you should remove any .class files you have there.
• All files from the WebContent folder in the code to the webapp folder where you have deployed the application. The only exceptions in general is WebContent/WEB-INF/web.xml, though you may need to refer to it when it changes so you can sync yours to it.
• Normally, the web.xml file does not change, but some major changes like the upgrade from Vaadin 6 to Vaadin 7 required a new web.xml file. In this case, it's a good idea to compare the two files and be sure to synchronized them. Typically, any given deployment can use the web.xml as is, but you may have tweaked the following elements <display-name>; <description>; in production you may have set <context-param> productionMode to true; <session-timeout>; and perhaps the <security-constraint> if on a non-SSL protected test server.
• Assuming you removed the WEB-INF/lib/Yozons-eSignFormsVaadin8-*.jar for the prior version, be sure to copy over the version from the lib folder of the project area.
• As always, you may need to run SQL updates and 'rundbsetup' as described in the wiki [DatabaseUpdatesForNewReleases DatabaseUpdatesForNewReleases]. You can review the scripts/createRelease and 'scripts/installRelease' for other details.