All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
Table of Content Zone | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
UNIX-like OS or Microsoft Windows
Java JDK 11 or 17 (OpenJDK or Oracle JDK)
Apache Maven 3.5.4 or above (Java build tool)
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 ProxyYou 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:
Apache Ant 1.10.x or later (Java build tool)
Apache Ant is required for the second stage of the build process (deploying/installing the application). First, Maven is used to construct the installer ( 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)
Oracle (UNSUPPORTED AS OF 7.6)
Apache Solr 8.x (full-text index/search service)
Solr can be obtained at the Apache Software Foundation site for 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 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)
(Optional) IP to City Database for Location-based StatisticsOptionally, 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:
|
...
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.
dspace-7.2
) or branch.Zip file. If you downloaded dspace-7.2.zip do the following:
Code Block |
---|
unzip dspace-7.2.zip |
.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).
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; |
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 | ||
---|---|---|
| ||
<dependency> <groupId>com.oracle</groupId> <artifactId>ojdbc6</artifactId> <version>11.2.0.4.0</version> </dependency> |
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
[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/serverdspace.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:4000dspace.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 | ||
---|---|---|
| ||
The provided However, you should be aware that ANY configuration can now be copied into your
Individual settings may also be commented out or removed in your See the Configuration Reference section for more details. |
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.)
Build the Installation Package: As the dspace UNIX user, generate the DSpace installation package.
Code Block |
---|
cd [dspace-source] mvn package |
Info | ||
---|---|---|
| ||
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: |
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: |
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 |
Deploy JAR application : The DSpace backend have a runnable jar application made with SpringBoot
inside the specific server-boot
module (in [dspace-source]/dspace/modules/server-boot). Inside the target folder, you'll find the build artifact (i.e. server-boot-[DSpace-version].jar
) that self-contains the dspace.dir
configuration made during the build phase. You can execute directly this jar with the following command
Code Block | ||||
---|---|---|---|---|
| ||||
java -jar [dspace-source]/dspace/modules/server-boot/target/server-boot-[DSpace-version].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, jsut like this: --[prop]=[value]
.
[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 | ||
---|---|---|
| ||
<?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
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
.
[dspace]/webapps/rest
). It is NOT used by the DSpace frontend. So, most users should skip this step.Copy Solr cores: DSpace installation creates a set of four empty Solr cores already configured.
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 |
Start (or re-start) Solr. For example:
Code Block | ||
---|---|---|
| ||
[solr]/bin/solr restart |
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.
${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.Create an Administrator Account: Create an initial administrator account from the command line:
Code Block |
---|
[dspace]/bin/dspace create-administrator |
sudo apt install apache2
sudo a2enmod headers; sudo a2enmod proxy; sudo a2enmod proxy_ajp
Alternatively, you can choose to use mod_proxy_http to create an http proxy. A separate example is commented out below
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" /> |
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> |
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; } } |
dspace.server.url
) in your local.cfg to match the new URL of your backend (REST API). This will require briefly rebooting Tomcat....
title | Below instructions are specific to 7.2 (or later) |
---|
...
...
Table of Content Zone | ||||||
---|---|---|---|---|---|---|
| ||||||
UNIX-like OS or Microsoft Windows
Node.js (v16.x or v18.x)
Yarn (v1.x)
PM2 (or another Process Manager for Node.js apps) (optional, but recommended for Production)
DSpace 7.x Backend (see above)
|
...
...
The Frontend Instructions below are specific to 7.2 or later. For Frontend Installation instructions for 7.0 or 7.1, see 7.0-7.1 Frontend Installation
dspace-7.2
) or branch.[dspace-angular].
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 # NOTE: Some dependencies occasionally get overly strict over exact versions of Node & Yarn. # If you are running a supported version of Node & Yarn, but see a message like # `The engine "node" is incompatible with this module.`, you can disregard it using this flag: # yarn install --ignore-engines |
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 |
[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.Deployment (to [dspace-ui-deploy]): (Only recommended for Production setups) Choose/Create a directory on your server where you wish to run the compiled User Interface. We'll call this [dspace-ui-deploy].
Info | ||
---|---|---|
| ||
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 |
Copy the entire [dspace-angular]
/dist/
folder to this location. For example:
Code Block |
---|
cp -r [dspace-angular]/dist [dspace-ui-deploy] |
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 | ||
---|---|---|
| ||
[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) |
[dspace-ui-deploy]
directory (because on startup, the runtime configuration is written to [dspace-ui-deploy]/dist/browser/assets/config.json
)Configuration: You have two options for User Interface Configuration, Environment Variables or YAML-based configuration (config.prod.yml
). Choose one!
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 | ||||
---|---|---|---|---|
| ||||
# 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 |
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 | ||
---|---|---|
| ||
# 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 |
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.
[dspace-angular]/config/config.prod.yml
[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.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 |
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 | ||
---|---|---|
| ||
{ "apps": [ { "name": "dspace-ui", "cwd": "/full/path/to/dspace-ui-deploy", "script": "dist/server/main.js", "instances": "max", "exec_mode": "cluster", "env": { "NODE_ENV": "production" } } ] } |
[dspace-ui-deploy]
folder path.NOTE #3: If you wanted to configure your UI using Environment Variables, specify those Environment Variables under the "env" section. For example:
Code Block | ||
---|---|---|
| ||
"env": { "NODE_ENV": "production", "DSPACE_REST_SSL": "true", "DSPACE_REST_HOST": "demo.dspace.org", "DSPACE_REST_PORT": "443", "DSPACE_REST_NAMESPACE": "/server" } |
NOTE #4: 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 | ||
---|---|---|
| ||
{ "apps": [ { "name": "dspace-ui", "cwd": "C:\\full\\path\\to\\dspace-ui-deploy", "script": "dist\\server\\main.js", "instances": "max", "exec_mode": "cluster", "env": { "NODE_ENV": "production" } } ] } |
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 # 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 |
sudo apt install apache2
sudo a2enmod proxy; sudo a2enmod proxy_http
Apache HTTPD sample configuration:
Now, setup (or update) the 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> # 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... # 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 # 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 (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] # These Proxy settings are for the backend. They are described in the backend installation (see above) # 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 # [NEW FOR UI:] 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> |
Sample NGinx "server block" configuration. Keep in mind we are only providing basic example settings.
Code Block |
---|
# 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 # 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. 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 # These Proxy settings are for the backend. They are described in the backend installation (see above) location /server { proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-Host $host; proxy_pass http://localhost:8080/server; } # [NEW FOR UI:] Proxy all HTTPS requests from NGinx 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) location / { proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-Host $host; proxy_pass http://localhost:4000/; } } |
[dspace-ui-deploy]/config/ssl/
folder and add a key.pem
and cert.pem
to that folder (they must have those exact names)...
Code Block |
---|
# This script will attempt a basic Node.js connection to the REST API # configured in your "[dspace-angular]/config/config.prod.yml" and # validate the response.(NOTE: config.prod.yml MUST be copied to # to [dspace-angular]/config/ for this script to find it!) yarn test:rest # In DSpace 7.1 a different command was needed # yarn config:check:rest |
...
config.*.yml
(or environment.*.ts
for 7.1 or 7.0) configuration file for the User Interface. That configuration section defines which REST API the UI will attempt to use. If the settings do NOT map to a valid DSpace REST API, then you will see this "No _links section found.." error. Keep in mind, the REST API must use HTTPS (the only exception is if both the frontend and backend are running on "localhost"-based URLs)If you are using a Let's Encrypt style certificate, you may need to modify your backend's Apache settings to also provide a Chain File as follows:
Code Block |
---|
# For example: /etc/letsencrypt/live/[domain]/cert.pem SSLCertificateFile [full-path-to-PEM-cert] # For example: /etc/letsencrypt/live/[domain]/privkey.pem SSLCertificateKeyFile [full-path-to-cert-KEY] # For example: /etc/letsencrypt/live/[domain]/chain.pem SSLCertificateChainFile [full-path-to-chain-file] |
Verify that you can access the REST API from the machine where Node.js is running (i.e. your UI is running). For example try a simple "wget" or "curl" to verify the REST API is returning expected JSON similar to our demo API at https://demo.dspace.org/server/api
Code Block |
---|
# Attempt to access the REST API via HTTPS from command-line on the machine where Node.js is running. # If this fails or throws a SSL cert error, you must fix it. wget https://[rest.host]/server/api |
...
Also double check the "rest" section of your config.*.yml
(or environment.*.ts
for 7.1 or 7.0) configuration file for the User Interface. Make sure it's also pointing to the exact same URL as that "dspace.server.url
" setting. Again, check the mode, domain, port and paths all match exactly.
...