Page History
...
First, you will need to make minor modifications to the old "environment.*.ts" configuration file(s) to ensure it no longer imports any other files:
Code Block title Replace all imports in environment.*.ts // (1) FIRST, you must comment out or remove all 4 imports at the top of the file. For example: //import { GlobalConfig } from '../config/global-config.interface'; //import { NotificationAnimationsType } from '../app/shared/notifications/models/notification-animations-type'; //import { BrowseByType } from '../app/browse-by/browse-by-switcher/browse-by-decorator'; //import { RestRequestMethod } from '../app/core/data/rest-request-method'; // (2) SECOND, replace those 4 imported objects with these 4 objects. // Paste this code at the top of the file where those imports were. interface GlobalConfig { } enum NotificationAnimationsType { Fade = 'fade', FromTop = 'fromTop', FromRight = 'fromRight', FromBottom = 'fromBottom', FromLeft = 'fromLeft', Rotate = 'rotate', Scale = 'scale' } enum BrowseByType { Title = 'title', Metadata = 'metadata', Date = 'date' } enum RestRequestMethod { GET = 'GET', POST = 'POST', PUT = 'PUT', DELETE = 'DELETE', OPTIONS = 'OPTIONS', HEAD = 'HEAD', PATCH = 'PATCH' }
Now, you are ready to run the "yarn env:yaml" command to transform this old configuration into the new format.
Code Block title Migrate from environment.\*.ts to config.\*.yml yarn env:yaml [relative-path-to-environment.ts] [optional-relative-path-to-YAML] # For example, from the 7.2 (or above) root directory, run this: # yarn env:yaml relative/path/to/old/environment.prod.ts config/config.prod.yml
- Finally, you should replace the old environment.*.ts config file(s) can be deleted. They are not used at all in 7.2 or abovewith the stock versions. They continue to provide default configuration values, but customization should be done in the YAML files. If you had created additional environment files, those can be deleted.
Configuration Override
In 7.2 or above
...
Using Environment variables. All environment variables MUST (1) be prefixed with "DSPACE_", (2) use underscores as separators (no dots allowed), and (3) use all uppercase. Some examples are below:
Code Block # "ui" settings environment variables ui.host => DSPACE_UI_HOST # The host name ui.port => DSPACE_UI_PORT # The port number ui.nameSpace => DSPACE_UI_NAMESPACE # The namespace ui.ssl => DSPACE_UI_SSL # Whether the angular application uses SSL [true/false] # "rest" settings environment variables rest.host => DSPACE_REST_HOST # The host name of the REST application rest.port => DSPACE_REST_PORT # The port number of the REST application rest.nameSpace => DSPACE_REST_NAMESPACE # The namespace of the REST application rest.ssl => DSPACE_REST_SSL # Whether the angular REST uses SSL [true/false] # Other examples defaultLanguage => DSPACE_DEFAULTLANGUAGE mediaViewer.video => DSPACE_MEDIAVIEWER_VIDEO # NOTE: At this time, only string/boolean/number based settings can be overridden in Environment variables Multi-valued setting examples # If a setting can have multiple values (e.g. theme names), then use an index number (starting with zero) # to specify the multiple values. # The below example is equivalent to: # themes: # - name: 'dspace' # - name: 'mytheme' # handle: '10673/123' DSPACE_THEMES_0_NAME = 'dspace' DSPACE_THEMES_1_NAME = 'mytheme' DSPACE_THEMES_1_HANDLE = '10673/123'
- Or, by creating Or, by creating a
.env
(environment) file in the project root directory and setting the environment variables in that location.
...
The "rateLimiter" sub-section can be used to protect against a DOS (denial of service) attack when the UI is processed on the server side (i.e. server-side rendering). Default settings are usually OK. In Angular, server-side rendering occurs to support better Search Engine Optimization (SEO), as well as to support clients which cannot use Javascript. See also Angular's docs on Server-side rendering.
REST API Settings
The "rest" (REST API) section defines which REST API the UI will use. 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
This example is valid if your Backend is publicly available at https://api.mydspace.edu/server/ . Keep in mind that the "port" must always be specified even if it's a standard port (i.e. port 80 for HTTP and port 443 for HTTPS).
Sub-path in frontend URL: When using a subpath (nameSpace) in your UI server base URL (e.g. "http://localhost:4000/mysite/" instead of "http://localhost:4000/"), you must make sure that the URL without the subpath is added to the rest.cors.allowed-origins
list in [dspace]/config/modules/rest.cfg
or the local.cfg
override. The default value used for this configuration assumes that Origin and DSpace URL are identical, but CORS origins do not contain a subpath. Without this change you will see CORS policy errors preventing communication between the frontend and backend servers.
REST API Settings
The "rest" (REST API) section defines which REST API the UI will use. 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
This example is valid if your Backend is publicly available at https://api.mydspace.edu/server/ . Keep in mind that the "port" must always be specified even if it's a standard port (i.e. port 80 for HTTP and port 443 for HTTPS).
Code Block | ||||
---|---|---|---|---|
| ||||
rest:
ssl: true
host: api.mydspace.edu
port: 443
# NOTE | ||||
Code Block | ||||
| ||||
rest:
ssl: true
host: api.mydspace.edu
port: 443
# NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
nameSpace: /server |
...
Code Block | ||
---|---|---|
| ||
rest: { ssl: true, host: 'api.mydspace.edu', port: 443, // NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript nameSpace: '/server' }, |
Cache Settings - General
The "cache" section controls how long objects/responses will remain in the UI cache. The defaults should be OK for most sites.
Code Block | ||||
---|---|---|---|---|
| ||||
cache: # NOTE: how long should objects be cached for by default msToLive: default: 900000 # 15 minutes # control:Default max-age=60 # revalidate browser autoSync: defaultTime: 0 'Cache-Control' HTTP Header to set for all static content (including compiled *.js files) # Defaults to one week. This lets a user's browser know that it can cache these files for one week, # after which they will be "stale" and need to be redownloaded. control: max-age=604800 # one week autoSync: defaultTime: 0 maxBufferSize: 100 timePerMethod: PATCH: 3 # time in seconds |
...
Code Block | ||
---|---|---|
| ||
cache: { // NOTE: how long should objects be cached for by default msToLive: { default: 15 * 60 * 1000, // 15 minutes }, control: 'max-age=60', // revalidate browser autoSync: { defaultTime: 0, maxBufferSize: 100, timePerMethod: {[RestRequestMethod.PATCH]: 3} as any // time in seconds } }, |
Authentication Settings
The "auth" section provides some basic authentication-related settings. Currently, it's primarily settings related to when a session timeout warning will be showed to your users, etc.
Cache Settings - Server Side Rendering (SSR)
Info |
---|
Available in 7.5 or later |
Caching options are also available for the User Interface's "server-side rendering" (which uses Angular Universal). Server-side rendering is used to pre-generate full HTML pages and pass those back to users. This is necessary for Search Engine Optimization (SEO) as some web crawlers cannot use Javascript. It also can be used to immediately show the first HTML page to users while the Javascript app loads in the user's browser.
While server-side-rendering is highly recommended on all sites, it can result in Node.js having to pre-generate many HTML pages at once when a site has a large number of simultaneous users/bots. This may cause Node.js to spend a lot of time processing server-side-rendered content, slowing down the entire site.
Therefore, DSpace provides some basic caching of server-side rendered pages, which allows the same pre-generated HTML to be sent to many users/bots at once & decreases the frequency of server-side rendering.
Two cache options are provide: botCache
and anonymousCache
. As the names suggest, the botCache is used for known web crawlers / bots, while the anonymousCache may be used for all anonymous (non-authenticated) users. By default, only the botCache is enabled. But highly active sites may wish to enable the anonymousCache as well, since it can provide users with a more immediate response when they encounter cached pages.
Note |
---|
Keep in mind, when the "anonymousCache" is enabled, this means that all non-authenticated users will utilize this cache. This cache can result in massive speed improvements (for initial page load), as the majority of users may be interacting with cached content. However, these users may occasionally encounter cached pages which are outdated or "stale" (based on values of "timeToLive" and "allowStale"). This means that these users will not immediately see new updates or newly added content (Communities, Collections, Items) until the cache has refreshed itself. That said, when "timeToLive" is set to a low value (like 10 seconds), this risk is minimal for highly active pages/content. |
Code Block | ||||
---|---|---|---|---|
| ||||
cache:
...
serverSide:
# Set to true to see all cache hits/misses/refreshes in your console logs. Useful for debugging SSR caching issues.
debug: false
# When enabled (i.e. max > 0), known bots will be sent pages from a server side cache specific for bots.
# (Keep in mind, bot detection cannot be guarranteed. It is possible some bots will bypass this cache.)
botCache:
# Maximum number of pages to cache for known bots. Set to zero (0) to disable server side caching for bots.
# Default is 1000, which means the 1000 most recently accessed public pages will be cached.
# As all pages are cached in server memory, increasing this value will increase memory needs.
# Individual cached pages are usually small (<100KB), so max=1000 should only require ~100MB of memory.
max: 1000
# Amount of time after which cached pages are considered stale (in ms). After becoming stale, the cached
# copy is automatically refreshed on the next request.
# NOTE: For the bot cache, this setting may impact how quickly search engine bots will index new content on your site.
# For example, setting this to one week may mean that search engine bots may not find all new content for one week.
timeToLive: 86400000 # 1 day
# When set to true, after timeToLive expires, the next request will receive the *cached* page & then re-render the page
# behind the scenes to update the cache. This ensures users primarily interact with the cache, but may receive stale pages (older than timeToLive).
# When set to false, after timeToLive expires, the next request will wait on SSR to complete & receive a fresh page (which is then saved to cache).
# This ensures stale pages (older than timeToLive) are never returned from the cache, but some users will wait on SSR.
allowStale: true
# When enabled (i.e. max > 0), all anonymous users will be sent pages from a server side cache.
# This allows anonymous users to interact more quickly with the site, but also means they may see slightly
# outdated content (based on timeToLive)
anonymousCache:
# Maximum number of pages to cache. Default is zero (0) which means anonymous user cache is disabled.
# As all pages are cached in server memory, increasing this value will increase memory needs.
# Individual cached pages are usually small (<100KB), so a value of max=1000 would only require ~100MB of memory.
max: 0
# Amount of time after which cached pages are considered stale (in ms). After becoming stale, the cached
# copy is automatically refreshed on the next request.
# NOTE: For the anonymous cache, it is recommended to keep this value low to avoid anonymous users seeing outdated content.
timeToLive: 10000 # 10 seconds
# When set to true, after timeToLive expires, the next request will receive the *cached* page & then re-render the page
# behind the scenes to update the cache. This ensures users primarily interact with the cache, but may receive stale pages (older than timeToLive).
# When set to false, after timeToLive expires, the next request will wait on SSR to complete & receive a fresh page (which is then saved to cache).
# This ensures stale pages (older than timeToLive) are never returned from the cache, but some users will wait on SSR.
allowStale: true |
Authentication Settings
The "auth" section provides some basic authentication-related settings. Currently, it's primarily settings related to when a session timeout warning will be showed to your users, etc.
Code Block | ||||
---|---|---|---|---|
| ||||
auth:
# | ||||
Code Block | ||||
| ||||
auth: # Authentication UI settings ui: # the amount of time before the idle warning is shown timeUntilIdle: 900000 # 15 minutes # the amount of time the user has to react after the idle warning is shown before they are logged out. idleGracePeriod: 300000 # 5 minutes # Authentication REST settings rest: # If the rest token expires in less than this amount of time, it will be refreshed automatically. this amount of time, it will be refreshed automatically. # This is independent from the idle warning. Defaults to automatic refresh when the token will # expire within 2 minutes. Because token expires after 30 minutes by default, this means automatic # Thisrefresh iswould independentoccur fromevery the~28 idle warningminutes. timeLeftBeforeTokenRefresh: 120000 # 2 minutes |
...
Code Block | ||
---|---|---|
| ||
themes: [ // Add additional themes here. In the case where multiple themes match a route, the first one // in this list will get priority. It is advisable to always have a theme that matches // every route as the last one // { // // A theme with a handle property will match the community, collection or item with the given // // handle, and all collections and/or items within it // name: 'custom', // handle: '10673/1233' // }, // { // // A theme with a regex property will match the route using a regular expression. If it // // matches the route for a community or collection it will also apply to all collections // // and/or items within it // name: 'custom', // regex: 'collections\/e8043bc2.*' // }, // { // // A theme with a uuid property will match the community, collection or item with the given // // ID, and all collections and/or items within it // name: 'custom', // uuid: '0958c910-2037-42a9-81c7-dca80e3892b4' // }, // { // // Using the "extends" property allows a theme to extend/borrow from an ancestor theme (by name). // // Wherever a theme component is now found in this themes, its ancestor theme(s) will be checked // // recursively before falling back to default. // name: 'custom-A', // extends: 'custom-B', // // Any of the matching properties above can be used // handle: 10673/34, // }, // { // name: 'custom-B', // extends: 'custom', // handle: 10673/12, // }, // { // // A theme with only a name will match every route // name: 'custom' // }, // { // // This theme will use the default bootstrap styling for DSpace components // name: BASE_THEME_NAME // }, { // The default dspace theme name: 'dspace' // Whenever this theme is active, the following tags will be injected tags will be injected into the <head> of the page. // Example use case: set the favicon based on the active theme. headTags: [ { // Insert <link rel="icon" href="assets/dspace/images/favicons/favicon.ico" sizes="any"/> into the <head> of the page. // Example use casetagName: set the favicon based on the active theme. 'link', attributes: { headTags: [ { 'rel': 'icon', // Insert <link rel="icon" href="'href': 'assets/dspace/images/favicons/favicon.ico" sizes="any"/> into the <head> of the page.', 'sizes': 'any', } }, ... tagName: 'link', attributes: { 'rel': 'icon', 'href': 'assets/dspace/images/favicons/favicon.ico', 'sizes': 'any', } }, ... ] }, ], |
Media Viewer Settings
The DSpace UI comes with a basic, out-of-the-box Media Viewer (disabled by default). This media viewer can support any files which have a MIME Type that begins with either "image/*", "video/*", or "audio/*".
Code Block | ||||
---|---|---|---|---|
| ||||
# Whether to enable media viewer for image and/or video Bitstreams (i.e. Bitstreams whose MIME type starts with 'image' or 'video').
# When "image: true", this enables a gallery viewer where you can zoom or page through images.
# When "video: true", this enables embedded video streaming. This embedded video streamer also supports audio files.
mediaViewer:
image: false
video: false |
As of 7.5 (or later), the Video viewer also supports WebVTT (or VTT) Captioning. Video captioning requires that a WebVTT Caption file (.vtt) be uploaded into the DSpace Item (DSpace is not able to create or generate these .vtt files). Here's an example of how to setup captioning:
- The Item must already have a Bitstream which is a video file (in a "video/*" format) in the ORIGINAL bundle. In this example, we'll assume it is named "myVideo.mp4"
- Upload a corresponding WebVTT Caption file named "
[video-filename]-[languageCode].vtt
" to the ORIGINAL bundle.- For a video named "myVideo.mp4", an English caption file would be named "myVideo.mp4-en.vtt".
- If an additional Spanish language caption file was uploaded, it should be named "myVideo.mp4-es.vtt".
- All WebVTT Caption files MUST use two-letter ISO 639-1 Language Codes. A list of all supported Language Codes can be found in "src/app/item-page/media-viewer/media-viewer-video/language-helper.ts"
- Once the Caption file is uploaded, reload the video viewer (on the Item page). You should now see the "Captions" (or CC) option is now available. (Depending on the browser you use, this option may appear in the lower menu of the video, or require you to open an options menu.) Selecting it will enable captioning in your language of choice.
Code Block | ||
---|---|---|
| ||
// Whether to enable media viewer for image and/or video Bitstreams (i.e. Bitstreams whose MIME type starts with "image" or "video").
// For images, this enables a gallery viewer where you can zoom or page through images.
// For videos, this enables embedded video streaming
mediaViewer: {
image: false,
video: false,
}, |
...
]
},
], |
Media Viewer Settings
The DSpace UI comes with a basic, out-of-the-box Media Viewer (disabled by default). This media viewer can support any files which have a MIME Type that begins with either "image/*", "video/*", or "audio/*".
Code Block | ||||
---|---|---|---|---|
| ||||
# Whether to enable media viewer for image and/or video Bitstreams (i.e. Bitstreams whose MIME type starts with 'image' or 'video').
# When "image: true", this enables a gallery viewer where you can zoom or page through images.
# When "video: true", this enables embedded video streaming. This embedded video streamer also supports audio files.
mediaViewer:
image: false
video: false |
Uploading video captioning files
As of 7.5 (or later), the Video viewer also supports WebVTT (or VTT) Captioning. Video captioning requires that a WebVTT Caption file (.vtt) be uploaded into the DSpace Item (DSpace is not able to create or generate these .vtt files). Here's an example of how to setup captioning:
- The Item must already have a Bitstream which is a video file (in a "video/*" format) in the ORIGINAL bundle. In this example, we'll assume it is named "myVideo.mp4"
- Upload a corresponding WebVTT Caption file named "
[video-filename]-[languageCode].vtt
" to the ORIGINAL bundle.- For a video named "myVideo.mp4", an English caption file would be named "myVideo.mp4-en.vtt".
- If an additional Spanish language caption file was uploaded, it should be named "myVideo.mp4-es.vtt".
- All WebVTT Caption files MUST use two-letter ISO 639-1 Language Codes. A list of all supported Language Codes can be found in "src/app/item-page/media-viewer/media-viewer-video/language-helper.ts"
- Once the Caption file is uploaded, reload the video viewer (on the Item page). You should now see the "Captions" (or CC) option is now available. (Depending on the browser you use, this option may appear in the lower menu of the video, or require you to open an options menu.) Selecting it will enable captioning in your language of choice.
Code Block | ||
---|---|---|
| ||
// Whether to enable media viewer for image and/or video Bitstreams (i.e. Bitstreams whose MIME type starts with "image" or "video").
// For images, this enables a gallery viewer where you can zoom or page through images.
// For videos, this enables embedded video streaming
mediaViewer: {
image: false,
video: false,
}, |
Toggle end-user agreement and privacy policy
Info |
---|
Available in 7.4 or later |
The DSpace UI comes with basic end-user agreement and privacy policy functionality. Since release 7.4 these features can be disabled in a configuration file. More information on what disabling on of these features results in is documented in the default app configuration (see code snippet below).
Code Block | ||||
---|---|---|---|---|
| ||||
info:
# Whether the end user agreement is required before users may use the repository.
# If enabled, the user will be required to accept the agreement before they can use the repository.
# If disabled, the page will not exist and no agreement is required to use the repository
enableEndUserAgreement: false
# Whether the privacy statement should exist or not.
enablePrivacyStatement: false |
By default the features are enabled.
Settings for rendering Markdown, HTML and MathJax in metadata
Info |
---|
Available in 7.4 or later |
The DSpace UI comes with basic end-user agreement and privacy policy functionality. Since release 7.4 these features can be disabled in a configuration file. More information on what disabling on of these features results in is documented in the default app configuration (see code snippet below).
Code Block | ||||
---|---|---|---|---|
| ||||
info:
# Whether the end user agreement is required before users may use the repository.
# If enabled, the user will be required to accept the agreement before they can use the repository.
# If disabled, the page will not exist and no agreement is required to use the repository
enableEndUserAgreement: false
# Whether the privacy statement should exist or not.
enablePrivacyStatement: false |
By default the features are enabled.
...
can support Markdown (using https://commonmark.org/) and MathJax (https://www.mathjax.org) in metadata field values. Both Markdown and MathJax are disabled by default.
HTML is a part of markdown, so enabling the markdown option will ensure HTML tags in metadata field values get rendered as well
Code Block |
---|
# Whether to enable Markdown (https://commonmark.org/) and MathJax (https://www.mathjax.org/)
# display in supported metadata fields. By default, only dc.description.abstract is supported.
markdown:
enabled: false
mathjax: false |
Mathjax will only be rendered if markdown is enabled, so configuring 'markdown.mathjax = true' with 'markdown.enabled = false' will have no effect.
By default, only the "dc.description.abstract" metadata supports these formats when enabled. To enable markdown for other metadata fields, a custom sub-component of the ItemPageFieldComponent has to be created for that metadata field, with the enableMarkdown field set to true. Refer to the ItemPageAbstractFieldComponent component for an example.
Controlled Vocabularies in Search Filters
Info |
---|
Available in 7.4 5 or later |
The DSpace UI can support Markdown (using https://commonmark.org/) and MathJax (https://www.mathjax.org) in metadata field values. Both Markdown and MathJax are disabled by default.
HTML is a part of markdown, so enabling the markdown option will ensure HTML tags in metadata field values get rendered as well
Code Block |
---|
# Whether to enable Markdown (https://commonmark.org/) and MathJax (https://www.mathjax.org/)
# display in supported metadata fields. By default, only dc.description.abstract is supported.
markdown:
enabled: false
mathjax: false |
Mathjax will only be rendered if markdown is enabled, so configuring 'markdown.mathjax = true' with 'markdown.enabled = false' will have no effect.
When using hierarchical controlled vocabularies (e.g. SRSC as described in Authority Control of Metadata Values), it's possible to search using the controlled vocabulary hierarchy via the search filters. To enable this feature, you must specify the filter and vocabulary to enable as follows:
Code Block |
---|
# Which vocabularies should be used for which search filters
# and whether to show the filter in the search sidebar
# Take a look at the filter-vocabulary-config.ts file for documentation on how the options are obtained
vocabularies:
- filter: 'subject'
vocabulary: 'srsc'
enabled: true |
Keep in mind, the "filter" MUST be a valid search filter (e.g. subject, author) as seen on the "/api/discover/facets" REST API endpoint. The "vocabulary" MUST be a valid controlled vocabulary installed in your DSpace backend (under "[dspace]/config/controlled-vocab/" folder based on the documentation at Authority Control of Metadata Values.
When this feature is enabled, you should see a "Browse [filter] tree" link in the search filter on the search results page (and anywhere search filters are shown). This "Browse [filter] tree" link will allow you to select a search filter from within the configured hierarchical vocabularyBy default, only the "dc.description.abstract" metadata supports these formats when enabled. To enable markdown for other metadata fields, a custom sub-component of the ItemPageFieldComponent has to be created for that metadata field, with the enableMarkdown field set to true. Refer to the ItemPageAbstractFieldComponent component for an example.
Universal (Server-side Rendering) Settings
...
Code Block | ||
---|---|---|
| ||
// NOTE: will log all redux actions and transfers in console debug: false |