Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Content Zone
locationtop
stylesquare

UNIX-like OS or Microsoft Windows

  • UNIX-like operating system (Linux, HP/UX, Mac OSX, etc.) : Many distributions of Linux/Unix come with some of the dependencies below pre-installed or easily installed via updates.  You should consult your particular distribution's documentation or local system administrators to determine what is already available.
  • Microsoft Windows:  While DSpace can be run on Windows servers, most institutions tend to run it on a UNIX-like operating system.


Java JDK 11 or 17 (OpenJDK or Oracle JDK)

Info

JDK17 support was first available in DSpace 7.2.  DSpace 7.1 or 7.0 only supported JDK 11.

Info
titleMake sure to install the JDK and not just the JRE

DSpace requires the full JDK (Java Development Kit) be installed, rather than just the JRE (Java Runtime Environment).  So, please be sure that you are installing the full JDK and not just the JRE.


Note
titleOnly JDK11 and JDK 17 are fully supported

Older versions of Java are unsupported. This includes JDK v7-10.

Newer versions of Java may work (e.g. JDK v12-16), but we do not recommend running them in Production.  We highly recommend running only Java LTS (Long Term Support) releases in Production, as non-LTS releases may not receive ongoing security fixes. As of this DSpace release, JDK11 and JDK 17 are the two most recent Java LTS releases.  As soon as the next Java LTS release is available, we will analyze it for compatibility with this release of DSpace.  For more information on Java releases, see the Java roadmaps for Oracle and/or OpenJDK.


Apache Maven 3.3.x or above (Java build tool)

Info

We recommend using the most recent version of Maven that you can, as newer releases may include performance improvements and security updates.  Maven 3.8.x and 3.6.x are known to work well.

Maven is necessary in the first stage of the build process to assemble the installation package for your DSpace instance. It gives you the flexibility to customize DSpace using the existing Maven projects found in the [dspace-source]/dspace/modules directory or by adding in your own Maven project to build the installation package for DSpace, and apply any custom interface "overlay" changes.

Maven can be downloaded from http://maven.apache.org/download.html   It is also provided via many operating system package managers.

Configuring a Maven Proxy

You can configure a proxy to use for some or all of your HTTP requests in Maven. The username and password are only required if your proxy requires basic authentication (note that later releases may support storing your passwords in a secured keystore‚ in the meantime, please ensure your settings.xml file (usually ${user.home}/.m2/settings.xml) is secured with permissions appropriate for your operating system).

Example:

Code Block
<settings>
  .
  .
  <proxies>
   <proxy>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.somewhere.com</host>
      <port>8080</port>
      <username>proxyuser</username>
      <password>somepassword</password>
      <nonProxyHosts>www.google.com|*.somewhere.com</nonProxyHosts>
    </proxy>
  </proxies>
  .
  .
</settings>


Apache Ant 1.10.x or later (Java build tool)

Info

While Apache Ant recommends using v1.10.x for Java 11, we've also had some success with recent versions of 1.9.x (specifically v1.9.15 seems to work fine with Java 11). That said, earlier versions of v1.9.x are not compatible with Java 11.

Apache Ant is required for the second stage of the build process (deploying/installing the application). First, Maven is used to construct the installer ([dspace-source]/dspace/target/dspace-installer), after which Ant is used to install/deploy DSpace to the installation directory.

Ant can be downloaded from the following location: http://ant.apache.org   It is also provided via many operating system package managers.

Relational Database (PostgreSQL)

PostgreSQL 12.x, 13.x, 14.x or 15.x (with pgcrypto installed)
  • PostgreSQL can be downloaded from http://www.postgresql.org/.  It is also provided via many operating system package managers.
  • Install the pgcrypto extension.  It will also need to be enabled on your DSpace Database (see Installation instructions below for more info). The pgcrypto extension allows DSpace to create UUIDs (universally unique identifiers) for all objects in DSpace, which means that (internal) object identifiers are now globally unique and no longer tied to database sequences.
    • On most Linux operating systems (Ubuntu, Debian, RedHat), this extension is provided in the "postgresql-contrib" package in your package manager. So, ensure you've installed "postgresql-contrib".
    • On Windows, this extension should be provided automatically by the installer (check your "[PostgreSQL]/share/extension" folder for files starting with "pgcrypto")
  • Unicode (specifically UTF-8) support must be enabled (but this is enabled by default).
  • Once installed, you need to enable TCP/IP connections (DSpace uses JDBC):
    • In postgresql.conf: uncomment the line starting: listen_addresses = 'localhost'.  This is the default, in recent PostgreSQL releases, but you should at least check it.
    • Then tighten up security a bit by editing pg_hba.conf and adding this line:

      Code Block
      host dspace dspace 127.0.0.1 255.255.255.255 md5

      This should appear before any lines matching all databases, because the first matching rule governs.

    • Then restart PostgreSQL.
