Versions Compared

Old Version 159

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 160

changes.mady.by.user Tim Donohue

Saved on

Key

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

...

  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:

      • 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, based on whether you are using PostgreSQL or Oracle
    • db.dialect* - Which database dialect to use, based on whether you are using PostgreSQL or Oracle
    • 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

    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://api7.dspace.org/server/
  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.  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. These instructions are specific to Apache HTTPD, but a similar setup can be achieved with Nginx
      1. Install Apache HTTPD, e.g. sudo apt install apache2
      2. Install the mod_proxy and mod_proxy_ajp modules, e.g. 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. Restart Apache to enable

      4. 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" />


      5. 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...

    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
    # When using mod_proxy_http, you need to also ensure the X-Forwarded-Proto header is sent
    # to tell DSpace it is behind HTTPS, otherwise some URLs may continue to use HTTP 
    # (requires installing/enabling mod_headers)
    #RequestHeader set X-Forwarded-Proto https
</VirtualHost>


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

...

  1. Download Code (to [dspace-angular]): Download the latest dspace-angular 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.
    1. NOTE: For the rest of these instructions, we'll refer to the source code location as [dspace-angular].

  2. Install Dependencies: Install all required local dependencies by running the following from within the unzipped [dspace-angular] directory

    Code Block
    # change directory to our repo
cd [dspace-angular]

# install the local dependencies
yarn install


  3. Build/Compile: Build the User Interface for Production. This builds source code (under [dspace-angular]/src/) to create a compiled version of the User Interface in the [dspace-angular]/dist folder.  This /dist folder is what we will deploy & run to start the UI.

    Code Block
    yarn build:prod


    1. You only need to rebuild the UI application if you change source code (under [dspace-angular]/src/).  Simply changing the configurations (e.g. config.prod.yml, see below) do not require a rebuild, but only require restarting the UI.

  4. Deployment (to [dspace-ui-deploy]):Choose/Create a directory on your server where you wish to run the compiled User Interface. We'll call this [dspace-ui-deploy].

    Info
    title[dspace-ui-deploy] vs [dspace-angular]

    [dspace-angular] is the directory where you've downloaded and built the UI source code (per the instructions above).  For deployment/running the UI, we recommend creating an entirely separate [dspace-ui-deploy] directory. This keeps your running, production User Interface separate from your source code directory and also minimizes downtime when rebuilding your UI.  You may even choose to deploy to a [dspace-ui-deploy] directory on a different server (and copy the /dist directory over via FTP or similar).

    If you are installing the UI for the first time, or just want a simple setup, you can choose to have [dspace-ui-deploy] and [dspace-angular] be the same directory. This would mean you don't have to copy your /dist folder to another location. However, the downside is that your running site will become unresponsive whenever you do a re-build/re-compile (i.e. rerun "yarn build:prod") as this build process will first delete the [dspace-angular]/dist directory before rebuilding it.

    1. Copy the entire [dspace-angular]/dist/ folder to this location. For example:

      Code Block
      cp -r [dspace-angular]/dist [dspace-ui-deploy]

       

    2. WARNING: At this time, you MUST copy the entire "dist" folder and make sure NOT to rename it.  Therefore, the directory structure should look like this: 

      Code Block
      titleContents of \[dspace-ui-deploy\] folder
      [dspace-ui-deploy]
    /dist
       /browser (compiled client-side code)
       /server  (compiled server-side code, including "main.js")
    /config     (Optionally created in the "Configuration" step below)
       /config.prod.yml (Optionally created in the "Configuration" step below)


    3. NOTE: the OS account which runs the UI via Node.js (see below) MUST have write privileges to the [dspace-ui-deploy] directory (because on startup, the runtime configuration is written to [dspace-ui-deploy]/dist/browser/assets/config.json)

  5. Configuration: You have two options for User Interface Configuration, Environment Variables or YAML-based configuration (config.prod.yml).  Choose one!

    1. YAML configuration: Create a "config.prod.yml" at [dspace-ui-deploy]/config/config.prod.yml.  You may wish to use the [dspace-angular]/config/config.example.yml as a starting point. This config.prod.yml file can be used to override any of the default configurations listed in the config.example.yml (in that same directory). At a minimum this file MUST include a "rest" section (and may also include a "ui" section),  similar to the following (keep in mind, you only need to include settings that you need to modify).  

      Code Block
      languageyml
      titleExample config.prod.yml
      # The "ui" section defines where you want Node.js to run/respond. It often is a *localhost* (non-public) URL, especially if you are using a Proxy.
