The quickest and easiest way to install Alfresco is to run the Alfresco installation wizard for the target platform. This sets up all the required third-party software, configures your environment correctly, and provides a mechanism to start and stop the Alfresco server. It also includes scripts to apply any optional modules you may be interested in leveraging, such as Records Management.

The installation wizard has a default set of installation options, but you can choose to install a subset of these if all are not required. The optional components include WCM, SharePoint protocol support, an embedded MySQL database, OpenOffice, and the Java development kit (JDK). If any of these components are already installed, then selecting the custom install step in the installation wizard will allow you to choose what to install. The wizard will prompt you for the location of these existing components, if necessary.

After a successful installation, the installLocation will contain the aforementioned scripts and the following folders:

There are multiple installation packages available for Alfresco, so if you already have a Web application server installed, such as Tomcat or JBoss AS, then you can choose to get an appropriate installation package. The different installation packages and their installation instructions are available for download from Alfresco. For the purposes of this book, we will assume that the default installation wizard has been used with the default options.

Once installed, you can start the Alfresco server using the alf_start script in the installLocation. The server will take a few seconds to start and you can see progress in the log console.

When the repository starts, it loads properties files by default. These include:

The Alfresco installation wizard creates the alfresco-global.properties file and populates it with the values provided during installation. As the alfresco-global.properties file is loaded last, you can override any properties that appear in any of the previously loaded properties files.

For example, to disable the FTP server, you can override the ftp.enabled property from installLocation/tomcat/webapps/alfresco/WEB-INF/classes/alfresco/subsystems/fileservers/default/file-servers.properties. This is accomplished by adding the line ftp.enabled=false to installLocation/tomcat/shared/classes/alfresco-global.properties.

The most important property the Alfresco installation wizard sets is dir.root. This property defines the location of the alf_data folder. Alfresco uses a relational database to hold most of its data, such as metadata, folder structures, and versioning information. The content itself and the full-text indexes are stored on the file system in folders within the alf_data folder.

The contents of the contentstore and lucene-indexes folders must remain synchronized with the database; otherwise, you will see the following error at startup: The indexes are not synchronized with the database.

When Alfresco is set up without the installation wizard, not overriding dir.root is a common mistake. The default value is ./alf_data. This means that Alfresco looks for the alf_data folder in the location where the server was started and creates a new empty folder if it cannot find the folder. This is worth remembering whenever you delete a database, because if the database data is cleared, so must the contents in the folders lucene-indexes and contentstore within alf_data.

The Installing and Configuring Alfresco guide provides explanations of all the other properties in alfresco-global.properties as well as examples of other common configuration scenarios.

The Spring context loaded by the repository provides an extension mechanism in the form of a wildcard import of any Spring context file ending with -context.xml. The Alfresco installation wizard includes several sample Spring configuration files in installLocation/tomcat/shared/classes/alfresco/extension. For example, to enable the custom content model, remove the .sample suffix from the file custom-model-context.xml.sample.

To provide your own Spring configuration, simply place your file in the folder installLocation/tomcat/shared/classes/alfresco/extension. As with any Spring configuration changes, you must restart the server for the changes to take effect.

While the process of creating a Web script is detailed in Chapter 9, this section explains where you can place the Web script files.

You can place repository Web script files under installLocation/tomcat/shared/classes/alfresco/extension/templates/webscripts. You can use any arbitrary folder structure beneath this location with the exception of org/alfresco, which is reserved for Alfresco use.

You can also place repository Web scripts within the repository itself in the space /Company Home/Data Dictionary/Web Scripts Extensions. Files in this location supersede those in installLocation/tomcat/shared/classes/alfresco/extension/templates/webscripts. This lets you edit the file from any location, providing an upgrade-friendly approach, as no changes are required when you upgrade the WAR file. The only disadvantage of using this approach is that the runAs feature of the Web script engine is not supported when the files are located in the repository.

You can also use these two locations to override Web scripts provided by Alfresco. For example, placing a file with the same name in the relevant folder structure will override the out-of-the-box file of the same name.

Whenever you make any changes to a Web script or add a new Web script, you will need to refresh the Web script service. Using the following URL will display the Web scripts currently available in your server. There is also a Refresh Web Scripts button you can click to force a refresh. The URL depends on your install, but by default it will be:

You can configure various aspects of the Web tier—for example, the appearance of forms and debugging options. These configuration files should be provided as extensions and placed in the folder installLocation/tomcat/shared/classes/alfresco/web-extension.

The Share application is built upon the Surf platform, which itself provides an extension point in the form of the file web-framework-config-custom.xml.

Placing this file in the web-extension folder will make it load as part of the application. However, as all Surf-based applications load this file, problems can occur if you place any application-specific configuration in this file. To resolve this potential issue, all Surf-based applications can supply an application-specific custom configuration file. In the Share application, a custom configuration file share-config-custom.xml is available for this.

The advantage of providing configuration in this way is that the files are not cached by the application server's classloader. This lets you use the Refresh Web Scripts feature already described to reload the configuration files.

The process of creating various Share customizations is explained in Chapters 14 through 16. This section explains where the files are located.

As Share is running on the Web tier, most extension files are placed in various hierarchies under the folder installLocation/tomcat/shared/classes/alfresco/web-extension. However, there are a few exceptions; Web assets, CSS files, and images must be available on a file system accessible to the application server. You must place these files somewhere within installLocation/tomcat/webapps.

