Installing on MacOS X

[resplin]

Obsolete Pages{{Obsolete}}

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

Installation

This guide is still work in progress. Everything except instructions for CIFS should be working now. /Alexandra

Table of Contents

• 1 Installing Alfresco
  
  
  
  • 1.1 Alfresco Tomcat Bundled Installation
  
  
  • 1.2 Simple Installation on OS X
  
  
  • 1.3 Install JDK 5.0
  
  
  • 1.4 Install Alfresco Tomcat Bundle
  
  
  • 1.5 Set Paths
  
  
  • 1.6 Optional Install of Database
  
  
  • 1.7 Optional Install of OpenOffice (seem to be working finally!)
    
    
    
    • 1.7.1 Optional tips for running X11 applications in Mac OS X
    
    
  
  
  • 1.8 Running the Alfresco Server
  
  
  • 1.9 Closing the Alfresco Server
  
  
  • 1.10 Connect using WebDav on Mac OS X
  
  
  • 1.11 Use and connect to the FTP-server
  
  
  • 1.12 Using the CIFS Server
    
    
    
    • 1.12.1 Port remapping to remove requirement to run as root
    
    
    • 1.12.2 Removing the .DS_Store 'duplicate' files
    
    
  
  
  • 1.13 Image Manipulation
  
  
  • 1.14 Trouble-Shooting
  
  
  • 1.15 External references
  
  

Installing Alfresco

The following is a guide to installing Alfresco on Mac OS X and Mac OS X Server.

Alfresco Tomcat Bundled Installation

Requirements:

• Mac OS X 10.4 or above
  
• Java 1.5 is preinstalled on Mac OS X 10.4 and Mac OS X 10.4 Server. Pre-release packages of Java are available for download for registrered (free) users at http://developer.apple.com
  
• Alfresco available from http://www.alfresco.com
  

Optional:

• MySQL* Database available from http://www.mysql.com (or other database)
  
• OpenOffice for Mac OS X for document transformation available from http://www.openoffice.org. Requires X11 which can be found on the install DVD.
  

• MySQL is preinstalled on Mac OS X Server
  

Simple Installation on OS X

All these instructions assume knowledge of using OS X from Terminal commands.  You
may need to prefix some of the commands with 'sudo' if you do not have administrative
access.

Install JDK 5.0

- If you already have J2SE Development Kit 5.0 installed, skip to 'Install Alfresco Tomcat Bundle'

- Browse to http://www.apple.com/support/downloads/java2se50release1.html
- Install once downloaded
- Ensure the JAVA_HOME variable is set correctly

Install Alfresco Tomcat Bundle

Note: This assumes you have a /opt directory but virtually any directory will do. If this is your development workstation, we recommend your home directory for convenient: ~/alfresco. Of course,  /usr/local should work, or create your own /opt.

• Browse to http://www.alfresco.com/downloads (http://wiki.alfresco.com/wiki/Installing_Labs_3#Linux_download_and_installation for v3 labs)
  
• Download the 'Alfresco Linux Tomcat Bundle' option
  
• Create a directory in '/opt' named 'alfresco' 
  

  sudo mkdir /opt/alfresco

• Copy the downloaded alfresco bundle to /opt/alfresco
  

  sudo cp alfresco-community-tomcat-2.0.0.tar.gz  /opt/alfresco

or (for 2.1)

  sudo cp alfresco-community-tomcat-2.1.0.tar.gz  /opt/alfresco

- Tar uncompress alfresco-community-tomcat-2.0.0.tar.gz  in the '/opt/alfresco' directory

  sudo gnutar -xzvf alfresco-community-tomcat-2.0.0.tar.gz

or (for 2.1)

  sudo gnutar -xzvf alfresco-community-tomcat-2.1.0.tar.gz

or (for 3b)

  sudo gnutar -xzvf alfresco-community-tomcat-3b.tar.gz

or (for 3c)

  sudo gnutar -xzvf alfresco-labs-tomcat-3c.tar.gz

or (for 3d / 3Stable)

  sudo gnutar -xzvf alfresco-labs-tomcat-3c.tar.gz

