Ondřej Košarko edited this page Jan 5, 2018 · 35 revisions

Read Installation - Prerequisites before.

The following variables will be used in the following text:

export DSPACE_INSTANCE_NAME=repository
export DSPACE_SOURCE_DIRECTORY=/opt/repository/sources/dspace
export DSPACE_WORKSPACE=/opt/repository/workspace
export DSPACE_INSTALLATION_DIRECTORY=/opt/repository/installations

Note for upgrading from lindat-repository (previous version based on DSpace 1.8.2)

[Upgrading from lindat-repository](Upgrade From Lindat Repository) based on 1.8.2 version.

Note for Windows users

Windows users should read [this](Working on Windows).

Clone LINDAT DSpace from Git

Clone repository branch clarin for read-only access.

git clone -b clarin $DSPACE_SOURCE_DIRECTORY

Directory structure

You don't need to use workspace, it just creates symlinks for quicker navigation (to {config,scripts,..}). If you choose not to use is then do replace all mentions of $DSPACE_WORKSPACE/ with $DSPACE_SOURCE_DIRECTORY/utilities/project_helpers

cd $DSPACE_SOURCE_DIRECTORY/utilities/project_helpers

Update Configuration


We've provided a makefile to ease the compile/install/restart routines. Since our server configuration will likely differ from yours you should check it.

If the variables in $DSPACE_WORKSPACE/config/variable.makefile.example are not correct, copy the file to $DSPACE_WORKSPACE/config/variable.makefile and update them.

cp variable.makefile.example variable.makefile
vim variable.makefile

Most of the variables are self-explanatory, but the lindat-common related ones. See lindat-common to learn what that is.

Optionally create start/stop scripts to start/stop your server "stack" (apache, tomcat, postgres...) review $DSPACE_WORKSPACE/scripts/ and $DSPACE_WORKSPACE/scripts/ If you don't like what is in there create $DSPACE_WORKSPACE/scripts/ and $DSPACE_WORKSPACE/scripts/ of your own. You might want to check another examples in $DSPCAE_WORKSPACE/scripts/{start,stop}_stack_example.old

Update DSpace Configuration

Create a copy of distribution config file inside $DSPACE_WORKSPACE/sources/ and name it

cp $DSPACE_WORKSPACE/config/local.conf.dist $DSPACE_WORKSPACE/sources/

Update the file and provide the required values (list should be updated!):

See Configuration

Update Tomcat Configuration

Add the following configuration in the server.xml in your tomcat's conf dir (eg. /etc/tomcat6/server.xml). Inside the element Host.

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true" xmlValidation="false" xmlNamespaceAware="false">

        <Context path="/$DSPACE_INSTANCE_NAME/xmlui" docBase="$DSPACE_INSTALLATION_DIRECTORY/webapps/xmlui"
                       reloadable="true" cachingAllowed="false" allowLinking="true" />
        <Context path="/$DSPACE_INSTANCE_NAME/solr" docBase="$DSPACE_INSTALLATION_DIRECTORY/webapps/solr"
                       reloadable="true" cachingAllowed="false" allowLinking="true" />
        <Context path="/$DSPACE_INSTANCE_NAME/oai" docBase="$DSPACE_INSTALLATION_DIRECTORY/webapps/oai"
                       reloadable="true" cachingAllowed="false" allowLinking="true" />
        <Context path="/$DSPACE_INSTANCE_NAME/rest" docBase="$DSPACE_INSTALLATION_DIRECTORY/webapps/rest"
                       reloadable="true" cachingAllowed="false" allowLinking="true" />

Note: We could also create a tomcat virtual host (see section Multiple Instances Dspace), but our current configuration of DSpace Shibboleth login has problems with such a setup, so for now please use the above configuration instead.

Note 2: Ensure Tomcat runs with -Dfile.encoding=UTF8 and/or <Connector ... URIEncoding="UTF-8" />.

Note 3: With tomcat8 allowLinking and cachingAllowed are no longer attributes of Context see

Note 4: Some advise against defining Context in server.xml see

Update webserver Configuration

Make sure access to /xmlui/shibboleth-login requires a shibboleth session. For Apache add the following in the /etc/apache2/sites-enabled/https-tomcat6 (or ssl-dspace.conf) file inside the <VirtualHost> element in case your path is not caught by the LocationMatch.

