{{tag>Manuals Installation_Guide}}
[<10>]
====== Aware IM deployment options ======

When you install //**Aware IM**// out-of-the-box as described in sections [[docs:1100_inst_guide:0100_windows]], [[docs:1100_inst_guide:0200_linux]] or [[docs:1100_inst_guide:0300_macos]] //**Aware IM**// is installed on a single machine. This is, however, not the only option of //**Aware IM**// deployment. //**Aware IM**// is a Client-Server system. From the deployment point of view it has 3 components that can be installed on the same or different computers. These components are:

  * The Aware IM server
  * The Aware IM Configuration Tool
  * The Aware IM web application managed by Tomcat


As mentioned above all the components may reside on the same computer – this is the default deployment configuration that you get when you use the default //**Aware IM**// installation. This option is suitable for the following categories of users:

  * Individual end users who run information systems configured with the //**Aware IM**// software for personal needs
  * Configurators who configure and test their //**Aware IM**// information systems on a single machine
  * Small to medium companies that run their information management systems configured with //**Aware IM**// for their internal office needs
  * Small to medium companies that run their information management systems configured with //**Aware IM**// for their internal office needs and/or provide access to these systems to their customers via Internet where the load of the server running //**Aware IM**// system is low to medium.



For larger companies who have more internal and external users with higher load of requests it may be beneficial to deploy //**Aware IM**// on separate computers for better scaling and performance. 

It is also possible that individual users or companies do not have direct access to the computer where //**Aware IM**// is running – for example, if they use 3<sup>rd</sup> party organizations to host their web needs (including //**Aware IM**//). These individuals and organizations however may need frequent and easy access to the Configuration Tool so that they can configure or modify their information systems whenever necessary.



//**Aware IM**// can be deployed to meet these needs. The following deployment options are available:

  - The Aware IM web application (Web Server) can be installed on a separate machine(s), which allows for better scaling and performance under heavy load.
  - The Aware IM Configuration Tool can be deployed on a separate machine with access to the Aware IM server via internal LAN. This makes it possible to use the Configuration Tool by different users simultaneously.
  - //**Aware IM**// server can be deployed on a remote machine. Configurators can upload applications from their local machines to the //**Aware IM**// server via the Web browser. Thus this option allows running //**Aware IM**// on a remote machine in a host environment and at the same time easily configuring and changing applications.



The required steps for each of these options are described below.

===== Running Aware IM Web Server on a separate machine =====

To run //**Aware IM**// web application on a separate machine within a single LAN you have to make sure that the //**Aware IM**// server is deployed on your “server” machine(s) whereas //**Aware IM**// web application is deployed on a single or a cluster of “web server” machines. 



Make sure you do the following:

  - To deploy the //**Aware IM**// server on the “server” machine do the following:
    - Make sure that the machine has the database engine of your choice installed (alternatively the database server may be deployed on yet another machine). 
    - Install //**Aware IM**// on your server machine as described in the previous sections. 
    - To start the //**Aware IM**// server change to AwareIM/bin directory on your server machine and run the Aware IM Control Panel as described in the previous sections.
  - To deploy the //**Aware IM**// web application on the web server machine(s) do the following:
    - Install //**Aware IM**// on your web server machine as described in the previous section. 
    - Modify the file AwareIMInstallationDirectory/webapps/AwareIM/webapp.props to include the name of your “server” machine in the LAN. For example,\\ \\ <code>ServerName=myAwareIMServerName</code>

===== Running Configuration Tool on a separate machine on a local area network (LAN)  =====

To run the Configuration Tool on a machine different from the one where your //**Aware IM**// server is running do the following (it is assumed that the Configuration Tool and the //**Aware IM**// server are running on the machines connected by a Local Area Network (LAN). We will call the machine where the Configuration Tool is running, the “client” machine and the machine where the //**Aware IM**// server is running – the “server” machine.

  - Install  //**Aware IM**// server on a “server” machine.
  - Replace references to ''localhost'' in the ''BASServer.props'' file located in the BIN directory of the Aware IM installation on the server machine with the network name of the server machine, for example:\\ \\ <code>DirectoryServiceProvider=tcp://localhost:61616