Note: As of Alfresco 3d / 3Stable, there is now a Mac OS X installer. If you use that installer, you can skip all installation instructions noted here though the CIFS and FTP configuration instructions will come in handy.

If you not intend to run Alfresco as root user make sure all permissions for the user you want to run as is set to both exceute and write access for the bundle.

Set Paths

Edit 'alfresco.sh' and check the variables are pointing to the location where Tomcat
is installed:
- For the Tomcat bundle, this will be '/opt/alfresco/tomcat'

For version 2.1,

/opt/alfresco/tomcat

is the default

Optional Install of Database

Alfresco is pre-configured to use the HSQL database, but can easily be
configured to use other databases, please visit the forums and wiki at
www.alfresco.com for guidelines

- See 'README-mysql.txt' for details on configuring for use with MySQL.

General configuration details can be found at:
http://wiki.alfresco.com/wiki/Repository_Configuration#New_Installations

You have now installed all the components needed to run the Alfresco server.

Optional Install of OpenOffice (seem to be working finally!)

If you would like to have a range of document transformations available from within
Alfresco, you need to install OpenOffice.  This is entirely optional and can be
done at any point after Alfresco has been installed. 

• • • There are known issues with OpenOffice 2.0.1 and 2.0.2 ***
      

• Make sure X11 is installed otherwise do it from the Mac OS X install DVD
  
• Browse to http://download.openoffice.org
  
• Download the OS X version
  
• Install OpenOffice
  
• Start one of the OpenOffice programs to go through initial registration, then close it
  
• Rename '/opt/alfresco/zstart_oo.sh' to '/opt/alfresco/start_oo.sh'
  

  mv zstart_oo.sh start_oo.sh

• Edit '/opt/alfresco/start_oo.sh' and set the correct location for OpenOffice. On Mac OS X the usual location is in /Applications. There is an error in the script regarding the path to 'soffice' and the correct one for OpenOffice 2.2 is
  

  /Applications/OpenOffice.org\ 2.2.app//Contents/MacOS/program/soffice

• The launch argument looks something like this
  

  /Applications/OpenOffice.org\ 2.2.app/Contents/MacOS/program/soffice '-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager' -nologo -headless -nofirststartwizard & 

What made it work for me was to not run the alfresco.sh script as root and do it from xterm after starting X11. No configuration of DISPLAY environment variables seem to be necessary.

• Stop and restart the Alfresco server if it is already running
  

Optional tips for running X11 applications in Mac OS X

• Add the following lines in the top of the start_oo.sh script in order to configure a display in X11
  

  DISPLAY=localhost:1.0; export DISPLAY
  cd /usr/X11R6/bin
  ./Xvfb :1 -screen 0 800x600x32

• It also seems that using the open-X11 script in the X11R6/bin folder is the suggested way to start X11 applications on Mac OS X. However, the idea is to start OpenOffice headless with the right sockets open for Alfresco to access it as a transformation engine.
  

Running the Alfresco Server

Navigate to the '/opt/alfresco' directory, and enter

  ./alfresco.sh start

Or, to help ensure CIFS can properly bind to privileged port (otherwise see port remapping below)

  sudo ./alfresco.sh start

You can now try Alfresco by visiting:

http://localhost:8080/alfresco
Note: it may take a few minutes before the server responds.  When I first started, it took three iterations of starting... then becoming frustrated and stopping...--Jake 22:01, 18 January 2008 (UTC)

The server is configured with a single administrative login with user name and password
both set to 'admin'.

To test the installation, you may wish to follow the tutorial, available from:

http://www.alfresco.com/downloads or from the company space from within the Web Client.

Closing the Alfresco Server

Navigate to the '/opt/alfresco' directory and run './alfresco.sh stop'.

Connect using WebDav on Mac OS X

The Alfresco repository can be mounted as a WebDav volume in Mac OS X Finder. Choose Apple-K and enter the following

  http://[IP-address][:port]/alfresco/webdav/

Use and connect to the FTP-server

There is a built-in Java-based FTP-server in Alfresco. That server defaults to the standard port 21 but that will only work if you run the Alfresco startup script as root. If you need to start Alfresco as anything other than root you will need to change the port. In order to bind FTP-server to unpriviliged ports you need to edit file-servers.xml and locate the following entry:

  <config evaluator='string-compare' condition='FTP Server'>
  <serverEnable enabled='true'/>

