In this blog, I describe how to install Ace Operator V.2. The blog will take you though the steps of preparation, software download, building from the sources and installing the software. Please read the blog fully to avoid surprises in the middle of the installation process .
Installation of Ace Operator V.2 is a snap compared to Ace Operator V.1. There is no longer a need to follow a hundred step process like before but it is still not a breeze given the nature of the product. Since Ace Operator is a software suite that (potentially) faces the Internet, you do need to have a bit of networking, software administration and security experience to manage the service. If you don’t have the experience, get help from someone who does.
Ace Operator V.2 runs on any platform that Supports Java 1.6 Standard Edition and MySQL 5.x+ Standard Edition or above. We have tested the software on Microsoft Window 7 and Linux platforms. We use Linux in our hosted environment and would recommend it for an Internet-facing production environment.
Install Prerequisite Software and Services
There are a few pieces of software and services you need to download and install before installing Ace Operator. They are:
- Java SE Software Development Kit 1.6: Make sure that you download the SDK and not the JRE. Install the software using the instructions provided for your platform.
- MySQL 5.x Standard Edition: Download and install the software as per the instructions provided for your platform. Make sure that MySQL is installed as a service and it starts up when the system is started.
- Apache Tomcat 7.x or above: Download and install the software as per the instructions provided for your platform. Make sure that Tomcat is installed as a service and it starts up when the system is started. If you are using Linux, we have provided a System V service script that you can use for this purpose.
- Mail Server: You need access to an SMTP (outgoing mail) server. You need all the information about the server including the server host name, port, user name, password, SSL information, etc.
- SSL Certificate for Tomcat: Since Ace Operator uses SSL, you will need a SSL certificate. You can find out more about how to install SSL certificate for Tomcat here. In a production environment, you will need a certificate from a trusted authority so that the users do not get a warning when connecting to your service. In our hosted environment, we use a certificate issued by godaddy.com.
Secure Your System
If you are going to use Ace Operator on the Internet, you have to make sure that your server is secure and is not prone to cyber attacks.Talk to a someone with the knowledge of Internet Security if you do not understand this topic well. Here are a few things that you must do to secure the server.
- Make sure that the operating system has all the latest and greatest security patches installed.
- Install a firewall that blocks all incoming IP port connections except ports TCP/8080 and TCP/8443. If you are using Linux, we have provided a IP tables script in the source distribution that you can use. In our hosted environment, we also forward ports TCP/80 and TCP/443 to ports TCP/8080 and TCP/8443 respectively.
- Secure your system’s super-user or administrator accounts by setting a strong, but easy to remember, password.
- Secure your MySQL root account by setting a strong, but easy to remember, password.
- Secure your Tomcat admin account by setting a strong, but easy to remember, password. In our hosted environment, we uninstalled the Tomcat Administration and ROOT web applications to avoid any unauthorized administrator-level access.
- If the SMTP server you are using is located outside the system where you want to install Ace Operator, make sure that outgoing connections to the SMTP host/port is not blocked.
- Make sure that files and directories installed as a part of Ace Operator cannot be accessed by other uses of the system.
Build and Install Ace Operator
At this point of the installation process, you have multiple options. If you are the Java techie type and want to get the latest Ace Operator, you can download the source code from the Ace Operator Subversion Repository. If you are not interested in mucking with the source and start using the software right away, you can download the binary package from the Ace Operator Download Site. If you downloaded the binary distribution, skip the Building from the Sources section.
Building from the Sources
If you want to create the binaries from the sources, you need the following additional tools:
- A Subversion client: You can use either TortoiseSVN, Command-line SVN, Subclipse, etc.
- Maven 2: Make sure you download Maven version 2 or above.
The Build Process
Follow the steps below:
- You can checkout the bleeding-edge snapshot version from https://aceoperator.svn.sourceforge.net/svnroot/aceoperator/trunk or better, checkout a stable release from https://aceoperator.svn.sourceforge.net/svnroot/aceoperator/labels/releases into your local workspace. Make sure that you checking out a release that starts with a 2, example – 2.0.0. Alternatively, you can download the source distribution from the Ace Operator Download Site if you don’t want to mess with Subversion.
- To build from the sources, run the following commands or equivalent (depending on the command line shell you are using):
>> cd ace # location where you checked out Ace Operator
>> mvn install # Make sure that maven bin directory is in your PATH.
Maven will churn for a few minutes downloading dependencies from the Maven repositories from the Internet and then compile the sources, create packages and assemble the distribution. The whole process must complete without errors. When completed, you will find the binary packages in the ace/target directory. You will find that the build has created two packages, one in zip format and another in tar.gz format. The format of the file names are ace-VERSION-bin.zip and ace-VERSION-bin.tar.gz respectively. Select one of these files depending on the availability of a suitable unzip tool for your platform. Note that you can download these binary files directly from the Ace Operator Download Site.
Install Ace Operator
Follow the steps below:
- In a Linux/Unix environment, create an user called tomcat and a group called tomcat. On Windows environment, create an administrator user called “tomcat“.
- Login to the tomcat account you just created.
- Make sure that the Java JDK/JRE bin directory is in the execution PATH.
- Unzip the binary package that you downloaded or built from sources. You can use GNU tar/gzip to extract the tar.gz archive. On Windows, you can use the Windows unzip utility to unzip the zip file or use 7Zip, a free tool, to extract the zip or tar.gz archives. The unzip process will create a directory of the format ace-VERSION and extract the content into this directory.
- Copy the .ace directory (note the dot prefix) under the extracted package to the tomcat user’s home directory. In Linux, the home directory is /home/tomcat and on Windows 7, the home directory is C:\Users\tomcat.
- Make sure that the MySQL server is running.
- Change directory to the installer directory located under the extracted package and run the installer using the command ./postinstall or .\postinstall.bat depending on whether you are using Linux or Windows. Follow the instructions. on the screen. The system will prompt you for database user and SMTP information among other things. You will also need to provide the MySQL root password. The system will create a database user called ace and two databases, ace and webtalk and create default configuration files at the end of this step.
- Copy all the files and directories under the web directory located under the extracted package into the Tomcat installation’s webapp directory.
- Make sure that the Tomcat is setup to accept HTTPS (TLS). Also, make sure that Tomcat installer is owned by the tomcat user you created above and is started and stopped by the Tomcat user. In addition, make sure that you have allocated enough virtual memory to run Ace Operator. We use the environment variable, JAVA_OPTS=”-Xms256m -Xmx512m -Djava.awt.headless=true -Dfile.encoding=UTF8″. We have included a Tomcat Unix SYSV startup script located under the bin folder of the extracted binary package. You can modify and use the script if you want.
- Start Tomcat.
- Bring up a browser and point to http://SERVER:8080/ace-contactcenter. You should see a screen if the installation has been successful.
Testing the Basic Setup
The next step is to verify that the installation has been successful. In order to verify, execute the following steps:
- Bring up a browser and point to http://SERVER:8080/ace-communicator and login using the credentials ace/a1b2c3d4.
- On the main screen, click on the Talk Application link. On the Talk Application screen, click on the User->Administer link.
- Create an operator user by entering the user name, password, full name and email. Make sure that you select operator group from the Is a Member of Groups list. The other information does not need to be entered at this point.
- Bring up a browser and point to http://SERVER:8080/ace-contactcenter.
- From the form, populate the profile field with the value, default-operator and click on the Connect button. A new page is popped up. Login as an operator using the credentials of the operator user you just created. Stay logged in for the next step.
- To test the visitor access, from the same form, populate the profile field with the value, default-visitor and click on the Connect button. A new page is popped up. Enter the necessary information and verify that a chat session is established between the operator and the visitor.
If all the steps completes successfully, the Ace Operator system is functional- Yeah!!
Troubleshooting the Installation
If the steps above did not complete successfully , there are a few things to verify before asking for help. They are:
- A common problem is that the owner of the Tomcat directory tree is different from the user who started Tomcat. Make sure that your installation does not have this issue.
- The post-installation process described above did not go well because bad credentials were supplied for the MySQL root user. Check if the ace and webtalk database users are created and there are tables in the database. You can rerun the post installation step multiple times to rectify the issues.
- In addition to the Tomcat logs, you can also find more information in the Ace Operator logs located in .ace/log directory under the Tomcat user’s home directory.
- If nothing works, use the forums and mailing lists for Ace Operator to ask for help. You can find more information here.