JMS_BROKER_CONNECTOR=tcp://localhost:61616</code>
  - Under the Windows operating system run the Configuration Tool setup program (ConfigTool.exe) located in the Windows directory of your Aware IM distribution disk from the client machine and follow the instructions of the program. You will need to specify the installation directory of the Configuration Tool and the network name of the server machine. After the Configuration Tool has been installed you can run it from the Startup menu.
  - Add the following line to the file ''UIConfig.props'' located in the ''BIN'' directory of the installation performed during the previous step (if the line already exists change it):\\ \\ <code>WebServer = NameOfTheMachineWhereAwareIMServerIsRunning</code>
  - Under Linux operating system perform the following steps:
    - Unpack the archive file with the Configuration Tool component (''ConfigTool.tar.gz'') to some local directory on your client machine (we assume it is called AwareIM). 
    - Modify the file ''AwareIM/ConfigTool/eclipse/ConfigTool.ini'' to add the name and port of your “server” machine in the LAN into the ''–vmargs'' section of the file. For example,\\ \\ <code>-vmargs
-Djasper.reports.compile.class.path=plugins/com.awaresoft.awareim.shared_1.0.0/jasperreports-0.5.0.jar
-Dawaresoft.awareim.configtool.serverName=myserver
-Dawaresoft.awareim.configtool.serverPort=9000</code>
  - To start the Configuration Tool change to the ''AwareIM/ConfigTool/eclipse'' directory on your client machine and run the ''ConfigTool'' program.


<callout type="primary" icon="true" title="note"> If the Aware IM Server is running on the Linux or Mac OS X machine make sure that the file etc/hosts has the following entries:\\ \\ 
<code>
127.0.0.1 localhost.localdomain localhost
x.x.x.x serverName</code>
where x.x.x.x is the IP address of the server where Aware IM is running and serverName is the network name of the server.\\ \\ 
**Additionally if you are running the remote Configuration Tool from a Linux or Mac OS X workstation make sure that the ''etc/hosts'' file of each workstation has the same entries as the ''etc/hosts'' file on the server.**</callout>

===== Running the Configuration Tool Across the Internet =====