and add the following line after:

  <port>1121</port>

Then you will need to make sure the firewall is open for the port you selected (any port above 1024 can be entered in the above example - though some may already be in use). That means that you need to the specify another port than the default one in your ftp client. Another option is to set up port forwarding so the non-priviliged port is mapped to the standard FTP port 21.

In order to have support for non-ASCII Swedish characters åäö and ÅÄÖ I had to add an extra line of code to set the file server to MacRoman and then do the same in my FTP-client (Cyberduck).

  <charSet>MacRoman</charSet>

See more on http://wiki.alfresco.com/wiki/File_Server_Configuration#FTP_Server_Configuration

For a list of character encodings see here: http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html

Using the CIFS Server

To check the CIFS server is running on the local machine, try connecting from the Alfresco server using smbclient.

  smbclient -L 127.0.0.1

or

  smbclient -L `hostname` -U admin%admin

You may mount the repository on a Mac client using a Network connection (Apple-K in Finder) of the form:

  'smb://IP-address/alfresco'.

A dialogue box should appear prompting for WORKGROUP, USER and PASSWORD. WORKGROUP can be left empty and use your web client user and password for the remaining to. A volume called 'ALFRESCO' should be mounted in Finder.

If you have trouble using Finder to mount an SMB share, use the command line instead, like this:

  mount_smbfs //admin:admin@localhost:1445/Alfresco /Users/jpotts/alfresco-cifs

The '1445' is the CIFS port (see firewall port remapping, below) and may not be required in all cases.

Starting Alfresco as root user is required to have CIFS working without remapping.

Port remapping to remove requirement to run as root

In order to be able to start Alfresco without being root user the file server config and firewall settings need to be updated.

For file server config changes see running CIFS from a normal user account

For firewall settings:

  # ! /bin/sh
  echo 'Setup CIFS Port Forwarding ...'
  sysctl -w net.inet.ip.fw.enable=1
  sysctl -w net.inet.ip.forwarding=1
  sysctl -w net.inet.ip.fw.verbose=1
  sysctl -w net.inet.ip.fw.debug=0

  #Will remove any existing rules in your current configuration. Optional.
  ipfw flush

  #ipfw add 100 count log ip from any to any
  ipfw add 200 allow ip from any to any via lo0
  
  # Forward native SMB and NetBIOS sessions to non-privileged ports
  ipfw add 300 fwd <local ip>,1445 tcp from any to me dst-port 445
  ipfw add 400 fwd <local ip>,1139 tcp from any to me dst-port 139

  # Forward NetBIOS datagrams to non-privileged ports (does not currently work)
  ipfw add 500 fwd <local ip>,1137 udp from any to me dst-port 137
  ipfw add 600 fwd <local ip>,1138 udp from any to me dst-port 138

  ipfw add 65535 allow ip from any to any

  #Resets logs in ipfw. Optional
  ipfw zero
  echo 'Done.'

Replace all instances of <local ip> above with your server's IP address.  Please note that in order to apply these rules, the firewall need to be activated. In Mac OS X Client do that in System Preferences->Sharing, and for Mac OS X Server open the Server Admin GUI application and make sure the firewall is on. Please observe that neither GUI-tool include all the options necessary to do the settings described above. Therefore it may be appropriate to create a shell script with the terminal commands for ipfw listed above. Run that as root or use the sudo-command. Also note that the Server Admin GUI can be rather slow to update its list of rules after running the script.

If you need another GUI tool to manipulate the firewall on Mac OS X have a look at: http://www.hanynet.com/waterroof/

Removing the .DS_Store 'duplicate' files

-Mac OS X creates hidden .DS_Store files in each folder. DS_Store (Desktop Services Store) is a hidden file created by Mac OS X to store custom attributes of a folder such as the position of icons or the choice of a background image. The creation of these files can be annoying when using Alfresco and can be disabled using the instructions on the following page:

http://docs.info.apple.com/article.html?artnum=301711

The following instructions in the orginial readme file seems only to be applicable for Windows clients