# In this example, we are setting up our UI to just use localhost, port 4000. 
# This is a common setup for when you want to use Apache or Nginx to handle HTTPS and proxy requests to Node on port 4000
ui:
  ssl: false
  host: localhost
  port: 4000
  nameSpace: /

# This example is valid if your Backend is publicly available at https://api.mydspace.edu/server/
# The REST settings MUST correspond to the primary/public URL of the backend. Usually, this means they must be kept in sync
# with the value of "dspace.server.url" in the backend's local.cfg
rest:
  ssl: true
  host: api.mydspace.edu
  port: 443
  nameSpace: /server


    2. Environment variables: Every configuration in the UI may be specified via an Environment Variable. See Configuration Override in the User Interface Configuration documentation for more details. For example, the below environment variables provide the same setup as the config.prod.yml example above.

      Code Block
      titleExample Environment Variables
      # All environment variables MUST 
# (1) be prefixed with "DSPACE_"
# (2) use underscores as separators (no dots allowed), and 
# (3) use all uppercase

# "ui" section
DSPACE_UI_SSL = false
DSPACE_UI_HOST = localhost
DSPACE_UI_PORT = 4000
DSPACE_UI_NAMESPACE = /

# "rest" section
DSPACE_REST_SSL = true
DSPACE_REST_HOST = api.mydspace.edu
DSPACE_REST_PORT = 443
DSPACE_REST_NAMESPACE = /server


      1. NOTE: When using PM2, some may find it easier to use Environment variables, as it allows you to specify DSpace UI configs within your PM2 configuration. See PM2 instructions below.

    3. Configuration Hints:
      1. See the User Interface Configuration documentation for a list of all available configurations.
      2. In the "ui" section above, you may wish to start with "ssl: false" and "port: 4000" just to be certain that everything else is working properly before  adding HTTPS support. KEEP IN MIND, we highly recommend always using HTTPS for Production. (See section on HTTPS below)
      3. (Optionally) Test the connection to your REST API from the UI from the command-line.  This is not required, but it can sometimes help you discover immediate configuration issues if the test fails.
        1. If you are using YAML configs, copy your config.prod.yml back into your source code folder at [dspace-angular]/config/config.prod.yml 
        2. From [dspace-angular], run yarn test:rest This script will attempt a basic Node.js connection to the REST API that is configured in your "config.prod.yml" file and validate the response.
        3. A successful connection should return a 200 Response and all JSON validation checks should return "true"
        4. If you receive a connection error or different response code, you MUST fix your REST API before the UI will be able to work.  See also the "Common Installation Issues" below.  If you receive an SSL error, see "Using a Self-Signed SSL Certificate causes the Frontend to not be able to access the Backend"
  6. Start up the User Interface:  The compiled User Interface only requires Node.js to run.  However, most users may want to use PM2 (or a similar Node.js process manager) in Production to provide easier logging and restart tools.

    1. Quick Start: To quickly startup / test the User Interface, you can just use Node.js.  This is only recommended for quickly testing the UI is working, as no logs are available.

      Code Block
      # You MUST start the UI from within the deployment directory
cd [dspace-ui-deploy]

# Run the "server/main.js" file to startup the User Interface
node ./dist/server/main.js

