DSpace

Customizations Quick Reference

See: DSpace How To Guide:
http://www.dspace.org/images/Training_Materials/dspacehowtoguide.pdf
DSpace 1.8 Manual
https://wiki.duraspace.org/display/DSDOC18

Back up before making changes!

It is important to remember when you have used ssh in to make changes to configuration or theme files
in dspace to make a backup of the existing file first. Either put the configuration files in a version control
system like git, or simply make a copy the file before making your change. By appending a date (or date
and time) to the backup file name, you can easily keep track of multiple changes. This is useful if you
dont immediately notice that your change broke something.
For example, before editing the dspace.cfg file as the dspace user, go into the correct directory, and
make a backup file
cd /usr/local/dspace/config
cp dspace.cfg dspace.cfg.bak.20120810

This example copied the dspace.cfg file to a file called dspace.cfg.bak.20120810 (the 20120810 being the
date of the change)

Locations for Customizations

Customizations
Primary Configuration settings
Label/Terms and Languages
modifications
Specify themes for particular
collections
Interface Themes
Default Reference Theme CSS
Default Reference Theme image
location
Text on home page
Change license users use when
submitting items (may not be
activated in submission process)
Custom submission forms
Text for System generated emails

Files
/usr/local/dspace/config/dspace.cfg
/usr/local/dspace/webapps/xmlui/i18n
/usr/local/dspace/config/xmlui.conf
/usr/local/dspace/webapps/xmlui/themes
/usr/local/dspace/webapps/xmlui/themes/Reference/lib/style.css
/usr/local/dspace/webapps/xmlui/themes/Reference/images
/usr/local/dspace/config/news-xmlui.xml
/usr/local/dspace/config/default.license

/usr/local/dspace/config/input-forms.xml
/usr/local/dspace/config/item-submission.xml
/usr/local/dspace/config/emails/

Other useful file locations

Tool/Resource

Location

Dspace command line management /usr/local/dspace/bin/dspace

tool
Digital Object Bitstreams
/usr/local/dspace/assetstore
Tomcat log files
/usr/local/dspace/log

Changing between Unix Users

In a unix system there are some commands that will let you either switch the currently logged in user to
a different one, or run a command as a different user.
To run a command with the elevated permissions of the root user, you use the command sudo followed
by the command you want to run as root. The user who is running the command must have sudo
privileges, which are granted when they are a member of the sudo group.
An example of how to use sudo follows. You can only restart the apache service as root, so a user who
has a user who has sudo privileges can run the following command to restart apache
sudo service apache2 restart

This command will prompt for the currently running users password, and once that is correctly entered,
run the service apache2 restart command as the root user.

Another userful command is su. This allows you to change your current user to another one. For
example the command
su - dspace

Will prompt for the dspace user password, and then log in as the dspace user. Now commands can be
run as dspace. Once that is done, typing
exit

will return the shell to the previously logged in user.

In the previous example, the indicates to run any login commands associated with the user. Also of
note is that if the currently logged in user is root, no password is needed for su.

The dspace User

The tomcat server that runs the dspace program is running as the unix dspace user. Due to this, the
dspace user needs read (and sometimes write) access to the various files in /usr/local/dspace where
the program and data live. When editing or uploading changes to configuration files it is recommended
that you do this as the dspace user to help avoid files ending up with the wrong permissions or file
ownership.

Unix vs dspace users

There is no connection between unix users on the system (i.e. user accounts that let you log in via ssh),
and dspace users (i.e. accounts that let you log into the dspace program via the web browser). Thus
users who need access to ssh in and access to the dspace system will need both a unix shell account and
a dspace account.

Restarting the dspace Process

Sometimes after making changes to configuration files in the dspace system you have to restart the
tomcat service for the changes to take effect. Generally, you can make changes to the css and templates
without a restart, but will for changes in the config directory. When restarting the server, make sure that
other users are not actively adding items, metadata, etc. to avoid interrupting their workflow.
When you restart the tomcat service, it can take a little while before it is active and accepting
connections. It is best practice to wait 20 seconds after a tomcat restart and then restart the apache
process to make sure the connector between tomcat and apache is functioning properly.
Service restarts need to be done by the root user, so this example will use sudo to gain the necessary
privileges. So to restart dspace, as a user who has sudo privileges run the following command:
sudo service tomcat6 restart && sleep 20 && sudo service apache2 restart

You will need to enter the unix password of the logged in user for the command to work.

Generating Thumbnails
When you add bitstreams, thumbnails and content indexing is performed asynchronously by the dspace
filter-media command attached to a cron task. By default, the cron task is set to run in the dspace users
crontab once a night. You can select a more frequent interval, but be careful that you dont have so
short an interval that runs overlap.
You can also run this process manually (for example, after you have loaded a batch of images, and you
want to see the thumbnails). To do this, as the dspace user, run:
/usr/local/dspace/bin/dspace filter-media

This will scan the collection for all unthumbnailed/unindexed images and process them.
If you change the thumbnail size in the dspace.cfg file, or for some other reason want to delete all the
thumbnails that were generated, you can run the following command to recreate them for all items. To
do this, as the dspace user, run:
/usr/local/dspace/bin/dspace filter-media -f

PostgreSQL Database
dspace uses the PostgreSQL database to store almost all of its information other than the bitstreams.
Usually, not much needs to be done with postgreSQL other than to make sure that it is running before

the tomcat server (that hosts dspace) starts. If necessary you can start, stop, or restart the postgresql
server by running the following command as a user who has sudo privleges
sudo service postgresql start

In this example the user started the postgresql server.

An important thing to note is that if you are doing a filesystem backup of the server, you wont
necessarily end up a backup of the database in a consistent state. You can make a manual backup of the
database with the following command as the dspace user:
pg_dump dspace > /home/dspace/dspace.sql

This creates a text file containing the SQL commands needed to recreate the dspace database in
/home/dspace/dspace.sql

Nightly cron jobs (Scheduled Tasks)

Several cron jobs have been created as part of the dspace installation. There are listed below for
reference. Notice that most of these commands are running the dspace command line tool to invoke
various tasks. You can run these tasks manually on the command line as the dspace user, and this is
often a useful way to either trigger the commands to meet an immediate need or for troubleshooting.
# Send out subscription e-mails at 01:00 every day
0 1 * * * /usr/local/dspace/bin/dspace sub-daily
# Run the media filter at 02:00 every day
0 2 * * * /usr/local/dspace/bin/dspace filter-media
# Run the checksum checker at 03:00
0 3 * * * /usr/local/dspace/bin/dspace checker -lp
# Mail the results to the sysadmin at 04:00
0 4 * * * /usr/local/dspace/bin/dspace checker-emailer -c
# Clean up the database nightly at 4.20am
20 4 * * * vacuumdb --analyze dspace > /dev/null 2>&1
# Run stat analysis
0 1 * * * /usr/local/dspace/bin/dspace stat-general
0 1 * * * /usr/local/dspace/bin/dspace stat-monthly
0 2 * * * /usr/local/dspace/bin/dspace stat-report-general
0 2 * * * /usr/local/dspace/bin/dspace stat-report-monthly