Page tree
Skip to end of metadata
Go to start of metadata

Updated Guide Available

An updated guide to Installing DSpace on OSX has been created. See: Installing DSpace on OSX (2014)

This tutorial is an aid to doing the bits of the standard install in a mac-specific way. I'll try to keep the headings/numbering the same so you can follow.

See [ Installing DSpace on OSX] for an older, more terse version.

I gather that DSpace can be difficult to install sometimes - these guidelines made it a breeze for me.


1. OSX: Install the latest XCode tools from Apple. If you have Tiger or later then the ones that came on your install disc are probably fine.

2. Java: xCode tools should have updated this. make sure you have done all your system updates. Check Java with

java -version

3. Apache Ant: xCode should have done this too.

ant -version

4. PostgreSQL 8.0+
I like OSX Postgres installer found at as it puts PostgreSQL in /usr/local thus saving me from the game of 'hunt the os specific path' that can make your life hell. This way everything is where you expect it to be (especially if you are looking postgresql documentation that assumes unix/linux)
There are a number of OSX installers/builds. Use the one you like best.

Note: you can also install PostgreSQL using MacPorts (or you can read here [ Mac How] )

  1. for example
    sudo port install postgresql-jdbc postgresql80 postgresql80-doc postgresql80-server

Note: these instructions assume postgresql in /usr/local other installers may not do the same. multiple installs of postgresql with associated startup items etc can be a headache. Start with a clean machine if you can.

Create a new user in the Users System Prefs pane:

1. Name: PostgreSQL User
2. Short Name: postgres
3. Password: whatever you want

(there is no good reason to create a shell only user - a standard osx user is fine - and easier to manage)

DSpace doesn't care which which osx user - it works via tcp.

Open a terminal window and type in the following commands:

sudo chown -R postgres /usr/local/pgsql/

enter administrator password when asked

su - postgres

(enter the password of the newly created postgres user when asked)

/usr/local/bin/initdb -E UTF8 -D /usr/local/pgsql/data

and wait for the operation to complete

/usr/local/bin/pg_ctl -D /usr/local/pgsql/data -l postgres.log start

Read the responses as they will tell you if things go badly. The homepage for the installer includes some links for troubleshooting.

I have recently had an instance when it was refusing to start because of the log file - but this was resolved by specifying the full path to the log file; -l /usr/local/pgsql/postgres.log

PS Shut down the DB server with;

/usr/local/bin/pg_ctl stop -D /usr/local/pgsql/data/

Once you have started postgresql...
Edit /usr/local/pgsql/data/postgresql.conf uncomment the line starting:

listen_addresses = 'localhost'

Then restart PostgreSQL with

/usr/local/bin/pg_ctl stop -D /usr/local/pgsql/data/

wait for it...

/usr/local/bin/pg_ctl -D /usr/local/pgsql/data -l postgres.log start

5. Apache Tomcat 5.5

DSpace will need to run as the same user as Tomcat, *so install and run Tomcat as a user called 'dspace' *.
(Do this as dspace after step 1. Create the DSpace user. below. Sorry.

mv apache-tomcat-5.5.20 /usr/local/

. Then, to make things easier in the future when upgrading tomcat and to make things easier in general you should create a simlink called tomcat to the full name of the tomcat folder with

ln -s /usr/local/apache-tomcat-5.5.20 /usr/local/tomcat

Here is what you need to change to /etc/profile under osx for tomcat/dspace

change PATH to include /usr/local/bin


then append

export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
export CATALINA_HOME=/usr/local/tomcat
export JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"

NOTE To edit /etc/profile - do the following

sudo emacs /etc/profile

don't be scared: use your arrow keys to move arround and use the apple-c apple-v keys to copy and paste
when you are finished use ctrl-x ctrl-s to save followed immediately by c-x c-c to quit

do the same

sudo emacs /usr/local/tomacat/conf/server.xml

to add the unicode support for tomcat (i.e. URIEncoding="UTF-8")
(the <Connector bit is a fair way down)

1. Create the DSpace user. This needs to be the same user that Tomcat will run. (do the same as you did for postgresql - but with the postgres user above/)

this is a good time to use 'fast user switching' to change to the dspace os x user.

2. Download the latest DSpace source code release and unpack it:

I'd download it to /Users/dspace/

tar -zxvf dspace-source-1.4.1.tar.gz

will create a folder /Users/dspace/dspace-source-1.4.1

I like to move it and create a symlink

mv /Users/dspace/dspace-source-1.4.1 /usr/local/
ln -s /usr/local/dspace-source-1.4.1 /usr/local/dsource

But thats just me.

3. Download the PostgreSQL JDBC driver from the postgresql site to


I rename it to postgresql.jar Do you need to?
Remember to get version 8.2 of PostgreSQL for JDBC2.

Move the JDBC driver to the DSpace source tree

mv /Users/dspace/postgresql.jar /usr/local/dsource/lib/

4. Create a dspace database, owned by the dspace PostgreSQL user:

/usr/local/bin/createuser -U postgres -d -A -P dspace
/usr/local/bin/createdb -U dspace -E UNICODE dspace

Enter a password for the DSpace database.

5. Edit dspace-source/config/dspace.cfg, in particular you'll need to set these properties:

dspace.url = http://localhost:8080/dspace
dspace.hostname = localhost = DSpace at my desk
db.password (the password you entered in the previous step)

6. Create the directory for the DSpace installation. As root, run:

sudo bash
mkdir /dspace
chown dspace /dspace

7. As the dspace OS X user, compile and install DSpace:

cd /usr/local/dsource
ant fresh_install

8. Copy the DSpace Web application archives (.war files) to the appropriate directory in your Tomcat/Jetty/Resin installation. For example:

cp /usr/local/dsource/build/*.war /usr/local/tomcat/webapps

9. Create an initial administrator account:


10. reStart Tomcat.

/usr/local/tomcat/bin/ (if http://localhost:8080/ tomcat is running)

Visit the base URL of your server, e.g. http://localhost:8080/dspace