Oracle (UNSUPPORTED AS OF 7.6)
Warning
titleAs of the 7.6 release, Oracle databases are no longer supported

Oracle support has been removed as was previously announced in March 2022 on our mailing lists.  See https://github.com/DSpace/DSpace/issues/8214

All DSpace sites should now use PostrgreSQL (see above)

  • Details on acquiring Oracle can be downloaded from the following location: http://www.oracle.com/database/. You will need to create a database for DSpace. Make sure that the character set is one of the Unicode character sets. DSpace uses UTF-8 natively, and it is suggested that the Oracle database use the same character set. You will also need to create a user account for DSpace (e.g. dspace) and ensure that it has permissions to add and remove tables in the database. Refer to the Quick Installation for more details.
    • NOTE: If the database server is not on the same machine as DSpace, you must install the Oracle client to the DSpace server and point tnsnames.ora and listener.ora files to the database the Oracle server.

Apache Solr 8.x (full-text index/search service)

Warning

Solr 8.11.1 or above is recommended as all prior 8.x releases are vulnerable to CVE-2021-44228 (log4j critical vulnerability). If you must use a prior version of 8.x, make sure to add "-Dlog4j2.formatMsgNoLookups=true" to your SOLR_OPTS environment variable, see https://solr.apache.org/security.html#apache-solr-affected-by-apache-log4j-cve-2021-44228


Note

Solr 9 is not yet fully supported, but can be used provided that you make minor modification to the out-of-the-box "search/conf/solrconfig.xml" that comes with DSpace 7.  See this below comment for details.


Note

