All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
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": "api7.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
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> # 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... # 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 # 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> |
[dspace-ui-deploy]/config/ssl/
folder and add a key.pem
and cert.pem
to that folder (they must have those exact names)...