Page History

...

...

1. Install all the Backend Requirements listed above.

2. Create a DSpace operating system user (optional) .  As noted in the prerequisites above, Tomcat (or Jetty, etc) must run as an operating system user account that has full read/write access to the DSpace installation directory (i.e. [dspace]).  Either you must ensure the Tomcat owner also owns [dspace], OR you can create a new "dspace" user account, and ensure that Tomcat also runs as that account:

   Code Block
   useradd -m dspace

   The choice that makes the most sense for you will probably depend on how you installed your servlet container (Tomcat/Jetty/etc).  If you installed it from source, you will need to create a user account to run it, and that account can be named anything, e.g. 'dspace'.  If you used your operating system's package manager to install the container, then a user account should have been created as part of that process and it will be much easier to use that account than to try to change it.

3. Download the latest DSpace release from the DSpace GitHub Repository. You can choose to either download the zip or tar.gz file provided by GitHub, or you can use "git" to checkout the appropriate tag (e.g. dspace-9.0) or branch.
4. Unpack the DSpace software. After downloading the software, based on the compression file format, choose one of the following methods to unpack your software:
   

   1. Zip file. If you downloaded dspace-9.0.zip do the following:

      Code Block
      unzip dspace-9.0.zip

      
      

   2. .gz file. If you downloaded dspace-9.0.tar.gz do the following:

      Code Block
      gunzip -c dspace-9.0.tar.gz | tar -xf -

      For ease of reference, we will refer to the location of this unzipped version of the DSpace release as [dspace-source] in the remainder of these instructions. After unpacking the file, the user may wish to change the ownership of the dspace-9.x folder to the "dspace" user. (And you may need to change the group).