Make sure to install Solr with Authentication disabled (which is the default).  DSpace does not yet support authentication to Solr (see https://github.com/DSpace/DSpace/issues/3169).  Instead, we recommend placing Solr behind a firewall and/or ensuring port 8983 (which Solr runs on) is not available for public/anonymous access on the web. Solr only needs to be accessible to requests from the DSpace backend.

Solr can be obtained at the Apache Software Foundation site for Lucene and Solr.  You may wish to read portions of the quick-start tutorial to make yourself familiar with Solr's layout and operation.  Unpack a Solr .tgz or .zip archive in a place where you keep software that is not handled by your operating system's package management tools, and arrange to have it running whenever DSpace is running.  You should ensure that Solr's index directories will have plenty of room to grow.  You should also ensure that port 8983 is not in use by something else, or configure Solr to use a different port.

If you are looking for a good place to put Solr, consider /opt or /usr/local.  You can simply unpack Solr in one place and use it.  Or you can configure Solr to keep its indexes elsewhere, if you need to – see the Solr documentation for how to do this.

It is not necessary to dedicate a Solr instance to DSpace, if you already have one and want to use it.  Simply copy DSpace's cores to a place where they will be discovered by Solr.  See below.

Servlet Engine (Apache Tomcat 9, Jetty, Caucho Resin or equivalent)

Note

Only Tomcat 9 is supported at this time. Tomcat 10 is incompatible with Tomcat 9 and will not be supported until DSpace 8.0 at the earliest.  See https://github.com/DSpace/DSpace/issues/8713 for more details

  • Apache Tomcat 9. Tomcat can be downloaded from the following location: http://tomcat.apache.org.    It is also provided via many operating system package managers.
    • The Tomcat owner (i.e. the user that Tomcat runs as) must have read/write access to the DSpace installation directory (i.e. [dspace])There are a few common ways this may be achieved:
      • One option is to specifically give the Tomcat user (often named "tomcat") ownership of the [dspace] directories, for example:

        Code Block
        # Change [dspace] and all subfolders to be owned by "tomcat"
        chown -R tomcat:tomcat [dspace]


      • Another option is to have Tomcat itself run as a new user named "dspace" (see installation instructions below).  Some operating systems make modifying the Tomcat "run as" user easily modifiable via an environment variable named TOMCAT_USER.  This option may be more desirable if you have multiple Tomcat instances running, and you do not want all of them to run under the same Tomcat owner.
    • On Debian systems, you may also need to modify or override the "tomcat.service" file to specify the DSpace installation directory in the list of ReadWritePaths.  For example:

      Code Block
      # Replace [dspace] with the full path of your DSpace install
      ReadWritePaths=[dspace]


    • You need to ensure that Tomcat a) has enough memory to run DSpace, and b) uses UTF-8 as its default file encoding for international character support. So ensure in your startup scripts (etc) that the following environment variable is set: JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"
    • Modifications in [tomcat]/conf/server.xml : You also need to alter Tomcat's default configuration to support searching and browsing of multi-byte UTF-8 correctly. You need to add a configuration option to the <Connector> element in [tomcat]/config/server.xml: URIEncoding="UTF-8" e.g. if you're using the default Tomcat config, it should read:

      Code Block
      languagehtml/xml
      <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
      <Connector port="8080"
                    minSpareThreads="25"
                    enableLookups="false"
                    redirectPort="8443"
                    connectionTimeout="20000"
                    disableUploadTimeout="true"
                    URIEncoding="UTF-8"/>
      

      You may change the port from 8080 by editing it in the file above, and by setting the variable CONNECTOR_PORT in server.xml.  You should set the URIEncoding even if you are running Tomcat behind a reverse proxy (Apache HTTPD, Nginx, etc.) via AJP.

  • Jetty or Caucho Resin 
    • DSpace 7 has not been tested with Jetty or Caucho Resin, after the switch to Java 11
    • Older versions of DSpace were able to run on a Tomcat-equivalent servlet Engine, such as Jetty (https://www.eclipse.org/jetty/) or Caucho Resin (http://www.caucho.com/). If you choose to use a different servlet container, please ensure that it supports Servlet Spec 3.1 (or above).
    • Jetty and Resin are configured for correct handling of UTF-8 by default.

(Optional) IP to City Database for Location-based Statistics

Optionally, if you wish to record the geographic locations of clients in DSpace usage statistics records, you will need to install (and regularly update) one of the following:

  • Either, a copy of MaxMind's GeoLite City database (in MMDB format)
    • NOTE: Installing MaxMind GeoLite2 is free.  However, you must sign up for a (free) MaxMind account in order to obtain a license key to use the GeoLite2 database.
    • You may download GeoLite2 directly from MaxMind, or many Linux distributions provide the geoipupdate tool directly via their package manager.  You will still need to configure your license key prior to usage.
    • Once the "GeoLite2-City.mmdb" database file is installed on your system,  you will need to configure its location as the value of usage-statistics.dbfile in your local.cfg configuration file
    • See the "Managing the City Database File" section of SOLR Statistics for more information about using a City Database with DSpace.
  • Or, you can alternatively use/install DB-IP's City Lite database (in MMDB format)
    • This database is also free to use, but does not require an account to download.
    • Once the "dbip-city-lite.mmdb" database file is installed on your system,  you will need to configure its location as the value of usage-statistics.dbfile in your local.cfg configuration file
    • See the "Managing the City Database File" section of SOLR Statistics for more information about using a City Database with DSpace.

Git (code version control)

Currently, there is a known bug in DSpace where a third-party Maven Module expects git to be available (in order to support the ./dspace version commandline tool).  We are working on a solution within this ticket: https://github.com/DSpace/DSpace/issues/6772

For the time being, you can work around this problem by installing Git locally: https://git-scm.com/downloads

Backend Installation

  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-7.2) 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-7.2.zip do the following:

      Code Block
      unzip dspace-7.2.zip


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

      Code Block
      gunzip -c dspace-7.2.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-7.x folder to the "dspace" user. (And you may need to change the group).

  5. Database Setup
    • 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).

      • Finally, you MUST enable the pgcrypto extension on your new dspace database.  Again, this can only be enabled by a "superuser" account (e.g. postgres)

        Code Block
        # Login to the database as a superuser, and enable the pgcrypto extension on this database
        psql --username=postgres dspace -c "CREATE EXTENSION pgcrypto;"

        The "CREATE EXTENSION" command should return with no result if it succeeds. If it fails or throws an error, it is likely you are missing the required pgcrypto extension (see Database Prerequisites above).

        • Alternative method: How to enable pgcrypto via a separate database schema. While the above method of enabling pgcrypto is perfectly fine for the majority of users, there may be some scenarios where a database administrator would prefer to install extensions into a database schema that is separate from the DSpace tables. Developers also may wish to install pgcrypto into a separate schema if they plan to "clean" (recreate) their development database frequently. Keeping extensions in a separate schema from the DSpace tables will ensure developers would NOT have to continually re-enable the extension each time you run a "./dspace database clean". If you wish to install pgcrypto in a separate schema here's how to do that:

          Code Block
          # Login to the database as a superuser
          psql --username=postgres dspace
          # Create a new schema in this database named "extensions" (or whatever you want to name it)
          CREATE SCHEMA extensions;
          # Enable this extension in this new schema
          CREATE EXTENSION pgcrypto SCHEMA extensions;
          # Grant rights to call functions in the extensions schema to your dspace user
          GRANT USAGE ON SCHEMA extensions TO dspace;
          
          
          # Append "extensions" on the current session's "search_path" (if it doesn't already exist in search_path)
          # The "search_path" config is the list of schemas that Postgres will use
          SELECT set_config('search_path',current_setting('search_path') || ',extensions',false) WHERE current_setting('search_path') !~ '(^|,)extensions(,|$)';
          # Verify the current session's "search_path" and make sure it's correct
          SHOW search_path;
          # Now, update the "dspace" Database to use the same "search_path" (for all future sessions) as we've set for this current session (i.e. via set_config() above)
          ALTER DATABASE dspace SET search_path FROM CURRENT;


    • Oracle (UNSUPPORTED AS OF 7.6):
      • Setting up DSpace to use Oracle is a bit different now. You will need still need to get a copy of the Oracle JDBC driver, but instead of copying it into a lib directory you will need to install it into your local Maven repository. (You'll need to download it first from this location: http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html.) Run the following command (all on one line):

        Code Block
        mvn install:install-file
            -Dfile=ojdbc6.jar
            -DgroupId=com.oracle
            -DartifactId=ojdbc6
            -Dversion=11.2.0.4.0
            -Dpackaging=jar
            -DgeneratePom=true
        


      • You need to compile DSpace with an Oracle driver (ojdbc6.jar) corresponding to your Oracle version - update the version in [dspace-source]/pom.xml  E.g.:

        Code Block
        languagehtml/xml
        <dependency>
          <groupId>com.oracle</groupId>
          <artifactId>ojdbc6</artifactId>
          <version>11.2.0.4.0</version>
        </dependency>
        


      • Create a database for DSpace. Make sure that the character set is one of the Unicode character sets. DSpace uses UTF-8 natively, and it is required that the Oracle database use the same character set. Create a user account for DSpace (e.g. dspace) and ensure that it has permissions to add and remove tables in the database.
      • NOTE: You will need to ensure the proper db.* settings are specified in your local.cfg file (see next step), as the defaults for all of these settings assuming a PostgreSQL database backend.

        Code Block
        db.url = jdbc:oracle:thin:@host:port/SID
        # e.g. db.url = jdbc:oracle:thin:@//localhost:1521/xe
        # NOTE: in db.url, SID is the SID of your database defined in tnsnames.ora
        # the default Oracle port is 1521
        # You may also use a full SID definition, e.g.
        # db.url = jdbc:oracle:thin:@(description=(address_list=(address=(protocol=TCP)(host=localhost)(port=1521)))(connect_data=(service_name=DSPACE)))
        
        # Oracle driver and dialect
        db.driver = oracle.jdbc.OracleDriver
        db.dialect = org.hibernate.dialect.Oracle10gDialect
        
        # Specify DB username, password and schema to use
        db.username =
        db.password =
        db.schema = ${db.username}
        # For Oracle, schema is equivalent to the username of your database account,
        # so this may be set to ${db.username} in most scenarios


      • Later, during the Maven build step, don't forget to specify mvn -Ddb.name=oracle package

  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
      titleYour 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
    


    Info
    titleBuilding with Oracle Database Support (UNSUPPORTED AS OF 7.6)

    Without any extra arguments, the DSpace installation package is initialized for PostgreSQL. If you want to use Oracle instead, you should build the DSpace installation package as follows:
    mvn -Ddb.name=oracle 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. Deploy Server web application: 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
      titleDEFINE 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.

  12. Optionally, also install the deprecated DSpace 6.x REST API web application.  If you previously used the DSpace 6.x REST API, for backwards compatibility the old, deprecated "rest" webapp is still available to install (in [dspace]/webapps/rest). It is NOT used by the DSpace frontend.  So, most users should skip this step.
  13. Copy Solr cores:  DSpace installation creates a set of four 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_1/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
      languagebash
      [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.
  14. Create an Administrator Account:  Create an initial administrator account from the command line:

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


  15. 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/
  16. 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.
  17. 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.  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.

...