Following the principle of locating files in an upgrade-friendly location, do not use the folder installLocation/tomcat/webapps/share, as it will be deleted when a new or updated WAR file is deployed. When using Tomcat, the recommended location is within the folder installLocation/tomcat/webapps/ROOT. The ROOT folder in Tomcat, as the name suggests, represents the root context of the application server—for example, http://localhost:8080. As this is separate from the Alfresco Web applications, you can update the files independently. Once again, no changes are required for extensions to continue to work.

In cases where using the ROOT context of the application server is not viable, the best option is to package the extension as an Alfresco Module Package (AMP) file, which is further explained in the "Packaging Extension Files" section.

Depending on the complexity of the extension, there may well be several files. In the case of a Records Management module, there could be hundreds! This may be fine if there is only one extension, but once there are files of two or three extensions, things could get quite messy and complex. This may also require a mechanism for distributing the extension, especially if it is being shared with the community. For these scenarios, Alfresco provides AMP files.

An AMP file is essentially a ZIP file with a pre-determined internal folder structure and, at its minimum, a single required configuration file. An AMP file is applied to a WAR file, which is then redeployed to the application server. This makes the extension appear as part of the Alfresco Web application; for example, all the files are within installLocation/tomcat/webapps/alfresco or installLocation/tomcat/webapps/share. The repository also maintains a registry of the installed modules and their version, enabling the modules to be upgraded independently of the WAR file.

There are some disadvantages, though, as discussed in previous sections of this chapter. As this means the files are all loaded by the application server's main classloader, you lose the ability to reload configuration files. In addition, since the AMP construction, WAR integration, and deployment are not conducive to a streamlined development cycle, you should use AMP files only for completed extensions.

Alfresco uses the RhinoScript engine to run programs written in JavaScript within the Alfresco server (in contrast to running client JavaScript in the Web browser for the user interface). This server-side JavaScript engine gives the developer access to Alfresco objects and processes through JavaScript programs that are simpler to write than Java, as well as easier to debug since the code is interpreted rather than compiled. Better still, these JavaScript program files can be managed as documents in the Alfresco Content Application Server and executed dynamically.

All JavaScript files being executed in the RhinoScript JavaScript engine have a logger root object available to them. The logger object exposes two methods: isLoggingEnabled() and log(). As with log4j, the isLoggingEnabled() method determines whether logging is turned on. The log() method outputs the provided string to the application server console and the alfresco.log file. The following code shows the typical usage for the logger object:

if (logger.isLoggingEnabled())
   logger.log("Output some useful information to the console");

To turn on JavaScript debugging, set the log4j level for the ScriptLogger class to debug in the file installLocation/tomcat/webapps/alfresco/WEB-INF/classes/log4j.properties (on the repository or Web tier). For example:

log4j.logger.org.alfresco.repo.jscript.ScriptLogger=debug

JavaScript files executed in the RhinoScript JavaScript engine (as previously described) can be debugged in a similar manner to any popular IDE. You can use a couple of methods to enable the JavaScript debugger. The first approach enables the debugger to appear every time the server starts, and the second approach allows you to enable it when required.

By default, client-side JavaScript is minimized for performance reasons. However, this is not ideal for development, as the JavaScript in utilities such as Firebug for Firefox show the source file as one very long line of text. To make Share use the full version, you can turn on client-side debugging through the file web-framework-config-custom.xml.

To turn on client-side debugging, create the file installLocation/tomcat/shared/classes/alfresco/web-extension/web-framework-config-custom.xml, and add the following:

<alfresco-config>
<config replace="true">
<flags>
<client-debug>true</client-debug>
</flags>
</config>
</alfresco-config>

This also enables a log4javascript utility written by Tim Down (http://log4javascript.org) embedded in Share that provides logging capabilities to client-side JavaScript. To see the log window, press Ctrl, Ctrl, Shift, Shift. To make the logger window appear on every page load, add <client-debug-autologging>false</client-debug-autologging> to the file web-framework-config-custom.xml. For example:

<alfresco-config>
<config replace="true">
<flags>
<client-debug>true</client-debug>
<client-debug-autologging>false</client-debug-autologging>
</flags>
</config>
</alfresco-config>

By default, there are several caches in place to aid performance; however, during development these caches prevent changes to source files from taking effect. JavaScript files are compiled so they do not need to be continually interpreted. You can turn this feature off with a custom Spring configuration file. This file can be called anything as long as it has the -content.xml suffix.

In this example, create the file custom-web-framework-application-context.xml in the folder installLocation/tomcat/shared/classes/alfresco/web-extension, and type the following:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN'
'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
<bean id="webframework.webscripts.scriptprocessor"
class="org.alfresco.web.scripts.PresentationScriptProcessor">
<property name="searchPath" ref="webframework.searchpath" />
<property name="compile"><value>false</value></property>
</bean>
<bean id="webframework.scriptprocessor"
class="org.alfresco.web.scripts.PresentationScriptProcessor">
<property name="searchPath" ref="webframework.templates.searchpath" />
<property name="compile"><value>false</value></property>
</bean>
</beans>

The application server's main classloader caches files, including files included in FreeMarker templates. While this is a desired feature in a production environment, this is not the case during development.

To disable caching of included folders, set the log4j level for the PresentationScriptProcessor and RhinoScriptProcessor classes to debug by adding the following lines to the file installLocation/tomcat/webapps/share/WEB-INF/classes/log4j.properties:

log4j.logger.org.alfresco.web.scripts.PresentationScriptProcessor=debug
log4j.logger.org.alfresco.repo.jscript.RhinoScriptProcessor=debug