If you are unable to connect to the CIFS server, then depending on your network, you may need
to configure the domain for CIFS to use.  You will need to have started the Alfresco server
at least once to be able to do this.  To set the domain, edit the 'file-servers-custom.xml'
file in the '~/alfresco/tomcat/shared/classes/alfresco/extension' directory and add the
domain into the following line:

  <host name='${localname}_A'/>

so that it is something like:

  <host name='${localname}_A' domain='MYDOMAIN'/>

You will need to restart the Alfresco server for this to take effect.

Once the Alfresco server is running, it should be possible to connect to it by mapping a
drive to it.  The name to use for the mapping is based on the name of the server on which
Alfresco is running, with '_A' on the end.  For example, if the PC name is 'MYPC01', then
the CIFS server name will be 'MYPC01_A'. 

To map the drive on a MS Windows client, open Windows Explorer, go
to the Tools menu and select 'Map Network Drive...'.  In the Map Network Drive dialog,
choose the drive letter you wish to use.  To locate the CIFS server, click the 'Browse...'
button and find the server name as described above.  You should then have the option to
select a folder within it called 'alfresco'.  Click 'OK' to select the folder, then click
'Finish' to map the drive.  You should now have access to the Alfresco repository from
the mapped drive.  If the CIFS server name does not show in the browse dialog, you may also
enter the folder location directly in the dialog, for example '\\MYPC01_A\alfresco'.

See more on: http://wiki.alfresco.com/wiki/File_Server_Configuration#SMB.2FCIFS_Server_Configuration

Image Manipulation

To enable image manipulation on Mac OS X or Mac OS X Server, the ImageMagick package needs to be installed.  To check, try running the 'convert' command, which is part of ImageMagick and usually found in /usr/bin.  Otherwise download ImageMagick-universal-apple-darwin8.10.1.tar.gz from

http://www.imagemagick.org/script/binary-releases.php#macosx

and follow the install instructions. If ImageMagick has been installed in /opt/imagemagick then add the following lines to the alfresco.sh startup script in order to make it available in the PATH

  export PATH=$PATH:/opt/imagemagick/ImageMagick-6.3.6/bin

  export MAGICK_HOME='/opt/imagemagick/ImageMagick-6.3.6'

  export DYLD_LIBRARY_PATH='/opt/imagemagick/ImageMagick-6.3.6/lib'

Trouble-Shooting

Remember to check the Alfresco.log file in the Alfresco Root directory. That can be done using 'more' or 'tail' command in the terminal but also using the GUI-application called Console found in /Applications/Utilities. In order to see the Alfresco directory you may need to enable display of hidden files in Mac OS X or Mac OS X Server. That can be done using several free/shareware applications like Cocktail: http://www.maintain.se/cocktail/

There should be no error messages with java stack-traces in the log file.

If you have problems with your installation, please look for help on the Installation Forum and ask for any additional help you may need.

- The JAVA_HOME variable must be set correctly to your Java5 installation.

- If the following errors are reported on the console:

 ERROR [AbstractImageMagickContentTransformer] JMagickContentTransformer not available:
 ERROR [AbstractImageMagickContentTransformer] ImageMagickContentTransformer not available:
 Failed to execute command: convert ...

These are not issues which will cause the server to fail. Alfresco is reporting that various external document transformation engines are not available for use by the server. 

- If you see this error on server startup:

 ERROR [protocol] FTP Socket error
   java.net.BindException: Address already in use: JVM_Bind
        at java.net.PlainSocketImpl.socketBind(Native Method)

Check to see if you have any services running against port 8080 for the Alfresco server and port 21 for the Alfresco FTP integration. (Please note that if running Alfresco from anything else than root the ftp port need to be set to something above 1024. See section above for instructions)

- To access the CIFS repository directly from the FireFox browser, you need to install the Alfresco FireFox Extension from here:

http://sourceforge.net/projects/alfresco

Internet Explorer does not require the extension to open CIFS folders directly.

- then you may view the CIFS folder from file:///Volumes/alfresco

For more troubleshooting tips see: http://wiki.alfresco.com/wiki/Troubleshooting

External references

Our good friends at AFP548 have a document about this called Document Management in the Fresh Air and recomend use Mac How.