To run the Configuration Tool across the Internet where the Configuration Tool connects to a remote server located anywhere in the world perform the following steps:
  - Install  //**Aware IM**// server on a remote machine.
  - Install either the full version of Aware IM or the standalone Configuration Tool on the client machine
  - Modify the ''UIConfig.props'' file located in the ''BIN'' directory and add the following properties (in the example below the URL of the server is assumed to be https://www.myserverver.com:8080/MyWebApp)
<code>HttpServerConnection=true
WebServer=www.myserver.com
WebServerPort=8080
WebServerProtocol=https
WebAppBase=MyWebApp</code>

===== Running Aware IM in a web hosting environment =====

Organizations or individuals who for whatever reason cannot or do not want to run their application on their own server but still want web access to their //**Aware IM**// application can use web-hosting services of third-party companies (that we will call “web hosts” here). These companies offer their servers for companies to deploy their applications/web sites on. 



There are a variety of services that web hosts offer. Usually they fall within one of the 3 categories:

^ ^ Hosting Method^Considerations^
^1. |Standard shared hosting |The server is shared with other users. You do not have control on which software is installed on your server and you cannot reboot the server.|
^2. |Virtual Private Server hosting (VPS)|The server is shared with other users. However, you get your own “virtual” server with a particular operating system (Windows or Linux). You have full control over your virtual server through the remote interface (even though it is physically shared with others) – you can install any application on the server and you can reboot the server any time| 
^3. |Dedicated server hosting|You have your own server that is not shared with other users. You have full control of this server through the remote interface.|


The first option is usually the cheapest, while the third one is the most expensive.

Although it is theoretically possible to run //**Aware IM**// applications under standard shared hosting (option 1.), we do not recommend it as there are too many things that can potentially go wrong



Option 3 is the safest option and is virtually equivalent to running //**Aware IM**// on your own server. The only problem with this option is the price – it can range from 100 to 300 (or more) dollars a month.



Option 2 is, in our opinion, the most practical option for many users. It is relatively inexpensive (you can get VPS hosting for $30 a month or even less) and you essentially get your own server that you have full control of. The next section discusses running //**Aware IM**// applications under the VPS hosting environment.

===== Running Aware IM under the VPS hosting environment =====


Usually VPS hosting comes in two flavours – Linux VPS that uses Linux operating system and Windows VPS that offers Windows operating system. Linux VPS is much more common, however, there are more and more companies who offer Windows VPS hosting. Linux VPS is usually slightly cheaper.


It is possible to run //**Aware IM**// applications under both operating systems. However, please see the following tables for the comparison of using Linux VPS versus Windows VPS:



^ Linux VPS pro’s                                                                                                                                                                                         ^ Linux VPS con’s                                                                                                                                                                                                                                                               ^
| Very common. There are a huge number of companies offering Linux VPS with different options and price range                                                                                             | Most web hosts offer non-graphical Linux. Running //**Aware IM**// under non-graphical Linux has two limitations:\\ \\ It is possible to install the graphical component for Linux, but it requires some Linux expertise (or you can possibly ask the host to do it for you)  |
| Usually cheaper than Windows VPS                                                                                                                                                                        | Usually Linux VPS offers remote access to the Linux server via command line interface only. However, if you install a Linux graphical component it is possible to set up a remote graphical interface to the server                                                           |
^ Windows VPS pro’s                                                                                                                                                                                       ^ Windows VPS con’s                                                                                                                                                                                                                                                             ^
| The experience is literally equivalent to running Aware IM on your own server. You get a remote graphical interface to the server, which is like running Windows on your own machine. Very convenient.  | Slightly more expensive on average than Linux VPS (although, it is now possible to find a very good deal)                                                                                                                                                                     |
|                                                                                                                                                                                                         | Not very common yet. Not many companies offering Windows VPS                                                                                                                                                                                                                  |



Our recommendation is that if you can find a good deal on Windows VPS, go for it – the remote graphical user interface is worth it.



Some of the companies running good deals on Windows and Linux VPS are GoDaddy ([[http://www.godaddy.com/|www.godaddy.com]]), VPS Land ([[http://www.vpsland.com/|www.vpsland.com]]), InfoQuest ([[http://www.infoquest.com/|www.infoquest.com]]) 



Once you have the VPS set up installing Aware IM is quite straightforward – transfer Aware IM installation files to your server and install it there. However, you need to watch out for these two most commonly encountered problems when running //**Aware IM**// in the VPS environment:


  - //Not enough memory// – memory may be a scarce resource when you have to share the machine with others. You have to make sure that there is at least 256Mb of memory available to run //**Aware IM**//. If there is not enough memory all sorts of strange problems may be encountered. Usually companies that offer VPS services offer a certain amount of “guaranteed” memory (your own) and a certain amount of “burstable” memory (shared with others). 
    - Do not pick web hosts that offer burstable memory only.
    - Make sure that the amount of guaranteed memory is at least 256M
    - Make sure that the guaranteed memory is not used by applications that are often pre-installed by a web host. If they are, uninstall them.
  - //Port 8080 is blocked //– web hosts often blocks all ports other than the standard port 80. You have to configure the firewall settings of your VPS to allow external requests through port 8080 (or better still ask you web host to do this) 

You can also re-configure Tomcat to use a different port (to do this open the ''server.xml'' file located in the ''AwareIM/Tomcat/conf'' directory, search for ''8080'' and replace it with a different number).



===== Using Load Balancing to achieve better performance and scaling =====


Some web hosting companies, for example, Amazon offer load balancing capabilities where you can allocate several servers to handle your user requests. A special load balancing software will automatically detect servers under heavy load and redirect traffic to servers with smaller load. This can dramatically increase overall performance of your system and allow scaling it up as the number of users and requests grow.



It is easy to set up //**Aware IM**// to work with load balancing. This is what you need to do:

  - Install //**Aware IM **//on each server that should participate in the load balancing chain. On Amazon you would allocate several server instances and install //**Aware IM**// on each of them
  - Make sure that every server instance is set up to work with the single installation of the database. It has to be either MySQL, Maria DB, SQL Server/Azure, PostgreSQL or Oracle database. Apache Derby database cannot be used. The database may reside on one of the server instances or on a separate server altogether. To setup database connection modify the ''BASServer.props'' file on each server instance as described in the previous sections.
  - Make sure that every instance “sticks” to its user session. For example, Amazon offers a feature called “sticky sessions”. You must enable it so that the system will automatically route the request to the server that handles this particular user.



Note that load balancing should only be used in production where the system just runs already developed applications. It shouldn’t be used for application development.

See also

{{page>docs:5000_videos:020_deployment_and_configuration}}