5. Database Setup for PostgreSQL:
   

   • Create a dspace database user (this user can have any name, but we'll assume you name it "dspace"). This is entirely separate from the dspace operating-system user created above:

     Code Block
     createuser --username=postgres --no-superuser --pwprompt dspace

     You will be prompted (twice) for a password for the new dspace user.  Then you'll be prompted for the password of the PostgreSQL superuser (postgres).

   • Create a dspace database, owned by the dspace PostgreSQL user. Similar to the previous step, this can only be done by a "superuser" account in PostgreSQL (e.g. postgres):

     Code Block
     createdb --username=postgres --owner=dspace --encoding=UNICODE dspace

     You will be prompted for the password of the PostgreSQL superuser (postgres).

6. Initial Configuration (local.cfg):  Create your own [dspace-source]/dspace/config/local.cfg configuration file.  You may wish to simply copy the provided [dspace-source]/dspace/config/local.cfg.EXAMPLE. This local.cfg file can be used to store any configuration changes that you wish to make which are local to your installation (see local.cfg configuration file documentation). ANY setting may be copied into this local.cfg file from the dspace.cfg or any other *.cfg file in order to override the default setting (see note below).  For the initial installation of DSpace, there are some key settings you'll likely want to override.  Those are provided in the [dspace-source]/dspace/config/local.cfg.EXAMPLE. (NOTE: Settings followed with an asterisk (*) are highly recommended, while all others are optional during initial installation and may be customized at a later time.)
   
   • dspace.dir* - must be set to the [dspace] (installation) directory  (NOTE: On Windows be sure to use forward slashes for the directory path!  For example: "C:/dspace" is a valid path for Windows.)
   • dspace.server.url* - complete URL of this DSpace backend (including port and any subpath).  Do not end with '/'.  For example: http://localhost:8080/server
   • dspace.ui.url* - complete URL of the DSpace frontend (including port and any subpath). REQUIRED for the REST API to fully trust requests from the DSpace frontend.  Do not end with '/'. For example: http://localhost:4000
   • dspace.name - Human-readable, "proper" name of your server, e.g. "My Digital Library".
   • solr.server* - complete URL of the Solr server. DSpace makes use of Solr for indexing purposes.  http://localhost:8983/solr unless you changed the port or installed Solr on some other host.
   • default.language - Default language for all metadata values (defaults to "en_US")
   • db.url* - The full JDBC URL to your database (examples are provided in the local.cfg.EXAMPLE)

   • db.driver* - Which database driver to use for PostgreSQL (default should be fine)

   • db.dialect* - Which database dialect to use for PostgreSQL (default should be fine)
   • db.username* - the database username used in the previous step.
   • db.password* - the database password used in the previous step.
   • db.schema* - the database schema to use (examples are provided in the local.cfg.EXAMPLE)
   • mail.server - fully-qualified domain name of your outgoing mail server.
   • mail.from.address - the "From:" address to put on email sent by DSpace.
   • feedback.recipient - mailbox for feedback mail.
   • mail.admin - mailbox for DSpace site administrator.
   • alert.recipient - mailbox for server errors/alerts (not essential but very useful!)

   • registration.notify- mailbox for emails when new users register (optional)

     Info
     title Your local.cfg file can override ANY settings from other *.cfg files in DSpace
     The provided local.cfg.EXAMPLE only includes a small subset of the configuration settings available with DSpace. It provides a good starting point for your own local.cfg file. However, you should be aware that ANY configuration can now be copied into your local.cfg to override the default settings.  This includes ANY of the settings/configurations in: The primary dspace.cfg file ([dspace]/config/dspace.cfg) Any of the module configuration files ([dspace]/config/modules/*.cfg files) Any of the Spring Boot settings ([dspace-src]/dspace-server-webapp/src/main/resources/application.properties) Individual settings may also be commented out or removed in your local.cfg, in order to re-enable default settings. See the Configuration Reference section for more details.

     
     

7. DSpace Directory: Create the directory for the DSpace backend installation (i.e. [dspace]). As root (or a user with appropriate permissions), run:

   Code Block
   mkdir [dspace] chown dspace [dspace]

   (Assuming the dspace UNIX username.)

8. Build the Installation Package: As the dspace UNIX user, generate the DSpace installation package.

   Code Block
   cd [dspace-source] mvn package

   
   

9. Install DSpace Backend: As the dspace UNIX user, install DSpace to [dspace]:

   Code Block
   cd [dspace-source]/dspace/target/dspace-installer ant fresh_install

   
   

   Info
   To see a complete list of build targets, run: ant help The most likely thing to go wrong here is the test of your database connection. See the Common Installation Issues Section below for more details.

   
   

10. Initialize your Database: While this step is optional (as the DSpace database should auto-initialize itself on first startup), it's always good to verify one last time that your database connection is working properly.  To initialize the database run:

    Code Block
    [dspace]/bin/dspace database migrate

    1. After running this script, it's a good idea to run "./dspace database info" to check that your database has been fully initialized.  A fully initialized database should list the state of all migrations as either "Success" or "Out of Order".  If any migrations have failed or are still listed as "Pending", then you need to check your "dspace.log" for possible "ERROR" messages.  If any errors appeared, you will need to resolve them before continuing.

11. Copy Solr cores:  DSpace installation creates a set of six empty Solr cores already configured. 

    1. Copy them from [dspace]/solr to the place where your Solr instance will discover them. For example:

       Code Block

       # [solr] is the location where Solr is installed. # NOTE: On Debian systems the configsets may be under /var/solr/data/configsets cp -R [dspace]/solr/* [solr]/server/solr/configsets # Make sure everything is owned by the system user who owns Solr # Usually this is a 'solr' user account # See https://solr.apache.org/guide/8_1solr/9_8/deployment-guide/taking-solr-to-production.html#create-the-solr-user chown -R solr:solr [solr]/server/solr/configsets

       
       

    2. Start (or re-start) Solr.  For example:

       Code Block
       language bash
       [solr]/bin/solr restart

        

    3. You can check the status of Solr and your new DSpace cores by using its administrative web interface.  Browse to ${solr.server} (e.g. http://localhost:8983/solr/) to see if Solr is running well, then look at the cores by selecting (on the left) Core Admin or using the Core Selector drop list.

       1. For example, to test that your "search" core is setup properly, try accessing the URL ${solr.server}/search/select. It should run an empty query against the "search" core, returning an empty JSON result. If it returns an error, then that means your "search" core is missing or not installed properly.
12. Deploy web application
    We have different possibilities in this case:
    • Deploy web application to Tomcat (traditional installation): The DSpace backend consists of a single "server" webapp (in [dspace]/webapps/server).  You need to deploy this webapp into your Servlet Container (e.g. Tomcat).  Generally, there are two options (or techniques) which you could use...either configure Tomcat to find the DSpace "server" webapp, or copy the "server" webapp into Tomcat's own webapps folder.

      • Technique A. Tell your Tomcat/Jetty/Resin installation where to find your DSpace web application(s). As an example, in the directory [tomcat]/conf/Catalina/localhost you could add files similar to the following (but replace [dspace]with your installation location):

        Code Block
        title DEFINE A CONTEXT PATH FOR DSpace Server webapp: server.xml
        <?xml version='1.0'?> <Context docBase="[dspace]/webapps/server"/>

        The name of the file (not including the suffix ".xml") will be the name of the context, so for example server.xml defines the context at http://host:8080/server.  To define the root context (http://host:8080/), name that context's file ROOT.xml.   Optionally, you can also choose to install the old, deprecated "rest" webapp if you

      • Technique B. Simple and complete. You copy only (or all) of the DSpace Web application(s) you wish to use from the [dspace]/webapps directory to the appropriate directory in your Tomcat/Jetty/Resin installation. For example:
        cp -R [dspace]/webapps/* [tomcat]/webapps (This will copy all the web applications to Tomcat).
        cp -R [dspace]/webapps/server [tomcat]/webapps (This will copy only the Server web application to Tomcat.)

        To define the root context (http://host:8080/), name that context's directory ROOT.

    • Deploy Runnable JAR application (NEW) : The DSpace backend now builds a Runnable JAR application made with SpringBoot.  After building DSpace, a new "server-boot.jar" will be available at [dspace]/webapps/server-boot.jar. This JAR file contains the entire "server" webapp, embedded Tomcat, and the "dspace.dir" configuration made during the build phase. You can execute this JAR with the following command:

      Code Block
      language bash title Server-boot execution
      java -jar [dspace]/webapps/server-boot.jar

      By running it, the server will boot with the configuration that you've made during the build phase. There are optional parameters that you can use to override the build values:

      • spring.config.location - reference to the application.properties file to use

        Code Block
        --spring.config.location=file:///path/to/target/application.properties

        
        

      • dspace.dir - reference to the installation directory of the application, ( default value in application.properties )

        Code Block
        --dspace.dir=/path/to/install/folder

        
        

      • logging.config - log configuration file of the project ( default value in application.properties )

        Code Block
        --logging.config=file:///path/to/target/file/log2.xml

        
        

      • These are only the main ones, obviously , you can override every property that can be found inside the configuration files just by appending it as argument of the execution command, just like this: --[prop]=[value].  Or you may choose to use Environment Variable overriding as described in the Configuration Reference

13. Create an Administrator Account:  Create an initial administrator account from the command line:

    Code Block
    [dspace]/bin/dspace create-administrator

    
    

14. Initial Startup!  Now the moment of truth! Start up (or restart) Tomcat/Jetty/Resin.
    
    1. REST API Interface - (e.g.)  http://dspace.myu.edu:8080/server/
    2. OAI-PMH Interface - (e.g.)  http://dspace.myu.edu:8080/server/oai/request?verb=Identify
    3. For an example of what the default backend looks like, visit the Demo Backend: https://demo.dspace.org/server/
15. Setup scheduled tasks for behind-the-scenes processes: For all features of DSpace to work properly, there are some scheduled tasks you MUST setup to run on a regular basis. Some examples are tasks that help create thumbnails (for images), do full-text indexing (of textual content) and send out subscription emails.  See the Scheduled Tasks via Cron for more details.
16. Production Installation (adding HTTPS support): Running the DSpace Backend on HTTP & port 8080 is only usable for local development environments (where you are running the UI and REST API from the same machine, and only accessing them via localhost URLs).  If you want to run DSpace in Production, you MUST run the backend with HTTPS support (otherwise logins will not work outside of your local domain).
    1. For HTTPS support, we recommend installing either Apache HTTPD or Nginx, configuring SSL at that level, and proxying all requests to your Tomcat installation (or Runnable JAR).  Keep in mind, if you want to host both the DSpace Backend and Frontend on the same server, you can use one installation of Apache HTTPD or NGinx to manage HTTPS/SSL and proxy to both.
    2. Apache HTTPD: These instructions are specific to Apache HTTPD, but a similar setup can be achieved with NGinx (see below)
       1. Install Apache HTTPD, e.g. sudo apt install apache2
       2. Install mod_headers, mod_proxy and mod_proxy_ajp (or mod_proxy_http) modules, e.g. sudo a2enmod headers; sudo a2enmod proxy; sudo a2enmod proxy_ajp

          1. Alternatively, you can choose to use mod_proxy_http to create an http proxy.  A separate example is commented out below

       3. For mod_proxy_ajp to communicate with Tomcat, you'll need to enable Tomcat's AJP connector in your Tomcat's server.xml:

          Code Block
          <Connector protocol="AJP/1.3" port="8009" redirectPort="8443" URIEncoding="UTF-8" />

          
          

       4. Restart Apache to enable these modules
       5. Obtain an SSL certificate for HTTPS support. If you don't have one yet, you can use Let's Encrypt (for free) using the "certbot" tool: https://certbot.eff.org/ 

       6. Now, setup a new VirtualHost for your site (using HTTPS / port 443) which proxies all requests to Tomcat's AJP connector (running on port 8009)

          Code Block

          <VirtualHost _default_:443> # Add your domain here. We've added "my.dspace.edu" as an example ServerName my.dspace.edu   .. setup your host how you want, including log settings...     .. setup your host how you want, including log settings... # Most installs will need these options enabled to ensure DSpace knows its hostname and scheme (http or https) # Also required to ensure correct sitemap URLs appear in /robots.txt for User Interface.    ProxyPreserveHost On RequestHeader set X-Forwarded-Proto https    SSLEngine on    SSLCertificateFile [full-path-to-PEM-cert] SSLCertificateKeyFile [full-path-to-cert-KEY] # LetsEncrypt certificates (and possibly others) may require a chain file be specified # in order for the UI / Node.js to validate the HTTPS connection. #SSLCertificateChainFile [full-path-to-chain-file] # Proxy all HTTPS requests to "/server" from Apache to Tomcat via AJP connector ProxyPass /server ajp://localhost:8009/server ProxyPassReverse /server ajp://localhost:8009/server # If you would rather use mod_proxy_http as an http proxy to port 8080 # then use these settings instead #ProxyPass /server http://localhost:8080/server    #ProxyPassReverse /server http://localhost:8080/server </VirtualHost>

          
          

    3. NGinx:  These instructions are specific to NGinx.  
       1. Install/Setup NGinx

       2. Sample NGinx "server block" configuration. Keep in mind we are only providing basic example settings.

          Code Block

          # Setup HTTP to redirect to HTTPS server { listen 80;  # Add your domain here. We've added "my.dspace.edu" as an example server_name my.dspace.edu; rewrite ^ https://my.dspace.edu permanent; } # Setup HTTPS access server { listen 443 ssl;  # Add your domain here. We've added "my.dspace.edu" as an example server_name my.dspace.edu; # Add your SSL certificate/key path here # NOTE: For LetsEncrypt, the certificate should be the full certificate chain file ssl_certificate my.dspace.edu.crt (or PEM); ssl_certificate_key my.dspace.edu.key; # Proxy all HTTPS requests to "/server" from NGinx to Tomcat on port 8080 location /server { proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-Host $host; proxy_pass http://localhost:8080/server; } }

          
          

    4. After switching to HTTPS, make sure to go back and update the URLs (primarily dspace.server.url) in your local.cfg to match the new URL of your backend (REST API).  This will require briefly rebooting Tomcat.

...

...