From a5aaacdf71560f878cb620a2d3d0c522bcd40d2d Mon Sep 17 00:00:00 2001
From: Fabien Forestier <fab.forestier42@gmail.com>
Date: Tue, 27 Aug 2019 17:20:52 +0200
Subject: [PATCH] Add admin-gui documentation and multi env docker build for
angular file
---
docs/architecture/admin-gui.md | 83 +++++++++++++
...i-environments-docker-build-for-angular.md | 111 ++++++++++++++++++
mkdocs.yml | 1 +
3 files changed, 195 insertions(+)
create mode 100644 docs/miscellaneous/multi-environments-docker-build-for-angular.md
diff --git a/docs/architecture/admin-gui.md b/docs/architecture/admin-gui.md
index e69de29..2edf8f7 100644
--- a/docs/architecture/admin-gui.md
+++ b/docs/architecture/admin-gui.md
@@ -0,0 +1,83 @@
+# Admin GUI
+
+## What it does
+
+The Admin GUI is a web user interface dedicated to admin users.
+
+It let them administrate the database of different services such as resources (resources, formats, projections), partners, reuse...
+
+It also has a section that provides logs of the datasets indexation jobs. It can be usefull to track indexation errors, execution time for each task...
+
+## Installation and usage
+
+The interface has been developed with the Angular framework, so you need to have [Node.js](https://nodejs.org/en/download/) installed on your machine in order to run the web application.
+
+Once you have Node.js installed you need to install the Angular CLI. Open a command line and run:
+
+```
+npm install -g @angular/cli
+```
+
+### Configuration
+
+Open the `/src/assets/config/config.json` file and update the configuration in order to match yours.
+
+For more explainations on how the configuration system works refer to the dedicated [section](../miscellaneous/multi-environments-docker-build-for-angular.md).
+
+
+
+### Start the web application
+
+Using the Angular CLI:
+```
+ng serve
+```
+
+or the npm script (which use the Angular CLI)
+```
+npm run start
+```
+
+### Build the application
+
+We defined in the package.json two scripts that can build the application. One that generates an optimized build and the other one an unoptimized build. The optimized build takes longer than the normal one.
+
+Those two scripts contain an option `--max_old_space_size=<nb of max RAM octets the node process can take>`. Make sure the number does not exceed your RAM capacity (you can simply remove the option, it will use the default value: 512mb on 32-bit systems and 1gb on 64-bit systems). By incrising the node process memory limit we decrease the build time.
+
+For development environment (not optimized)
+```
+npm run build:dev
+```
+
+For production environment (optimized)
+```
+npm run build:prod
+```
+
+### Build and deploy with Docker
+
+The related files are:
+- `docker-compose.yml` which indicates what Dockerfile should be used, what image is going to be build, volumes, exposed port...
+- `Dockerfile` which describe the steps to build the docker image.
+
+Some environment variables need to be set before building or running the image. Use the appropriate command to set those variables: `SET` on Windows, `export` on Linux.
+
+```
+export TAG=<version>
+export APP_PORT=<port the application should be running on>
+export CONFIG_FILE_PATH=<path to your config file>
+```
+
+Then to build the image run (you can change prod to dev if you don't want an optimized build):
+```
+docker-compose build --build-arg conf=prod admin-gui
+```
+
+Once the image is built on your machine, run the following command to start a container:
+```
+docker-compose --project-name admin-gui up
+```
+
+## Authentication
+
+It uses the same authentication methods as the portail data web app, so if you have an account you will be able to log in. However only a user belongging to the admin group will be able to create, modify and delete entities. The groups are managed by the api gateway, for more information refer to the [Authentication and Authorization](../miscellaneous/authentication&authorization.md) section.
\ No newline at end of file
diff --git a/docs/miscellaneous/multi-environments-docker-build-for-angular.md b/docs/miscellaneous/multi-environments-docker-build-for-angular.md
new file mode 100644
index 0000000..112de57
--- /dev/null
+++ b/docs/miscellaneous/multi-environments-docker-build-for-angular.md
@@ -0,0 +1,111 @@
+# Multi-environment docker build for Angular app
+
+As we use docker to deploy our application on different environments, we didn't want to build one image per environment but rather have one image representing a version of the application taking a dynamic configuration.
+
+The default Angular environment system doesn't allow that as the env file is compiled and so has to be defined at build time.
+
+To address this issue we implemented an alternative system that reads the configuration from a config.json file located in the assets folder. This happens at the bootstrap of the application in the user browser.
+
+Here is the corresponding code.
+
+At the bootstrap of the app we fetch the config.json file and set a window variable with the retrieved content.
+
+```
+// main.ts
+
+fetch('./assets/config/config.json')
+ .then(response => response.json())
+ .then((config) => {
+ if (!config) {
+ return;
+ }
+
+ // Store the response so that your ConfigService can read it.
+ window['adminGuiEnvConfig'] = config;
+
+ platformBrowserDynamic().bootstrapModule(AppModule)
+ .catch(err => console.log(err));
+
+ });
+```
+
+Then we add a dedicated service `app-config.service.ts` which is added to the `providers` in the app module.
+
+```
+// This class describes the configuration of the project
+export class AppConfig {
+ organizations: {
+ url: string;
+ };
+ ...
+}
+
+// Export the varaible that contains the configuration
+export let APP_CONFIG: AppConfig;
+
+@Injectable()
+export class AppConfigService {
+
+ constructor() { }
+
+ // Method that reads the window variable containing the configuration and initialize
+ // an AppConfig object contained in the export APP_CONFIG variable
+ public load() {
+ return new Promise((resolve, reject) => {
+ const conf = new AppConfig();
+ APP_CONFIG = Object.assign(conf, window['adminGuiEnvConfig']);
+ resolve();
+ });
+ }
+}
+```
+
+Add an APP_INITIALIZER that will call the load method when the application starts and so on initialize the configuration.
+
+```
+// app.module.ts
+
+export function initAppConfig(appConfigService: AppConfigService) {
+ return (): Promise<any> => {
+ return new Promise((resolve, reject) => {
+ appConfigService.load();
+ resolve();
+ });
+ };
+}
+
+@NgModule({
+ ...
+ providers: [
+ AppConfigService,
+ {
+ provide: APP_INITIALIZER,
+ useFactory: initAppConfig,
+ deps: [AppConfigService],
+ multi: true,
+ },
+ ],
+ bootstrap: [AppComponent],
+})
+```
+
+Import and use the APP_CONFIG in your components, services... when you need it.
+
+```
+// Example
+import { APP_CONFIG } from './app-config.service';
+
+@Injectable()
+export class OrganizationService {
+
+ organizationServiceUrl: string;
+
+ private _searchChangeSubject: Subject<any>;
+
+ constructor() {
+ this.organizationServiceUrl = `${APP_CONFIG.organizations.url}organizations/`;
+ }
+}
+
+```
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 07751d7..7e7bf96 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -42,3 +42,4 @@ nav:
- VSCode: miscellaneous/vscode-settings.md
- SASS recommendation: miscellaneous/sass-recommendation.md
- Webapp-auth: miscellaneous/webapp-auth.md
+ - Multi-environment docker build for Angular app: miscellaneous/multi-environments-docker-build-for-angular
--
GitLab