# Stop the UI by killing it via Ctrl+C


    2. Run via PM2: Using PM2 (or a different Node.js process manager) is highly recommended for Production scenarios. Here's an example of a Production setup of PM2.

      1. First you need to create a PM2 JSON configuration file which will run the User Interface.  This file can be named anything & placed where ever you like, but you may want to save it to your deployment directory (e.g. [dspace-ui-deploy]/dspace-ui.json). 

        Code Block
        titledspace-ui.json
        {
    "apps": [
        {
           "name": "dspace-ui",
           "cwd": "/full/path/to/dspace-ui-deploy",
           "script": "dist/server/main.js",
           "env": {
              "NODE_ENV": "production"
           }
        }
    ]
}


        1. NOTE: The "cwd" setting MUST correspond to your [dspace-ui-deploy] folder path.

        2. NOTE #2: If you wanted to configure your UI using Environment Variables, specify those Environment Variables under the "env" section.  For example:  

          Code Block
          titleConfiguration via Environment Variables
          "env": {
   "NODE_ENV": "production",
   "DSPACE_REST_SSL": "true",
   "DSPACE_REST_HOST": "api7.dspace.org",
   "DSPACE_REST_PORT": "443",
   "DSPACE_REST_NAMESPACE": "/server"
}


        3. NOTE #3: If you are using Windows, there are two other rules to keep in mind in this JSON configuration. First, all paths must include double backslashes (e.g. "C:\\dspace-ui-deploy").  Second, "cluster" mode is required.  Here's an example configuration for Windows:

          Code Block
          titledspace-ui.json (for Windows)
          {
    "apps": [
        {
           "name": "dspace-ui",
           "cwd": "C:\\full\\path\\to\\dspace-ui-deploy",
           "script": "dist\\server\\main.js",
           "exec_mode": "cluster",
           "env": {
              "NODE_ENV": "production"
           }
        }
    ]
}


      2. Now, start the application using PM2 using the configuration file you created in the previous step

        Code Block
        # In this example, we are assuming the config is named "dspace-ui.json"
pm2 start dspace-ui.json

# For better performance, you may want to use PM2's cluster mode
# This scales the app across all available CPUs. See docs for more details
# https://pm2.keymetrics.io/docs/usage/cluster-mode/
# pm2 start dspace-ui.json -i max

# To see the logs, you'd run
# pm2 logs

# To stop it, you'd run
# pm2 stop dspace-ui.json

# If you need to change your PM2 configs, delete the old config and restart
# pm2 delete dspace-ui.json


      3. For more PM2 commands see https://pm2.keymetrics.io/docs/usage/quick-start/
      4. HINT #1: In production, you may want to run PM2 in cluster mode.  See https://pm2.keymetrics.io/docs/usage/cluster-mode/
      5. HINT #2: You may also want to install/configure pm2-logrotate to ensure that PM2's log folder doesn't fill up over time.
      6. Did PM2 not work or throw an immediate error? It's likely that something in your UI installation or configuration is incorrect.  Check the PM2 logs ("pm2 logs") first for errors. If the problem is not obvious, try to see if you can run the UI using the "Quick Start" method (using just Node.js) instead. Once "Quick Start" is working, try PM2 again.
  7. Test it out: At this point, the User Interface should be available at the URL you configured!
    1. For an example of what the default frontend looks like, visit the Demo Frontend: https://demo7.dspace.org/ 
    2. If the UI fails to start or throws errors, it's likely a configuration issue.  See Commons Installation Issues below for common error messages you may see and how to resolve them.
    3. If you have an especially difficult issue to debug, you may wish to stop PM2. Instead, try running the UI via the "Quick Start" method (using just Node.js).  This command might provide a more specific error message to you, if PM2 is not giving enough information back.
  8. Add HTTPS support: For HTTPS (port 443) support, you have two options
    1. (Recommended) You can install Install either Apache HTTPD or Nginx , configuring SSL at that level to act as a "proxy" for the frontend (and backend).  This allows you to manage HTTPS (SSL certificates) in either Apache HTTPD or Nginx, and proxy all requests to PM2 the frontend (still running on port 4000) .  and backend (running on port 8080). This is our current recommended approach. Plus, as a bonus, if you want to host the UI and Backend on the same server  These instructions are specific to Apache, but a similar setup can be achieved with Nginx.
      1. If you already have Apache / Nginx installed for the backend, you can use
      just one Apache HTTPD (or Nginx) to proxy to both. These instructions are specific to Apache
      1. the same Apache / Nginx.  You can also choose to install a separate one (either approach is fine).
        1. Install Apache HTTPD, e.g. sudo apt install apache2
        2. Install the mod_proxy and mod_proxy_http modules, e.g. sudo a2enmod proxy; sudo a2enmod proxy_http
        3. Restart Apache to enable
        4. 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/

      2. Now, setup a new VirtualHost for your UI site (preferably using HTTPS / port 443) which proxies all requests to PM2 running on port 4000.

        Code Block
        <VirtualHost _default_:443>
     ..# setupAdd your hostdomain how you want, here. We've added "my.dspace.edu" as an example
    ServerName my.dspace.edu
    .. setup your host how you want, including log settings...

    # These SSL settings are identical to those for the backend installation (see above)
    # If you already have the backend running HTTPS, just add the new Proxy settings below.
    SSLEngine on
    SSLCertificateFile [full-path-to-PEM-cert]
    SSLCertificateKeyFile [full-path-to-cert-KEY]

    # LetsEncrypt #certificates Proxy(and allpossibly HTTPSothers) requestsmay fromrequire Apachea tochain PM2file onbe port 4000specified
    # in order NOTEfor thatthe thisUI proxy/ URLNode.js mustto matchvalidate the "ui" settings in your config.prod.yml
    ProxyPass / http://localhost:4000/ HTTPS connection.
    #SSLCertificateChainFile [full-path-to-chain-file]

    # These Proxy settings are for the backend. They are described in the backend installation (see above)
    ProxyPassReverse# / http://localhost:4000/
