...
Installing the Frontend (User Interface)
Warning |
---|
title | Below instructions are specific to 7.2 (or later) |
---|
|
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 |
Frontend Requirements
Table of Content Zone |
---|
|
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.
Node.js (v12.x or v14.x or v16.x)- Node.js can be found at https://nodejs.org/. It may be available through your Linux distribution's package manager. We recommend running a Long Term Support (LTS) version (even numbered releases). Non-LTS versions (odd numbered releases) are not recommended.
- Node.js is a Javascript runtime that also provides npm (Node Package Manager). It is used to both build and run the frontend.
Yarn (v1.x)PM2 (or another Process Manager for Node.js apps) (optional, but recommended for Production)DSpace 7.x Backend (see above)- The DSpace User Interface (Frontend) cannot function without an installed DSpace Backend. Follow the instructions above.
- The Frontend and Backend do not need to be installed on the same machine/server. They may be installed on separate machines as long as the two machines can connect to one another via HTTP or HTTPS.
|
Frontend Installation
Warning |
---|
title | Below instructions are specific to 7.2 (or later) |
---|
|
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 |
- 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
- First, install all the Frontend Requirements listed above & verify the backend/REST API is publicly accessible.
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.- NOTE: For the rest of these instructions, we'll refer to the source code location as
[dspace-angular].
Install Dependencies: Install all necessary 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 |
Create a Production Configuration file at
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 |
- 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.
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. |
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 |
---|
title | Contents 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) |
- 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
)
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 |
---|
language | yml |
---|
title | Syntax for 7.2 and above (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: /
# |
config/config.prod.yml. You may wish to use the 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 |
---|
language | yml |
---|
title | Syntax for 7.2 and above (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 |
NOTE: In 7.1 or 7.0, this configuration file uses a different syntax and should be created at [dspace-angular]/src/environments/environment.prod.ts
, based on the default settings in environment.common.ts
. An example of that older syntax can also be found below:
Code Block |
---|
title | Syntax for 7.1 or 7.0 (environment.prod.ts) |
---|
|
export const environment = {
// 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,
// NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
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
{
,
'
',
port: 443,
// NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
nameSpace: '/server'
}
};(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.In DSpace 7.1, this could be tested by running
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.
- Configuration Hints:
- See the User Interface Configuration documentation for a list of all available configurations.
- 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)
- (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.
- If you are using YAML configs, copy your config.prod.yml back into your source code folder at
[dspace-angular]/config/config.prod.yml
- 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. - A successful connection should return a 200 Response and all JSON validation checks should return "true"
- 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"
- 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.
Quick Start: To quickly startup / test the User Interface, you can just use Node.js
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 |
- 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.
yarn config:check:rest
This script will attempt a basic Node.js connection to the REST API that is configured in your "environment.prod.ts" file and validate the response. - In DSpace 7.2 (and above), this is instead tested by running
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. - A successful connection should return a 200 Response and all JSON validation checks should return "true"
- 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"
- HINT #1: 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. With those settings, you can quickly test your UI by running "
yarn start
" and trying to access it via http://[mydspace.edu]:4000/
from your web browser. KEEP IN MIND, we highly recommend always using HTTPS for Production. - HINT #2: If Node throws an error saying "listen EADDRNOTAVAIL: address not available", try setting the "host" to "0.0.0.0" or "localhost". Usually that error is a sign that the "host" is not recognized.
- If there are other settings you know you need to modify in the sample
config.example.yml
configuration file you can also copy them into this same file. Build the User Interface for Production. This uses your config.prod.yml
and the source code to create a compiled version of the UI in the [dspace-angular]/dist
folder
Code Block |
---|
yarn run build:prod |
- As of 7.2 or above, you only need to rebuild the UI application if you change source code (under ./src/). Simply changing the configurations in config.prod.yml do not require a rebuild, but only require restarting the UI.
- In 7.1 or 7.0: anytime you change/update your
environment.prod.ts
, then you will need to rebuild the UI application (i.e. rerun this"yarn run build:prod" command).
Assuming you are using PM2, create a JSON configuration file describing how to run our UI application. This need NOT be in the same directory as the dspace-angular codebase itself (in fact you may want to put the parent directory or another location). Keep in mind the "cwd" setting (on line 5) must be the full path to your [dspace-angular]
folder.
Code Block |
---|
|
{
"apps": [
{
"name": "dspace-angular",
"cwd": "/home/dspace/dspace-angular",
"script": "yarn",
"args": "run serve:ssr",
"interpreter": "none"
}
]
} |
- Not using PM2? That's OK. The key command that your process manager should run is
yarn run serve:ssr.
This is the command that starts the app (after it was built using yarn run build:prod
) - Using Windows? This "dspace-angular.json" file needs to have a slightly different structure on Windows.
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",
"env": {
"NODE_ENV": "production"
}
}
]
} |
- NOTE: The "cwd" setting MUST correspond to your
[dspace-ui-deploy]
folder path. NOTE #2: If you wanted to configure your UI using Environment Variables, specify those Environment Variables under the "env" section. For example:
Code Block |
---|
title | Configuration 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"
} |
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:\\
dspacedspace-ui-
angulardeploy). Second, "cluster" mode is required
. Finally, because of a known issue in PM2, you must point the "script" at the "npm/node_modulesyarn/bin/yarn.
js" file directly. So, here Here's
how this configuration looks on Windows platformsan example configuration for Windows:
angular
For
only |
{
"apps": [
{
"name": "dspace- |
angularui",
"cwd": "C:\\full\\path\\to\\dspace-ui- |
angular
C:
path
to\\npm\\node_modules\\yarn\\bin\\yarn
args
"run serve:ssr",
"interpreter
none
,
"exec_mode": "cluster"
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- |
angularui.json"
pm2 start dspace- |
angularui.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- |
angular
- For more PM2 commands see https://pm2.keymetrics.io/docs/usage/quick-start/
- HINT: You may also want to install/configure pm2-logrotate to ensure that PM2's log folder doesn't fill up over time.
- 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 "
yarn start- Quick Start"
(this builds & starts the app in one step). Once you successfully get the UI running via "yarn start", you should be able to go back to using PM2 successfully.- method (using just Node.js) instead. Once "Quick Start" is working, try PM2 again.
- Test it out: At this point, the User Interface should be available at the URL you configured in your
config.prod.yml
!
- For an example of what the default frontend looks like, visit the Demo Frontend: https://demo7.dspace.org/
- 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.
- If you have an especially difficult issue to debug, you may wish to stop PM2. Instead, try running the UI via
yarn start
(which is a simple build & deploy process for the UIthe "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.
- Add HTTPS support: For HTTPS (port 443) support, you have two options
- (Recommended) You can install either Apache HTTPD or Nginx , configuring SSL at that level, and proxy requests to PM2 (still running on port 4000). This is our current recommended approach. Plus, as a bonus, if you want to host the UI and Backend on the same server, you can use just one Apache HTTPD (or Nginx) to proxy to both. These instructions are specific to Apache.
- Install Apache HTTPD, e.g.
sudo apt install apache2
- Install the mod_proxy and mod_proxy_http modules, e.g.
sudo en2mod proxy; sudo a2enmod proxy_http
- Restart Apache to enable
Now, setup a new VirtualHost for your site (preferably using HTTPS / port 443) which proxies all requests to PM2 running on port 4000.
Code Block |
---|
<VirtualHost _default_:443>
.. setup your host how you want, including log settings...
SSLEngine on
SSLCertificateFile [full-path-to-PEM-cert]
SSLCertificateKeyFile [full-path-to-cert-KEY]
# Proxy all HTTPS requests from Apache to PM2 on port 4000
# NOTE that this proxy URL must match the "ui" settings in your config.prod.yml
ProxyPass / http://localhost:4000/
ProxyPassReverse / http://localhost:4000/
</VirtualHost> |
- Because 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!
- 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)
- (Alternatively) You can use the basic HTTPS support built into dspace-angular node our UI and Node server. (This may currently be better for non-Production environments as it has not been well tested)
- Create a
[dspace-ui-angulardeploy]/config/ssl/
folder and add a key.pem
and cert.pem
to that folder (they must have those exact names) - In your User Interface Configuration, go back and update the following:
- Set
Enable - "ui
.- > ssl"
(set - to true
)- Update
your - "ui
.- > port" to be 443
- In order to run Node/PM2 on port 443, you also will likely need to provide node with special permissions, like in this example.
- Rebuild and then restart the app in PM2Restart the UI
- 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
Additional UI configurations are described in User Interface Configuration. A guide to customizing the look and feel or branding via a Theme is also available in User Interface Customization
What Next?
After a successful installation, you may want to take a closer look at
If you've run into installation problems, you may want to...
...
See the Troubleshoot an error page guide, look for the section on "DSpace 7.x". This will provide you hints on locating error messages both in the User Interface (frontend) and in the REST API (backend)
...
- In DSpace 7.1, this could be tested by running
yarn config:check:rest
This script will attempt a basic Node.js connection to the REST API that is configured in your "environment.prod.ts" file and validate the response. - In DSpace 7.2 (and above), this is instead tested by running
yarn test:rest
This script will attempt a basic Node.js connection to the REST API that is configured in your "[dspace-angular]/config/config.prod.yml" file and validate the response. (NOTE: you will need to copy your config.prod.yml to [dspace-angular]/config/ for this script to find it!) - A successful connection should return a 200 Response and all JSON validation checks should return "true".
- 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 additional hints below for likely causes).
...