Page History
...
Table of Content Zone | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||
UNIX-like OS or Microsoft Windows
Java JDK 11 or 17 (OpenJDK or Oracle JDK)
Apache Maven 3.3.x 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 or Oracle)PostgreSQL 11.x, 12.x or 13.x (with pgcrypto installed)
Oracle 10g or later
Apache Solr 8.x (full-text index/search service)
Solr can be obtained at the Apache Software Foundation site for Lucene and Solr. You may wish to read portions of the quick-start tutorial to make yourself familiar with Solr's layout and operation. Unpack a Solr .tgz or .zip archive in a place where you keep software that is not handled by your operating system's package management tools, and arrange to have it running whenever DSpace is running. You should ensure that Solr's index directories will have plenty of room to grow. You should also ensure that port 8983 is not in use by something else, or configure Solr to use a different port. If you are looking for a good place to put Solr, consider 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:
Git (code version control)Currently, there is a known bug in DSpace where a third-party Maven Module expects For the time being, you can work around this problem by installing Git locally: https://git-scm.com/downloads |
...
- 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. Install all necessary 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
[dspace-angular]/srcconfig/environments/environmentconfig.prod.tsyml
. You may wish to use theenvironmentconfig.templateexample.ts yml
as a starting point. Thisenvironmentconfig.prod.tsyml
file can be used to override any of the default configurations specified listed in theenvironmentconfig.commonexample.tsyml
(in that same directory). At a minimum this file MUST include the a "uirest" section (and may also include a "rest" sections ui" section), similar to the following (keep in mind, you only need to include settings that you need to modify). (NOTE: In 7.1 or 7.0, this file used a different syntax and was located atsrc/environments/environment.prod.ts
. An example of that older syntax can also be found below)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
Code Block title Syntax for 7.1 or 7.0 (environment.prod.ts) export const environment = { 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 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, // NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript nameSpace: '/server' } };
- New in 7.1 or above: Immediately test your connection to the REST API by running
yarn config:check:rest
. This script will attempt a basic Node.js connection with the REST API configured in your "config.prod.yml" (or "environment.prod.ts" for 7.1 or 7.0) 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 viahttp://[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 default environmentsample
config.commonexample.ts
configurationyml
configuration file you can also copy them into this same file.
- New in 7.1 or above: Immediately test your connection to the REST API by running
Build the User Interface for Production. This uses your
environment.prod.ts
and the source code to create a compiled version of the UI in the[dspace-angular]/dist
folderCode Block yarn run build:prod
your
config.prod.yml
and the source code to create a compiled version of the UI in the[dspace-angular]/dist
folderCode 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 HINT: if 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 title dspace-angular.json { "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 usingyarn run build:prod
)
- Not using PM2? That's OK. The key command that your process manager should run is
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-angular.json" pm2 start dspace-angular.json # To see the logs, you'd run # pm2 logs # To stop it, you'd run # pm2 stop dspace-angular.json
- 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 "yarn 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.
- At this point, the User Interface should be available at the URL you configured in your
environmentconfig.prod.tsyml
- 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 UI). This command might provide a more specific error message to you, if PM2 is not giving enough information back.
- 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 (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 environmentconfig.*prod.tsyml ProxyPass / http://localhost:4000/ ProxyPassReverse / http://localhost:4000/ </VirtualHost>
- Install Apache HTTPD, e.g.
- (Alternatively) You can use the basic HTTPS support built into dspace-angular node server. (This may currently be better for non-Production environments as it has not been well tested)
- Create a
[dspace-angular]/config/ssl/
folder and add akey.pem
andcert.pem
to that folder (they must have those exact names) - 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 PM2
- 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
- Create a
- (Recommended) You can install either Apache HTTPD or Nginx , configuring SSL at that level, and proxy requests to PM2 (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.
- 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
...
Info | ||
---|---|---|
In 7.1 and above, there is a
If everything "looks good", you should see a 200 response, and all JSON validity checks should return "true". If you see a different response code, or an error, this means Node.js is unable to communicate with your configured REST API. |
...
- A possible configuration issue in the frontend or backend.
- Check the "rest" section of your
config.*.yml
(orenvironment.*.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. - Check the "dspace.ui.url" configuration of your backend & verify it corresponds to the public URL of the User Interface (i.e. the exact same URL you use in your browser)
- Check the "rest" section of your
- A possible SSL certificate issue. This issue may also appear if the REST API's SSL Certificate is either untrusted (by the frontend) or expired.
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]
- Per the Apache docs, you can also use the SSLCertificateFile setting to specify intermediate CA certificates along with the main cert.
- For self-signed certs, see also "Using a Self-Signed SSL Certificate causes the Frontend to not be able to access the Backend" common issue listed below.
- Something blocking access to the REST API. This may be a proxy issue, a firewall issue, or something else generally blocking the port (e.g. port 443 for SSL).
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://api7.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
- In most production scenarios, your REST API should be publicly accessible on the web, unless you are guaranteed that all your DSpace users will access the site behind a VPN or similar. So, this "No _links section found" error may also occur if you are accessing the UI from a client computer/web browser which is unable to access the REST 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.
...