Windows Service HOW-TO

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Installation
With the default installation, Alfresco is bundled as a web application that launches within Tomcat. To set up Alfresco to run as a Windows Service, you need to set up Tomcat (and optionally MySQL) to run as a Windows service.

Table of Contents

• 1 Alfresco Tomcat Bundle
  
  
  
  • 1.1 Basic Installation
  
  
  • 1.2 Installing the Alfresco Tomcat service
    
    
    
    • 1.2.1 Configurable Parameters
    
    
    • 1.2.2 Additional Parameters
    
    
  
  
  • 1.3 Installing the MySQL service (optional)
  
  
  • 1.4 Editing the Alfresco Tomcat Service
  
  
  • 1.5 Starting and Stopping the Service
  
  
  • 1.6 Removing the Alfresco Tomcat Service
  
  


• 2 JBoss Application Server


• 3 Installation Apache Tomcat (Old Instructions)
  
  
  
  • 3.1 The easy way
  
  
  • 3.2 Another way
  
  


• 4 Further Information

Alfresco Tomcat Bundle

Both the Community and Enterprise editions of Alfresco are available for download within a pre-configured version of Apache Tomcat, known as the Tomcat Bundle. This bundle is ideal for installation onto systems where you want to perform a manual installation, or where you may have multiple versions of Alfresco installed on the same system, e.g. test servers.

The Tomcat Bundle packages are provided in two forms.

• A .zip version, intended for installation on Windows systems
  
• A .tar.gz version, for GNU/Linux operating systems
  

The .zip package provides the customised Tomcat build along with a set of Windows .bat scripts for starting up and shutting down Alfresco. This is the version that you should use for this method.

Basic Installation

Extract the contents of the .zip package into a new folder on your system. It is recommended that you install into a location without any spaces in the path, e.g. c:\alfresco or c:\alfresco-community-tomcat-3.3.

At this point you may wish to check that that Alfresco starts up correctly by running the alf_start.bat script. This will start up the bundled Tomcat container, plus the embedded MySQL database.

Installing the Alfresco Tomcat service

The tomcat6.exe excutable can be used to install a Windows service which will start and stop Tomcat automatically, and this is included within the Alfresco Tomcat bundle.

tomcat6.exe is not in the community version 3.3g, http://forums.alfresco.com/en/viewtopic.php?f=8&t=27723 explain that you must download tomcat6 and copy it in the alf_path\tomcat folder to make it work

The tool provides a great deal of flexibility over how Tomcat can be configured, and offers a large number of command-line options to acheive this.

Although you should thouroughly test and tune your application server configuration just as you would do for a database, the following instructions should provide a good general configuration for the Alfresco Tomcat bundle hosting the alfresco and share webapps, using a Tomcat 6 bundle installed in c:\alfresco-community-tomcat-3.3. For instructions on how to configure Tomcat 5 (distributed with the Alfresco Tomcat bundle prior to version 3.0), see below.

cd c:\alfresco-community-tomcat-3.3\tomcat\bin
tomcat6 //IS//AlfrescoTomcat --DisplayName='Alfresco Community Edition' \ 
--Description='Alfresco Tomcat Bundle - Repository and Share' \
--Install='C:\alfresco-community-tomcat-3.3\tomcat\bin\tomcat6.exe' \
--Startup='auto' \
--Jvm='C:\Program Files\Java\jdk1.6.0_18\jre\bin\server\jvm.dll' \
--Classpath='C:\alfresco-community-tomcat-3.3\tomcat\bin\bootstrap.jar' \
--StartMode=jvm --StopMode=jvm --StartClass=org.apache.catalina.startup.Bootstrap \
--StartPath='C:\alfresco-community-tomcat-3.3' --StartParams=start \
--StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop \
--JvmMs=256 --JvmMx=1024 --JvmSs=1024 \
++JvmOptions='-Dcatalina.home=C:\alfresco-community-tomcat-3.3\tomcat' \
++JvmOptions='-Dcatalina.base=C:\alfresco-community-tomcat-3.3\tomcat' \
++JvmOptions='-Djava.endorsed.dirs=C:\alfresco-community-tomcat-3.3\tomcat\endorsed' \
++JvmOptions='-Djava.io.tmpdir=C:\alfresco-community-tomcat-3.3\tomcat\temp' \
++JvmOptions='-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager' \
++JvmOptions='-Djava.util.logging.config.file=C:\alfresco-community-tomcat-3.3\tomcat\conf\logging.properties' \
++JvmOptions='-XX:MaxPermSize=256m' \
++JvmOptions='-XX:NewSize=256m' \
++JvmOptions='-Dalfresco.home=C:\alfresco-community-tomcat-3.3' \
++JvmOptions='-Dcom.sun.management.jmxremote=true'