</VirtualHost>If you already have the backend running HTTPS, just append the new Proxy settings below.
    # Proxy all HTTPS requests to "/server" from Apache to Tomcat via AJP connector
    # (In this example: https://my.dspace.edu/server/ will display the REST API)
    ProxyPass /server ajp://localhost:8009/server
    ProxyPassReverse /server ajp://localhost:8009/server

    # Proxy all HTTPS requests from Apache to PM2 on localhost, port 4000
    # NOTE that this proxy URL must match the "ui" settings in your config.prod.yml
    # (In this example: https://my.dspace.edu/ will display the User Interface)
    ProxyPass / http://localhost:4000/
    ProxyPassReverse / http://localhost:4000/
</VirtualHost>


      3. HINT#1: Because you are using a proxy for HTTPS supportBecause you are using a proxy for HTTPS support, in your User Interface Configuration, your "ui" settings will still have "ssl: false" and "port: 4000".  This is perfectly OK!" settings will still have "ssl: false" and "port: 4000".  This is perfectly OK!
      4. HINT#2: to force the UI to connect to the backend using HTTPS, you should verify your "rest" settings in your User Interface Configuration match the "dspace.server.url" in your backend's "local.cfg" and both use the HTTPS URL.  So, if your backend (REST API) is proxied to https://my.dspace.edu/server/, both those settings should specify that HTTPS URL.
      5. HINT#3: to force the backend to recognize the HTTPS UI, make sure to update your "dspace.ui.url" in However, to force the backend (REST API) to use the new HTTPS URL, you should update your backend's "local.cfg" to have "dspace.ui.url = https://[full-address-of-proxy]"  (e.g. https://my.dspace.edu)is updated to use the new HTTPS UI URL.
    2. (Alternatively) You can use the basic HTTPS support built into our UI and Node server.  (This may currently be better for non-Production environments as it has not been well tested) 
      1. Create a [dspace-ui-deploy]/config/ssl/ folder and add a key.pem and cert.pem to that folder (they must have those exact names)
      2. In your User Interface Configuration, go back and update the following:
        1. Set "ui > ssl" to true
        2. Update "ui > port" to be 443
          1. In order to run Node/PM2 on port 443, you also will likely need to provide node with special permissions, like in this example.
      3. Restart the UI
      4. Keep in mind, while this setup is simple, you may not have the same level of detailed, Production logs as you would with Apache HTTPD or Nginx

...