hazza/dspace-angular
1
0
Fork 1
mirror of https://github.com/DSpace/dspace-angular.git synced 2025-10-07 10:04:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleanup and readme updates

Browse Source
This commit is contained in:
William Welling
2021-12-07 11:38:48 -06:00
parent 33488ccf40
commit 46bb3e109c
4 changed files with 165 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
README.md
View File

@@ -102,18 +102,18 @@ Installing
### Configuring ### Configuring
Default configuration file is located in `src/environments/` folder. Default configuration file is located in `config/` folder.
To change the default configuration values, create local files that override the parameters you need to change. You can use `environment.template.ts` as a starting point. To change the default configuration values, create local files that override the parameters you need to change. You can use `appConfig.json` as a starting point.
- Create a new `environment.dev.ts` file in `src/environments/` for a `development` environment; - Create a new `appConfig.(dev or development).json` file in `config/` for a `development` environment;
- Create a new `environment.prod.ts` file in `src/environments/` for a `production` environment; - Create a new `appConfig.(prod or production).ts` file in `config/` for a `production` environment;
The server settings can also be overwritten using an environment file. The settings can also be overwritten using an environment file or environment variables.
This file should be called `.env` and be placed in the project root. This file should be called `.env` and be placed in the project root.
The following settings can be overwritten in this file: The following non-convention settings:
```bash ```bash
DSPACE_HOST # The host name of the angular application DSPACE_HOST # The host name of the angular application
@@ -127,23 +127,44 @@ DSPACE_REST_NAMESPACE # The namespace of the REST application
DSPACE_REST_SSL # Whether the angular REST uses SSL [true/false] DSPACE_REST_SSL # Whether the angular REST uses SSL [true/false]
``` ```
All other settings can be set using the following convention for naming the environment variables:
1. replace all `.` with `_`
2. convert all characters to upper case
e.g.
```
cache.msToLive.default => CACHE_MSTOLIVE_DEFAULT
auth.ui.timeUntilIdle => AUTH_UI_TIMEUNTILIDLE
```
The same settings can also be overwritten by setting system environment variables instead, E.g.: The same settings can also be overwritten by setting system environment variables instead, E.g.:
```bash ```bash
export DSPACE_HOST=api7.dspace.org export DSPACE_HOST=api7.dspace.org
``` ```
The priority works as follows: **environment variable** overrides **variable in `.env` file** overrides **`environment.(prod, dev or test).ts`** overrides **`environment.common.ts`** The priority works as follows: **environment variable** overrides **variable in `.env` file** overrides external config set by `APP_CONFIG_PATH` overrides **`appConfig.(prod or dev).json`**
These configuration sources are collected **at build time**, and written to `src/environments/environment.ts`. At runtime the configuration is fixed, and neither `.env` nor the process' environment will be consulted. These configuration sources are collected **at run time**, and written to `dist/browser/assets/appConfig.json` for production and `src/app/assets/appConfig.json` for development.
The configuration file can be externalized by using environment variable `APP_CONFIG_PATH`.
#### Using environment variables in code #### Using environment variables in code
To use environment variables in a UI component, use: To use environment variables in a UI component, use:
```typescript ```typescript
import { environment } from '../environment.ts'; import { AppConfig, APP_CONFIG } from 'src/config/app-config.interface';
...
constructor(@Inject(APP_CONFIG) private appConfig: AppConfig) {}
...
``` ```
This file is generated by the script located in `scripts/set-env.ts`. This script will run automatically before every build, or can be manually triggered using the appropriate `config` script in `package.json` or
```typescript
import { environment } from '../environment.ts';
```
Running the app Running the app
@@ -230,7 +251,7 @@ E2E tests (aka integration tests) use [Cypress.io](https://www.cypress.io/). Con
The test files can be found in the `./cypress/integration/` folder. The test files can be found in the `./cypress/integration/` folder.
Before you can run e2e tests, you MUST have a running backend (i.e. REST API). By default, the e2e tests look for this at http://localhost:8080/server/ or whatever `rest` backend is defined in your `environment.prod.ts` or `environment.common.ts`. You may override this using env variables, see [Configuring](#configuring). Before you can run e2e tests, you MUST have a running backend (i.e. REST API). By default, the e2e tests look for this at http://localhost:8080/server/ or whatever `rest` backend is defined in your `appConfig.prod.json` or `appConfig.json`. You may override this using env variables, see [Configuring](#configuring).
Run `ng e2e` to kick off the tests. This will start Cypress and allow you to select the browser you wish to use, as well as whether you wish to run all tests or an individual test file. Once you click run on test(s), this opens the [Cypress Test Runner](https://docs.cypress.io/guides/core-concepts/test-runner) to run your test(s) and show you the results. Run `ng e2e` to kick off the tests. This will start Cypress and allow you to select the browser you wish to use, as well as whether you wish to run all tests or an individual test file. Once you click run on test(s), this opens the [Cypress Test Runner](https://docs.cypress.io/guides/core-concepts/test-runner) to run your test(s) and show you the results.
@@ -309,49 +330,87 @@ File Structure
``` ```
dspace-angular dspace-angular
├── README.md * This document ├── config *
├── app.yaml * Application manifest file │ └── appConfig.json * Default app config
├── config * Folder for configuration files
│   ├── environment.default.js * Default configuration files
│   └── environment.test.js * Test configuration files
├── docs * Folder for documentation
├── cypress * Folder for Cypress (https://cypress.io/) / e2e tests ├── cypress * Folder for Cypress (https://cypress.io/) / e2e tests
│   ├── integration * Folder for e2e/integration test files │ ├── downloads *
│   ├── fixtures * Folder for any fixtures needed by e2e tests │ ├── fixtures * Folder for e2e/integration test files
│   ├── plugins * Folder for Cypress plugins (if any) │ ├── integration * Folder for any fixtures needed by e2e tests
│   ├── support * Folder for global e2e test actions/commands (run for all tests) │ ├── plugins * Folder for Cypress plugins (if any)
│   └── tsconfig.json * TypeScript configuration file for e2e tests │ ├── support * Folder for global e2e test actions/commands (run for all tests)
│ └── tsconfig.json * TypeScript configuration file for e2e tests
├── docker *
│ ├── cli.assetstore.yml *
│ ├── cli.ingest.yml *
│ ├── cli.yml *
│ ├── db.entities.yml *
│ ├── docker-compose-ci.yml *
│ ├── docker-compose-rest.yml *
│ ├── docker-compose.yml *
│ ├── environment.dev.ts *
│ ├── local.cfg *
│ └── README.md *
├── docs * Folder for documentation
│ └── Configuration.md * Configuration documentation
├── scripts *
│ ├── merge-i18n-files.ts *
│ ├── serve.ts *
│ ├── sync-i18n-files.ts *
│ ├── test-rest.ts *
│ └── webpack.js *
├── src * The source of the application
│ ├── app * The source code of the application, subdivided by module/page.
│ ├── assets * Folder for static resources
│ │ ├── fonts * Folder for fonts
│ │ ├── i18n * Folder for i18n translations
│ │ └── images * Folder for images
│ ├── backend * Folder containing a mock of the REST API, hosted by the express server
│ ├── config *
│ ├── environments *
│ │ ├── environment.prod.ts * Production configuration files
│ │ ├── environment.test.ts * Test configuration files
│ │ └── environment.ts * Default (development) configuration files
│ ├── mirador-viewer *
│ ├── modules *
│ ├── ngx-translate-loaders *
│ ├── styles * Folder containing global styles
│ ├── themes * Folder containing available themes
│ │ ├── custom * Template folder for creating a custom theme
│ │ └── dspace * Default 'dspace' theme
│ ├── index.csr.html * The index file for client side rendering fallback
│ ├── index.html * The index file
│ ├── main.browser.ts * The bootstrap file for the client
│ ├── main.server.ts * The express (http://expressjs.com/) config and bootstrap file for the server
│ ├── polyfills.ts *
│ ├── robots.txt * The robots.txt file
│ ├── test.ts *
│ └── typings.d.ts *
├── webpack *
│ ├── helpers.ts * Webpack helpers
│ ├── webpack.browser.ts * Webpack (https://webpack.github.io/) config for browser build
│ ├── webpack.common.ts * Webpack (https://webpack.github.io/) common build config
│ ├── webpack.mirador.config.ts * Webpack (https://webpack.github.io/) config for mirador config build
│ ├── webpack.prod.ts * Webpack (https://webpack.github.io/) config for prod build
│ └── webpack.test.ts * Webpack (https://webpack.github.io/) config for test build
├── angular.json * Angular CLI (https://angular.io/cli) configuration
├── cypress.json * Cypress Test (https://www.cypress.io/) configuration
├── Dockerfile *
├── karma.conf.js * Karma configuration file for Unit Test ├── karma.conf.js * Karma configuration file for Unit Test
├── LICENSE *
├── LICENSES_THIRD_PARTY *
├── nodemon.json * Nodemon (https://nodemon.io/) configuration ├── nodemon.json * Nodemon (https://nodemon.io/) configuration
├── package.json * This file describes the npm package for this project, its dependencies, scripts, etc. ├── package.json * This file describes the npm package for this project, its dependencies, scripts, etc.
├── postcss.config.js * PostCSS (http://postcss.org/) configuration file ├── postcss.config.js * PostCSS (http://postcss.org/) configuration
├── src * The source of the application ├── README.md * This document
│   ├── app * The source code of the application, subdivided by module/page. ├── SECURITY.md *
│   ├── assets * Folder for static resources ├── server.ts * Angular Universal Node.js Express server
│   │   ├── fonts * Folder for fonts ├── tsconfig.app.json * TypeScript config for browser (app)
│   │   ├── i18n * Folder for i18n translations ├── tsconfig.json * TypeScript common config
│   | └── en.json5 * i18n translations for English ├── tsconfig.server.json * TypeScript config for server
│   │   └── images * Folder for images ├── tsconfig.spec.json * TypeScript config for tests
│   ├── backend * Folder containing a mock of the REST API, hosted by the express server ├── tsconfig.ts-node.json * TypeScript config for using ts-node directly
│   ├── config *
│   ├── index.csr.html * The index file for client side rendering fallback
│   ├── index.html * The index file
│   ├── main.browser.ts * The bootstrap file for the client
│   ├── main.server.ts * The express (http://expressjs.com/) config and bootstrap file for the server
│   ├── robots.txt * The robots.txt file
│   ├── modules *
│   ├── styles * Folder containing global styles
│   └── themes * Folder containing available themes
│      ├── custom * Template folder for creating a custom theme
│      └── dspace * Default 'dspace' theme
├── tsconfig.json * TypeScript config
├── tslint.json * TSLint (https://palantir.github.io/tslint/) configuration ├── tslint.json * TSLint (https://palantir.github.io/tslint/) configuration
├── typedoc.json * TYPEDOC configuration ├── typedoc.json * TYPEDOC configuration
├── webpack * Webpack (https://webpack.github.io/) config directory
│   ├── webpack.browser.ts * Webpack (https://webpack.github.io/) config for client build
│   ├── webpack.common.ts *
│   ├── webpack.prod.ts * Webpack (https://webpack.github.io/) config for production build
│   └── webpack.test.ts * Webpack (https://webpack.github.io/) config for test build
└── yarn.lock * Yarn lockfile (https://yarnpkg.com/en/docs/yarn-lock) └── yarn.lock * Yarn lockfile (https://yarnpkg.com/en/docs/yarn-lock)
``` ```

74
docs/Configuration.md
View File

@@ -1,26 +1,32 @@
# Configuration # Configuration
Default configuration file is located in `src/environments/` folder. All configuration options should be listed in the default configuration file `src/environments/environment.common.ts`. Please do not change this file directly! To change the default configuration values, create local files that override the parameters you need to change. You can use `environment.template.ts` as a starting point. Default configuration file is located in `config/` folder. All configuration options should be listed in the default configuration file `src/config/default-app-config.ts`. Please do not change this file directly! To change the default configuration values, create local files that override the parameters you need to change. You can use `appConfig.json` as a starting point.
- Create a new `environment.dev.ts` file in `src/environments/` for `development` environment; - Create a new `appConfig.(dev or development).json` file in `config/` for `development` environment;
- Create a new `environment.prod.ts` file in `src/environments/` for `production` environment; - Create a new `appConfig.(prod or production).json` file in `config/` for `production` environment;
Some few configuration options can be overridden by setting environment variables. These and the variable names are listed below. Alternatively, create a desired app config file at an external location and set the path as environment variable `APP_CONFIG_PATH`.
e.g.
```
APP_CONFIG_PATH=/usr/local/dspace/config/appConfig.json
```
Configuration options can be overridden by setting environment variables.
## Nodejs server ## Nodejs server
When you start dspace-angular on node, it spins up an http server on which it listens for incoming connections. You can define the ip address and port the server should bind itsself to, and if ssl should be enabled not. By default it listens on `localhost:4000`. If you want it to listen on all your network connections, configure it to bind itself to `0.0.0.0`. When you start dspace-angular on node, it spins up an http server on which it listens for incoming connections. You can define the ip address and port the server should bind itsself to, and if ssl should be enabled not. By default it listens on `localhost:4000`. If you want it to listen on all your network connections, configure it to bind itself to `0.0.0.0`.
To change this configuration, change the options `ui.host`, `ui.port` and `ui.ssl` in the appropriate configuration file (see above): To change this configuration, change the options `ui.host`, `ui.port` and `ui.ssl` in the appropriate configuration file (see above):
``` ```
export const environment = { {
// Angular UI settings. "ui": {
ui: { "ssl": false,
ssl: false, "host": "localhost",
host: 'localhost', "port": 4000,
port: 4000, "nameSpace": "/"
nameSpace: '/'
} }
}; }
``` ```
Alternately you can set the following environment variables. If any of these are set, it will override all configuration files: Alternately you can set the following environment variables. If any of these are set, it will override all configuration files:
@@ -30,21 +36,26 @@ Alternately you can set the following environment variables. If any of these are
DSPACE_PORT=4000 DSPACE_PORT=4000
DSPACE_NAMESPACE=/ DSPACE_NAMESPACE=/
``` ```
or
```
UI_SSL=true
UI_HOST=localhost
UI_PORT=4000
UI_NAMESPACE=/
```
## DSpace's REST endpoint ## DSpace's REST endpoint
dspace-angular connects to your DSpace installation by using its REST endpoint. To do so, you have to define the ip address, port and if ssl should be enabled. You can do this in a configuration file (see above) by adding the following options: dspace-angular connects to your DSpace installation by using its REST endpoint. To do so, you have to define the ip address, port and if ssl should be enabled. You can do this in a configuration file (see above) by adding the following options:
``` ```
export const environment = { {
// The REST API server settings. "rest": {
rest: { "ssl": true,
ssl: true, "host": "api7.dspace.org",
host: 'api7.dspace.org', "port": 443,
port: 443, "nameSpace": "/server"
// NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
nameSpace: '/server'
} }
}; }
``` ```
Alternately you can set the following environment variables. If any of these are set, it will override all configuration files: Alternately you can set the following environment variables. If any of these are set, it will override all configuration files:
@@ -54,6 +65,27 @@ Alternately you can set the following environment variables. If any of these are
DSPACE_REST_PORT=443 DSPACE_REST_PORT=443
DSPACE_REST_NAMESPACE=/server DSPACE_REST_NAMESPACE=/server
``` ```
or
```
REST_SSL=true
REST_HOST=api7.dspace.org
REST_PORT=443
REST_NAMESPACE=/server
```
## Environment variable naming convention
Settings can be set using the following convention for naming the environment variables:
1. replace all `.` with `_`
2. convert all characters to upper case
e.g.
```
cache.msToLive.default => CACHE_MSTOLIVE_DEFAULT
auth.ui.timeUntilIdle => AUTH_UI_TIMEUNTILIDLE
```
## Supporting analytics services other than Google Analytics ## Supporting analytics services other than Google Analytics
This project makes use of [Angulartics](https://angulartics.github.io/angulartics2/) to track usage events and send them to Google Analytics. This project makes use of [Angulartics](https://angulartics.github.io/angulartics2/) to track usage events and send them to Google Analytics.

4
src/config/config.server.ts
View File

@@ -6,7 +6,7 @@ import { AppConfig } from './app-config.interface';
import { Config } from './config.interface'; import { Config } from './config.interface';
import { DefaultAppConfig } from './default-app-config'; import { DefaultAppConfig } from './default-app-config';
import { ServerConfig } from './server-config.interface'; import { ServerConfig } from './server-config.interface';
import { extendConfig } from './config.util'; import { mergeConfig } from './config.util';
import { isNotEmpty } from '../app/shared/empty.util'; import { isNotEmpty } from '../app/shared/empty.util';
const CONFIG_PATH = join(process.cwd(), 'config'); const CONFIG_PATH = join(process.cwd(), 'config');
@@ -78,7 +78,7 @@ const overrideWithConfig = (config: Config, pathToConfig: string) => {
try { try {
console.log(`Overriding app config with ${pathToConfig}`); console.log(`Overriding app config with ${pathToConfig}`);
const externalConfig = fs.readFileSync(pathToConfig, 'utf8'); const externalConfig = fs.readFileSync(pathToConfig, 'utf8');
extendConfig(config, JSON.parse(externalConfig)); mergeConfig(config, JSON.parse(externalConfig));
} catch (err) { } catch (err) {
console.error(err); console.error(err);
} }

6
src/config/config.util.ts
View File

@@ -8,11 +8,11 @@ import { AppConfig } from './app-config.interface';
import { ThemeConfig } from './theme.model'; import { ThemeConfig } from './theme.model';
const extendEnvironmentWithAppConfig = (env: any, appConfig: AppConfig): void => { const extendEnvironmentWithAppConfig = (env: any, appConfig: AppConfig): void => {
extendConfig(env, appConfig); mergeConfig(env, appConfig);
console.log(`Environment extended with app config`); console.log(`Environment extended with app config`);
}; };
const extendConfig = (config: any, appConfig: AppConfig): void => { const mergeConfig = (config: any, appConfig: AppConfig): void => {
const mergeOptions = { const mergeOptions = {
arrayMerge: (destinationArray, sourceArray, options) => sourceArray arrayMerge: (destinationArray, sourceArray, options) => sourceArray
}; };
@@ -32,6 +32,6 @@ const getDefaultThemeConfig = (): ThemeConfig => {
export { export {
extendEnvironmentWithAppConfig, extendEnvironmentWithAppConfig,
extendConfig, mergeConfig,
getDefaultThemeConfig getDefaultThemeConfig
}; };