This will create a Windows service with the name AlfrescoTomcat, which will appear in the Windows Service Manager as Alfresco Enterprise Edition.

The service name must be unique as it is used to reference the service within Windows. Choosing AlfrescoTomcat or similar allows the service to co-exist with other Tomcat installations, which you might have if you are using a separate Tomcat instance or the Alfresco Virtualisation Server to preview web content.

Configurable Parameters

Change these parameters to suit your own installation.

--DisplayName	Display name shown in the Service Manager
--Description	Descriptive text shown in the Service Manager
--Install	Must point to the location of tomcat.exe in the Tomcat bundle
--Startup	Service start-up type - one of auto or manual
--Jvm	Must point to the location of the jvm.dll shared library in your JRE/JDK
--Classpath	Must contain the location of bootstrap.jar in the Tomcat bundle
--StartPath	Should point to the base Alfresco directory, or wherever you want alfresco.log to be created.
--JvmMs, --JvmMx, --JvmSs	Java heap settings - see JVM Tuning
--JvmOptions	-Dcatalina.home, -Dcatalina.base - Should point to tomcat directory in the installation -Djava.endorsed.dirs - Should point to tomcat/endorsed directory -Djava.io.tmpdir - Should point to tomcat/temp directory -Djava.util.logging.config.file - Should point to logging.properties file in tomcat/conf -XX:MaxPermSize - Max PermGen space - see JVM Tuning -XX:NewSize - New Size - see JVM Tuning -Dalfresco.home - Should point to the base Alfresco directory -Dcom.sun.management.jmxremote - Enables remote JMX management

Additional Parameters

In addition to the above, the following parameters can be included if required in your environment

--User	Username of the system user which the service should run as. Must have the 'Logon as a service attribute' enabled.
--Password	Password for the system user which the service should run as

Installing the MySQL service (optional)

As well as creating a Windows service to start up Tomcat, you will also need to consider how the database used by Alfresco starts up.

The MySQL Windows installer allows you to install the database server as a local service as well as configuring the database to meet your requirements. Alternatively, you may be hosting your database on another machine or using another relational database such as Oracle.

However, if you wish to use MySQL on the same machine as Tomcat and you do not want a separate installation outside of the Alfresco installation, you can install the instance of MySQL installed with the Tomcat Bundle as an additional Windows service.

Before you can install the Windows service you need to set the following parameters in the c:\alfresco\mysql\my.ini configuration file (assuming Alfresco has been installed in c:\alfresco).

basedir='c:\alfresco\mysql'
datadir='c:\alfresco\alf_data\mysql'

Then, use the following commands to install the service itself

cd c:\alfresco\mysql\bin
mysqld.exe --install AlfrescoMySQL --defaults-file=c:\alfresco\mysql\my.ini

Lastly you should update the Tomcat service so that it depends on the MySQL service, and hence starts MySQL first.

cd c:\alfresco\tomcat\bin
tomcat6 //US//AlfrescoTomcat --DependsOn=AlfrescoMySQL

Editing the Alfresco Tomcat Service

If the AlfrescoTomcat service already exists, use the //US switch instead of //IS to update it. You only need to specify those parameters that you want to set or update; all other parameters should be left untouched.

For example, assuming Alfresco installed in c:\alfresco-community-tomcat-3.3

cd c:\alfresco-community-tomcat-3.3\tomcat\bin
tomcat6 //US//AlfrescoTomcat --DisplayName='Alfresco Community Edition 3.2'

You can also use the tomcat6w.exe process to edit your configuration in a graphical dialogue.

cd c:\alfresco-community-tomcat-3.3\tomcat\bin
tomcat6w //ES//AlfrescoTomcat

Starting and Stopping the Service

The simplest method of starting and stopping the Alfresco Tomcat service is to use the Service Manager component in Windows. In Control Panel click Administrative Tools > Services to display the console, or run the command services.msc directly.

Alternatively the net start and net stop commands can be used from a prompt

net start AlfrescoTomcat
net stop AlfrescoTomcat

Removing the Alfresco Tomcat Service

The following commands will remove the AlfrescoTomcat service completely from the Windows service list, assuming Alfresco installed in c:\alfresco-community-tomcat-3.3

cd c:\alfresco-community-tomcat-3.3\tomcat\bin
tomcat6w //DS//AlfrescoTomcat

JBoss Application Server

Unlike Tomcat, JBoss AS does not provide an out-of-the-box executable for installing the application server as a Windows service. However JavaService provides a free utility which can be used to perform the installation.

The installation procudure is documented on the JBoss Community wiki. See http://community.jboss.org/wiki/JavaService.

As with Tomcat, the service should be configured appropriately to ensure that Alfresco starts in the correct context and that the JVM is appropriately tuned for the application. See the section JVM options and -server flag on that page, and ensure you conffigure the JAVA_OPTS values appropriately, including the -Xms, -Xmx, -Xss parameters that are specified explicitly for Tomcat.

