Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
Overview
As the DSpace 7 User Interface is built on Angular.io, it aligns with many of the best practices of that platform & the surrounding community. One example is that Configuration files (along with much of the UI code) use the TypeScript language. That said, you do NOT need to be deeply familiar with TypeScript to edit the configuration files. Much of the syntax is very similar to JSON, which is a common configuration format.
You must rebuild after any configuration change
At this time, you must rebuild the UI anytime you modify a configuration setting. This is because the currently active configuration is in your ./src/environments/environment.ts
which is the compiled/deduped version of your configuration after applying all overrides.
Configuration Override
The UI configuration files reside in the ./src/environments/
folder in the Angular UI source code. The default configuration are in environment.common.ts
in that directory.
To change the default configuration values, you simply create (one or more) local files that override the parameters you need to modify. You can use environment.template.ts
as a starting point.
- For example, create a new
environment.dev.ts
file insrc/environments/
for adevelopment
environment; - For example, create a new
environment.prod.ts
file insrc/environments/
for aproduction
environment;
The "ui" and "rest" sections of the configuration may also be overridden separately via one of the following
By setting any of the following environment variables in your system:
# "ui" settings environment variables DSPACE_HOST # The host name of the angular application DSPACE_PORT # The port number of the angular application DSPACE_NAMESPACE # The namespace of the angular application DSPACE_SSL # Whether the angular application uses SSL [true/false] # "rest" settings environment variables DSPACE_REST_HOST # The host name of the REST application DSPACE_REST_PORT # The port number of the REST application DSPACE_REST_NAMESPACE # The namespace of the REST application DSPACE_REST_SSL # Whether the angular REST uses SSL [true/false]
- Or, by creating a
.env
(environment) file in the project root directory and setting the environment variables in that location.
The override priority ordering is as follows (with items listed at the top overriding all other settings)
- Environment variables
- The ".env" file
- The "environment.prod.ts", "environment.dev.ts" or "environment.test.ts"
- The "environment.common.ts"
Configuration Reference
The following configurations are available in ./src/environments/environment.common.ts
These settings may be overridden as described above
Production Mode
When Production mode is enabled, this enables Angular's runtime production mode and compresses the built application. This should always be enabled in Production scenarios.
production: true
UI Section
The "ui" (user interface) section defines where you want Node.js to run/respond. It may correspond to your primary/public URL, but it also may not (if you are running behind 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.js running on port 4000.
ui: { ssl: false, host: 'localhost', port: 4000, // NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript nameSpace: '/', // The rateLimiter settings limit each IP to a "max" of 500 requests per "windowMs" (1 minute). rateLimiter: { windowMs: 1 * 60 * 1000, // 1 minute max: 500 // limit each IP to 500 requests per windowMs } },
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 Section
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).
rest: { ssl: true, host: 'api.mydspace.edu', port: 443, // NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript nameSpace: '/server' },
Cache Section
The "cache" section controls how long objects/responses will remain in the UI cache. The defaults should be OK for most sites.
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 } },