Page History
...
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 our UI uses the TypeScript language. That said, you do NOT need to be deeply familiar with TypeScript to edit the themes or other configuration files. Much of the syntax is very similar to JSON, which is a common configuration format.
Warning | ||
---|---|---|
| ||
As of DSpace 7.2, the UI configuration format has changed to YAML in order to support runtime configuration. This means that reloading configurations now simply requires restarting the UI (which generally takes a few seconds).
|
Configuration
...
File Format
In DSpace 7.2 and above, the Configuration format is now YAML and is located at ./config/config.*.yaml
. If you are upgrading from 7.0 or 7.1 to 7.2 (or later), you will either need to migrate your old configuration file (from Typescript to YAML) or start fresh. You can migrate your old (7.0 or 7.1) "environment.*.ts" configuration file to the new "config.*.yml" format by running:
Code Block |
---|
yarn env:yaml [relative-path-to-environment.ts] [optional-relative-path-to-YAML]
# For Example, to migrate an old environment.prod.ts file to the new config.prod.yml:
# yarn env:yaml src/environments/environment.prod.ts config/config.prod.yml |
In DSpace 7.1 and 7.0, the Configuration format was a Typescript file and was located at ./src/environments/environment.*.ts
. The structure of this file was essentially a JSON like format.
Configuration Override
In 7.2 or above
The UI configuration files reside in the ./config/
folder in the Angular UI source code. The default configuration is provided in config.yml.
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 config.example.yml
as a starting point.
- For example, create a new
config.dev.yml
file inconfig/
for adevelopment
environment; - For example, create a new
config.prod.yml
file inconfig/
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:
Code Block # "ui" settings environment variables DSPACE_UI_HOST # The host name of the angular application DSPACE_UI_PORT # The port number of the angular application DSPACE_UI_NAMESPACE # The namespace of the angular application DSPACE_UI_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
./config/config.prod.yml
,./config/config.dev.yml
or./config/config.test.yml
files (depending on current mode) - The
./config/config.yml
file - The hardcoded defaults in
./src/config/default-app-config.ts
In 7.1 or 7.0
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:
...
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:
Code Block # "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.
Code Block |
---|
production: true |
UI Core Settings
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.
[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
Note | ||
---|---|---|
| ||
As of 7.2 and above, Angular production mode is automatically enabled whenever you are running the app in Production mode (NODE_ENV=production, or 'yarn start:prod' or 'yarn serve:ssr'). Angular production mode is automatically disabled when you are running the app in Development mode (NODE_ENV=development, or 'yarn start:dev" or 'yarn serve') |
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.
Code Block |
---|
production: true |
UI Core Settings
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.
Code Block | ||||
---|---|---|---|---|
| ||||
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: 60000 # 1 minute
max: 500 # limit each IP to 500 requests per windowMs |
Code Block | ||
---|---|---|
| ||
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 DSpace UI requires that a corresponding language pack file (named with the language code and ending in ".json5") be placed in ./src/assets/i18n/
. See also DSpace 7 Translation - Internationalization (i18n) - Localization (l10n) for information about how to create and contribute these files.
Browse By Settings
Note | ||
---|---|---|
| ||
This section was removed in DSpace 7.2, as "Browse By" settings are now loaded dynamically from the REST API. Therefore, in DSpace 7.2 and above, you can modify the Browse By settings by simply configuring additional indexes using Discovery |
The "browseBy" section allows you to customize which "Browse by" options appear in the "All of DSpace" header menu at the top of your DSpace site. The "id" MUST correspond to the name of a valid Browse index available from your REST API (see documentation on the REST API /api/discover/browses endpoint). It is possible to configure additional indexes on the Backend using Discovery, and any configured index appears in your REST API.
...