Installation Apache Tomcat (Old Instructions)

• Use the following commands to install Alfresco as a Windows Service
  

(Assume Alfresco installed at c:\alfresco)

For Tomcat 5, use the following instructions:

cd c:\alfresco\tomcat\bin
service.bat install alfresco
tomcat5.exe //US//alfresco --DisplayName 'Alfresco Server'
tomcat5.exe //US//alfresco --JvmMs=256 --JvmMx=512 --JvmSs=64 --JvmOptions -XX:MaxPermSize=128m 
tomcat5.exe //US//alfresco --JavaHome=c:/alfresco/java
  ===>  I think it should be tomcat5.exe //US//alfresco --JavaHome=c:/Program Files/java
         Because the latest full bundle installs java under program files....
tomcat5.exe //US//alfresco --Environment ALF_HOME=c:/alfresco/
tomcat5.exe //US//alfresco --Environment PATH=c:/alfresco/bin;%PATH%
tomcat5.exe //US//alfresco --StartPath c:/alfresco --Startup auto

For Tomcat 6, use the following instructions:

The easy way

cd c:\alfresco\tomcat\bin
service.bat install
tomcat6 //US//Tomcat6 --JvmMs=128 --JvmMx=512 --JvmSs=96 ++JvmOptions '-XX:MaxPermSize=128m'

This will install Alfresco as a service named 'Tomcat6' with the service display name 'Apache Tomcat'; if you add a 'name' after 'install', the service name will be that 'name', and the service display name will be 'Apache Tomcat name'

For example installing with name=Alfresco:

cd c:\alfresco\tomcat\bin
service.bat install Alfresco
tomcat6 //US//Alfresco --JvmMs=128 --JvmMx=512 --JvmSs=96 ++JvmOptions '-XX:MaxPermSize=128m'

This will result in a service named 'Alfresco' with a server display name 'Apache Tomcat Alfresco'.

REMEMBER THE SERVICE NAME TO UNINSTALL OR EDIT THE SERVICE (AND TO SPECIFY OPTIONS AS IN THE LAST LINE ABOVE); WHEN IN DOUBT, DON'T CHANGE IT (you can change the service display name by editing the service). When you forget the name, you can run services.msc and look for services named 'Apache Tomcat xxx'.

Troubleshooting:
If you are having memory errors then you may be suffering from a bug in the service.bat file which hard codes the memory settings.  To work around it, open C:\Alfresco\tomcat\bin\service.bat and edit line 123 as follows.  Note the hard coded values for MaxPermSize, JvmMs, JvmMx and JvmSs:

'%EXECUTABLE%' //US//%SERVICE_NAME% ++JvmOptions '-XX:MaxPermSize=128m;-Djava.io.tmpdir=%CATALINA_BASE%\temp;-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager;-Djava.util.logging.config.file=%CATALINA_BASE%\conf\logging.properties' --JvmMs 128 --JvmMx 512 --JvmSs=96

Another way

cd c:\alfresco\tomcat\bin
tomcat6 //IS//Tomcat6 --DisplayName='Alfresco Server' \
--Install='C:\Program Files\Tomcat\bin\tomcat6.exe' --Jvm=auto \
--StartMode=jvm --StopMode=jvm \
--StartClass=org.apache.catalina.startup.Bootstrap --StartParams=start \
--StopClass=org.apache.catalina.startup.Bootstrap --StopParams=stop
tomcat6 //US//Tomcat6 --JvmMs=128 --JvmMx=512 --JvmSs=96 ++JvmOptions '-XX:MaxPermSize=128m'

• To uninstall the service, at a later time, do the following:
  

(Assume Alfresco installed at c:\alfresco)

For Tomcat 5:

cd c:\alfresco\tomcat\bin
service.bat uninstall alfresco

For Tomcat 6:

cd c:\alfresco\tomcat\bin
service.bat uninstall Tomcat6 (or the 'name' used when installing the service)

• To edit your service settings at any time:
  

(Assume Alfresco installed at c:\alfresco)

For Tomcat 5:

cd c:\alfresco\tomcat\bin
tomcat5w.exe //ES//alfresco

For Tomcat 6:

cd c:\alfresco\tomcat\bin
tomcat6w.exe //ES//Tomcat6 (or the 'name' used when installing the service)

Finally, to start the service, just go into your Windows Service control panel and locate the service that is now named 'Alfresco Server'.  You can start and stop Alfresco from this control panel (and set it to 'Automatic', if you want it to start automatically at boot time).

Further Information

You may wish to consult the Apache Tomcat Website to learn more about Tomcat and the various options that it will support, with specific HOW-TO information provided on the following pages:

Apache Tomcat 5.5 Windows service How-To

Apache Tomcat 6.0 Windows service How-To