<Location /$DSPACE_INSTANCE_NAME/xmlui/shibboleth-login>
        AuthType shibboleth
        ShibRequireSession On
        ShibUseHeaders On
        require valid-user

Create Databases

Create DSpace and Utilities Database

  • Create user dspace
  sudo -u postgres createuser --username=postgres --no-superuser --pwprompt dspace
  • Make sure the user can create databases
  • Create databases (skip this step if they already exist)
sudo make create_databases

Compilation and Deployment of DSpace

Set up prerequisities e.g. local libraries

This will install jars that can't be obtained via maven.

sudo make install_libs

Compile and deploy new DSpace instance

sudo make new_deploy

Run initialization scripts

First create an administrator for the dspace instance. Make sure to use the same email address with which you are registered on the Identity Provided, so that you have the administration rights when login through shibboleth.

sudo $DSPACE_INSTALLATION_DIRECTORY/bin/dspace create-administrator

Finally start/restart the server

  • If the server is not running
sudo make start
  • If the server is running
sudo make restart

Once the server starts the instance is ready to use.

Initialize the statistics (you already need solr running for these steps), we are still in the scripts directory.

sudo make init_statistics

Update discovery

sudo make update_discovery

Update OAI

sudo make update_oai

Add crontab cronjobs to update statistics and other indexes regularly. You might wish to inspect the makefile and add the jobs in your /etc/cron

make add_cronjobs

Redeploy DSpace

If any change is made to the local configuration and/or source code, redeploy needs to be done:

sudo make deploy

Other useful stuff

Important makefile targets

  • To only compile the code:
sudo make compile
  • To install the compiled code:
sudo make install
  • To compile and install at once:
sudo make deploy
  • If there are only configuration changes. You don't need to compile or deploy the whole dspace, use the following target and restart the server.
make update_config

Note: If you are using previous versions of ant then deploying/updating the application will not update the config files correctly. It will create config files with .new extension. Please update your ant version to 1.8 above.

sitemaps and SEO

You want to regenerate sitemaps periodically (the make add_cronjobs target handles this), you want to have sitemaps in your robots.txt

Sitemap: [dspace.url]/sitemap
Sitemap: [dspace.url]/htmlmap

You want a hidden link to the sitemap in your theme.

You want to have robots.txt available at the root of your domain, ie.

There are more details in dspace wiki

Handle server

If you will be running your own handle server check that chapter in the prerequisites or follow the official guide

Restore a database

sudo make restore_database

Repeated tasks

Investigate the makefile's add_cronjobs target to learn what tasks need to be run periodicallly.

Note: Sitemaps are regenerated periodically but make sure you have at least one collection (or you'll be getting NullPointerExceptions).

Start/Stop/Restart the servers

Start/Restart/Stop all servers (defined in scripts/{start,stop}

sudo make start
sudo make restart
sudo make stop


The last compilation or installation logs can be accesses in the directory $DSPACE_WORSKPACE/logs

The repository logs are in $DSPACE_INSTALLATION_DIRECTORY/log

Multiple Instances Dspace

To create multiple dspace instances on the same server with single tomcat, we can use the name based virtual hosts. Add the following in /etc/tomcat/server.xml to create a new virtual host.

  • Be sure that the defaultHost from matches name in <Host*>
        <Host name="localhost/$DSPACE_INSTANCE_NAME" debug="0" 
                autoDeploy="true" unpackWARs="true">

                <Valve className="org.apache.catalina.valves.AccessLogValve"

                <Context path="/xmlui" docBase="$DSPACE_INSTALLATION_DIRECTORY/webapps/xmlui"
                        reloadable="true" cachingAllowed="false"
                <Context path="/wiki-test/solr" docBase="$DSPACE_INSTALLATION_DIRECTORY/webapps/solr"
                        reloadable="true" cachingAllowed="false" allowLinking="true" />

Additional changes to the installed server

  • go through the webserver/tomcat/shibboleth sections in Prerequisites if you haven't already
  • to run programs from control panel
    • aptitude install python-dateutil python-lxml
    • if you are getting errors while running the programs check the JAVA_OPTS you are passing to (redmine 551)
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.