From 1f017d0b4875a026322840a347684b31c5124876 Mon Sep 17 00:00:00 2001
From: Kostis Trantzas <kostisgtr@gmail.com>
Date: Fri, 9 Feb 2024 19:16:45 +0200
Subject: [PATCH] Main documentation refreshing/housekeeping. It is focused on
a smoother installation guide.
---
doc/contributing/developing.md | 76 ++--
doc/deployment.md | 698 ++++++++++++++++++---------------
doc/index.md | 61 +--
3 files changed, 453 insertions(+), 382 deletions(-)
diff --git a/doc/contributing/developing.md b/doc/contributing/developing.md
index 80fbc0d5..72a79fcf 100644
--- a/doc/contributing/developing.md
+++ b/doc/contributing/developing.md
@@ -1,84 +1,84 @@
# Developing
-Openslice backend services are mainly implemented with Java 17 or above and Spring boot.
+OpenSlice backend services are mainly implemented with Java 17 or above and Spring boot.
-Openslice uses various subsystems and depending on the module would you like to work, other subsystems must be present (you can disable them though in the code, e.g. at application.yml file)
+OpenSlice uses various subsystems and depending on the module would you like to work, other subsystems must be present (you can disable them though in the code, e.g. at docker-compose.yaml file).
To get the latest development branch:
-```
+```bash
wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh
-sudo ./deploy.sh develop [or replace develop with other branch name]
+sudo ./deploy.sh develop #[or replace develop with other branch name]
```
-## Slack
-
-* Slack: https://openslice.slack.com
-
-## General subsystems
+You may follow the [installation process](https://osl.etsi.org/documentation/develop/deployment/), as described at "develop" tagged documentation.
-- Docker and Docker Compose should be installed in your development environment
+To work on a specific subsystem e.g. org.etsi.osl.tmf.api, you must:
-### Consul
-consul service registry should be up and running. You can launch consul with docker:
-`sudo docker run -d --name consul -p 8500:8500 -p 8600:8600 consul`
+1a - Deploy only the core necessary subsystems through:
+```bash
+sudo docker compose --profile dev down;sudo docker compose --profile dev up -d --build
+```
+> Note **--profile dev** that will only deploy the core dependency subsystems, instead of the whole OpenSlice.
-### ActiveMQ
-ActiveMQ is our messaging system. You can launch an instance of ActiveMQ:
-`sudo docker run --name='activemq' -d -e 'ACTIVEMQ_NAME=amqp-srv1' -e 'ACTIVEMQ_REMOVE_DEFAULT_ACCOUNT=true' -e 'ACTIVEMQ_ADMIN_LOGIN=admin' -e 'ACTIVEMQ_ADMIN_PASSWORD=admin' -e 'ACTIVEMQ_WRITE_LOGIN=producer_login' -e 'ACTIVEMQ_WRITE_PASSWORD=producer_password' -e 'ACTIVEMQ_READ_LOGIN=consumer_login' -e 'ACTIVEMQ_READ_PASSWORD=consumer_password' -e 'ACTIVEMQ_JMX_LOGIN=jmx_login' -e 'ACTIVEMQ_JMX_PASSWORD=jmx_password' -e 'ACTIVEMQ_STATIC_TOPICS=topic1;topic2;topic3' -e 'ACTIVEMQ_STATIC_QUEUES=queue1;queue2;queue3' -e 'ACTIVEMQ_MIN_MEMORY=1024' -e 'ACTIVEMQ_MAX_MEMORY=4096' -e 'ACTIVEMQ_ENABLED_SCHEDULER=true' -v /home/ctranoris/testcompose/data/activemq:/data/activemq -v /var/log/activemq:/var/log/activemq -p 8161:8161 -p 61616:61616 -p 61613:61613 webcenter/activemq:5.14.3`
+1b - Or alternatively, commend out the respective container from the docker-compose.yaml file, so as to deploy the whole OpenSlice, except the subsystem you want to work on, following the provided installation steps.
-### MySQL server
-We use mysql as a storage DB. Please make sure that you have it installed in your system. There are instructions on internet how to install it. Check also our docker-compose installation script
+2 - Clone the respective repository, e.g. https://labs.etsi.org/rep/osl/code/org.etsi.osl.tmf.api/-/tree/develop
+3 - Code :)
-## Oauth server
+## General requirements
-Keycloak is used as the authentication server.
+- Docker should be installed in your development environment
+- Run the core subsystems (see above sections)
-> Note: Please check the Post installation steps -> Keycloak at localhost, at [Deployment/Installation](../deployment.md), if you are developing in a local environment
+## Slack
-## VNF/NSD Catalog Management and NSD Deployment API service
+Feel free to join OpenSlice [Slack](https://openslice.slack.com) for any development oriented questions
-Clone the repository: https://github.com/openslice/org.etsi.osl.portal.api
+## Examples on developing on specific subsystems
-Check the application.yml file. Default port is 13080. Especially the datasource username/password, server port.
+### VNF/NSD Catalog Management and NSD Deployment API service
-make sure that the General subsystems are up and running as well as the OAuth server
+Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.api/-/tree/develop
-run it with `mvn spring-boot:run`
+Check the docker-compose.yml file. Default port is 13080. Check specifically the datasource username/password, server port.
-You can check your consul server if it registered.
+Make sure that the core subsystems are up and running.
-### Swagger API
-Swagger API of the service is at `http://localhost:13000/osapi/swagger-ui/`. You can try there various REST actions and authenticate via the OAuth server
+Execute it with
+```bash
+mvn spring-boot:run
+```
+For verification, Swagger API of the service is at `http://localhost:13000/osapi/swagger-ui/index.html`.
-## VNF/NSD Catalog Management and NSD Deployment WEB UI service
+There, you may try there various REST actions and authenticate via the OAuth server without the use of the UI.
-The Web UI is written in AngularJS
-Clone the repository: https://github.com/openslice/org.etsi.osl.portal.web
+### VNF/NSD Catalog Management and NSD Deployment WEB UI service
-by default the project org.etsi.osl.portal.api exposes the folder ../org.etsi.osl.portal.web/src/ in a folder testweb (Check class MvcConfig.java in org.etsi.osl.portal.api) for development. (In production nginx is used). Point your browser to `http://localhost:13000/osapi/testweb/index.html/`
+The Web UI is written in AngularJS.
+Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.web/-/tree/develop
----
+By default the project org.etsi.osl.portal.api exposes the folder ../org.etsi.osl.portal.web/src/ in a folder testweb (Check class MvcConfig.java in org.etsi.osl.portal.api) for development. (In production nginx is used). Point your browser to `http://localhost:13000/osapi/testweb/index.html/`
## Version/release management
-Check this nice article on how we develop and release versions
+Check this nice article on how we develop and release versions.
https://nvie.com/posts/a-successful-git-branching-model/
-We develop in the develop branch
+We develop in the develop branch and follow a issue driven development model.
---
## Wishlist
-Check also our wishlist of new features. You can add your own
+Check also our wishlist of new features. You can add your own.
-See [Wishlist](./wishlist.md)
+See [Wishlist](./wishlist.md).
diff --git a/doc/deployment.md b/doc/deployment.md
index 09e6712e..197d693a 100644
--- a/doc/deployment.md
+++ b/doc/deployment.md
@@ -1,274 +1,512 @@
-# Preparing the environment
+## Requirements
-Note: See the Kubernetes section, if you would like to deploy Openslice in a Kubernetes cluster
+### Hardware requirements:
-<br>
-1 - Backup your previous database if necessary:
-```
+| **Minimum Hardware Requirements** | **Recomended Hardware Requirements** |
+| --------------------------------- | ------------------------------------ |
+| 4 CPU cores | 8 CPU cores |
+| 8 GB RAM | 16 GB RAM |
+| 20 GB storage | 40 GB storage |
+
+### Software Requirements:
+
+* Docker (Docker Compose installation)
+* Kubernetes (Kubernetes installation - experimental)
+
+
+## Preparing the environment
+
+> See the [Kubernetes section](##Kubernetes-installation), if you would like to deploy OpenSlice in a Kubernetes cluster.
+
+
+### 1. Backup your previous database if necessary:
+```bash
sudo docker exec amysql /usr/bin/mysqldump -u root --password=letmein ostmfdb > backup_ostmfdb.sql
```
+### 2. Install docker
- 2 - Install docker
-
-_NOTE:_ Since July 2023 Docker Compose V1 stopped receiving updates. Openslice fully reverted to Compose V2, which is integrated in the Docker installation.
+> Since July 2023 Docker Compose V1 stopped receiving updates. OpenSlice fully reverted to Compose V2, which is integrated in the Docker installation.
+### 3. Configure containers to properly resolve the DNS of your domain (optional)
-3 - Download environment preparation script
```
-wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/main/compose/deploy.sh
+sudo nano /etc/docker/daemon.json
```
-4 - Work with main/master branch:
+and add:
```
-sudo ./deploy.sh
+{
+ "dns": ["8.8.8.8", "8.8.4.4"]
+}
```
-Alternatively, work with develop or any other branch:
+After editing daemon.json restart docker daemon for the changes to take place
-```
-sudo ./deploy.sh develop [or replace develop with other branch name]
+```bash
+sudo systemctl restart docker
```
-5 - Create configuration specific docker compose file
+## Downloading the project
+
+### 1. Create a new folder to download the project
+
+```bash
+mkdir openslice
```
-cd org.etsi.osl.main/compose/
-sudo cp docker-compose.yaml.configure docker-compose.yaml
+```bash
+cd openslice
```
-6 - Configure containers to properly resolve the DNS of your domain
+### 2. Download the deployment script
-edit /etc/docker/daemon.json and add:
+Download the deployment / environment preparation script
+```bash
+wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/main/compose/deploy.sh
```
-{
- "dns": ["8.8.8.8", "8.8.4.4"]
-}
+Make it executable
+```bash
+sudo chmod +x deploy.sh
```
-and restart docker daemon.
+### 3. Run the deployment script
-<br>
+OpenSlice is a multi repo project. This script selects the same branch for all repositories of the project to pull from.
-# Configure docker-compose services
+After that it builds the respective jar files locally and installs all the npm packages needed for the UI.
+If you run the script without selecting a branch the the main branch is going to be selected.
-Edit your configuration specific docker-compose.yaml that is previously created:
+We recommend:
-<br>
+* main branch for the most stable experience and
+* develop branch for an experience with the latest features (for develop branch installation, it is strongly advisable that you may as well follow the [develop documentation](https://osl.etsi.org/documentation/develop/deployment/))
-## 1. mysql-portal container
+```bash
+sudo ./deploy.sh main #[or replace main with other branch name]
+```
-In folder mysql-init edit the file 01-databases.sql. Edit the credentials that services connect to the database (if you wish) of portaluser (default is 12345) and keycloak (default is password).
+> **We recommend running the deploy.sh script with root permissions! In other case, some directories may not be accessible by the project building tools and hinder the smooth installation.**
-delete the exposed ports
-## 2.keycloak container
+## Configure docker-compose services
-2.1 Edit the following if you changed mysql credentials
+### 1. Create configuration specific Docker Compose file from the template
+
+```bash
+cd org.etsi.osl.main/compose/
```
-DB_DATABASE: keycloak
-DB_USER: keycloak
-DB_PASSWORD: password
+```bash
+sudo cp docker-compose.yaml.configure docker-compose.yaml
```
+### 2. Configure mysql-portal container *(optional)*
-2.2 Change the keycloak admin password
-```
-KEYCLOAK_PASSWORD: Pa55w0rd
-```
+1. In folder `org.etsi.osl.main/compose/mysql-init` edit the file `01-databases.sql`.
+2. In the `org.etsi.osl.main/compose/docker-compose.yaml` edit the credentials of the users that services use to connect to the databases, if you wish.
+ * portaluser (default is 12345) and
+ * keycloak (default is password)
-## 3.osportalapi container (NFV services)
+### 3. Configure keycloak container *(optional)*
-Edit the following if you changed mysql and keycloak credentials and adjust properly the domain (if you are using a non-local domain, replace everywhere the http://keycloak:8080)
+1. If you made changes to keycloak's mysql credentials:
-```
-SPRING_APPLICATION_JSON: '{
- "spring.datasource.url": "jdbc:mysql://amysql/osdb?createDatabaseIfNotExist=true",
- "spring.datasource.username":"root",
- "spring.datasource.password":"letmein",
- "spring-addons.issuers[0].uri": "http://portal.openslice.io/auth/realms/openslice",
- "spring-addons.issuers[0].username-json-path":"$.preferred_username",
- "spring-addons.issuers[0].claims[0].jsonPath":"$.realm_access.roles",
- "spring-addons.issuers[0].claims[1].jsonPath":"$.resource_access.*.roles",
- "spring.security.oauth2.resourceserver.jwt.issuer-uri": "http://portal.openslice.io/auth/realms/openslice",
- "springdoc.oAuthFlow.authorizationUrl": "http://portal.openslice.io/auth/realms/openslice/protocol/openid-connect/auth",
- "springdoc.oAuthFlow.tokenUrl": "http://portal.openslice.io/auth/realms/openslice/protocol/openid-connect/token",
- "springdoc.oauth.client-id" : "osapiWebClientId",
- "springdoc.oauth.clientsecret" : "secret",
- "spring.activemq.brokerUrl": "tcp://anartemis:61616?jms.watchTopicAdvisories=false",
- "spring.activemq.user": "artemis",
- "spring.activemq.password": "artemis",
- "logging.level.org.springframework" : "INFO"
+ In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`.
+ ```yaml
+ DB_DATABASE: keycloak
+ DB_USER: keycloak
+ DB_PASSWORD: password
+ ```
-```
+2. If you want to change the keycloak admin password:
+ In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`
-## 4.bugzilla container
+ ```yaml
+ KEYCLOAK_PASSWORD: Pa55w0rd
+ ```
-If you would like to use the Bugzilla connector
+### 4. Configure bugzilla container *(optional)*
-```
+If you want to utilise the Bugzilla connector:
+
+In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`
+ ```yaml
+ SPRING_APPLICATION_JSON: '{
+ "spring.activemq.brokerUrl": "tcp://anartemis:61616?jms.watchTopicAdvisories=false",
+ "spring.activemq.user": "artemis",
+ "spring.activemq.password": "artemis",
+ "bugzillaurl":"",
+ "bugzillakey":"",
+ "main_operations_product":""
+ }'
+ ```
+And add the provided Bugzilla installation information:
+```yaml
"bugzillaurl":"bugzillaurl.xx:443/bugzilla/",
"bugzillakey":"exampleKeyeqNNwxBlgxZgMEIne0Oeq0Bz",
-"main_operations_product":"Main Site Operations" //this is the default product to issue tickets
+"main_operations_product":"Main Site Operations" // this is the default product to issue tickets
```
-Bugzilla under this product should have components:
+Bugzilla should have the following components under the specified product:
- NSD Deployment Request: Component used to schedule deployment req
- Onboarding: Issues related to VNF/NSD Onboarding
- Operations Support: Default component for operations support
- Validation: Use to track validation processes of VNFs and NSDs
- VPN Credentials/Access: Used for requesting VPN Credentials/Access
+Also in the 'Main Site Operations' product, a version named 'unspecified' must be created.
-Also in the 'Main Site Operations' product, please create a version named 'unspecified'
+### 5. Configure osportalapi container (NFV services) *(conditional)*
+Change the respective fields:
-## 5.osscapi container (TMF-API service)
+- If you made changes to mysql and keycloak credentials.
+- If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR).
-Edit the following if you changed mysql and keycloak credentials
+> **If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}, as well as "spring.portal.main.domain" property.**
-```
-"spring.datasource.username":"xx",
-"spring.datasource.password":"xx",
-"keycloak-admin-password": "Pa55w0rd",
-Edit properly with your domain "swagger.authserver" : "http://localhost/auth/realms/openslice",
+In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`
+ ```yaml
+ SPRING_APPLICATION_JSON: '{
+ "spring.datasource.username":"root",
+ "spring.datasource.password":"letmein",
+ "spring-addons.issuers[0].uri": "http://keycloak:8080/auth/realms/openslice",
+ "spring.security.oauth2.resourceserver.jwt.issuer-uri": "http://keycloak:8080/auth/realms/openslice",
+ "springdoc.oAuthFlow.authorizationUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth",
+ "springdoc.oAuthFlow.tokenUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token",
+ "spring.portal.main.domain": "http://localhost",
+ "logging.level.org.springframework" : "INFO"
+ }'
+ ```
+
+### 6. osscapi container (TMF API service) *(conditional)*
+
+Change the respective fields:
+
+- If you made changes to mysql and keycloak credentials.
+- If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR).
+
+> **If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}.**
+In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`
+```yaml
+ SPRING_APPLICATION_JSON: '{
+ "spring.datasource.username":"root",
+ "spring.datasource.password":"letmein",
+ "spring-addons.issuers[0].uri": "http://keycloak:8080/auth/realms/openslice",
+ "spring.security.oauth2.resourceserver.jwt.issuer-uri": "http://keycloak:8080/auth/realms/openslice",
+ "springdoc.oAuthFlow.authorizationUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth",
+ "springdoc.oAuthFlow.tokenUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token",
+ "logging.level.org.springframework" : "INFO"
+ }'
```
-Delete the exposed ports in other services like activemq
+## Configure nginx
-<br>
+In folder `org.etsi.osl.main/compose/nginx` create a configuration specific `nginx.conf` file.
-# Configure nginx
+```bash
+cd org.etsi.osl.main/compose/nginx/
```
-cd nginx
+```bash
sudo cp nginx.conf.default nginx.conf
```
-Edit server_name
+If needed, in the nginx.conf file, edit the server_name for an non-local deployment.
+
-<br>
-# Configure Web UI
+## Configure Web UI
+In folder `org.etsi.osl.portal.web/src/js/` create a configuration specific `config.js` file.
+```bash
+cd org.etsi.osl.portal.web/src/js
```
-cd org.etsi.osl.portal.web/src/js/
-cp config.js.default config.js
+```bash
+sudo cp config.js.default config.js
```
+Edit the `config.js` file with the information of your domain
-Edit config.js with your domain
-
-```
-TITLE: "Openslice demo",
- WIKI: "http://localhost",
- BUGZILLA: "https://localhost/bugzilla/",
- STATUS: "http://status.localhost/",
- APIURL: "http://localhost",
- WEBURL: "http://localhost",
- APIOAUTHURL: "http://localhost/auth/realms/openslice",
- APITMFURL: "http://localhost/tmf-api/serviceCatalogManagement/v4"
+```yaml
+{
+ TITLE: "OpenSlice by ETSI",
+ WIKI: "https://openslice.readthedocs.io/en/stable/",
+ BUGZILLA: "ROOTURL/bugzilla/",
+ STATUS: "ROOTURL/status/",
+ APIURL: "http://localost:13000",
+ WEBURL: "ROOTURL/nfvportal",
+ APIOAUTHURL: "ROOTURL/auth/realms/openslice",
+ APITMFURL: "ROOTURL/tmf-api/serviceCatalogManagement/v4"
+}
```
-<br>
-
-# Configure TMF Web UI
+## Configure TMF Web UI
-There are 3 files available for configuration:
+In the folder `org.etsi.osl.tmf.web/src/assets/config` there are 3 files available for configuration:
* config.prod.json (Basic information + API configuration)
* theming.scss (CSS color palette theming)
* config.theming.json (HTML configuration - Logo, Favicon, Footer)
-The first 2 files above (i.e. config.prod.json, theming.scss) are essential for the successful deployment of Openslice, thus created automatically during the initial deployment at **org.etsi.osl.tmf.web/src/assets/config** directory as a copy of the default ones from the remote repository.
+The first 2 files above (i.e. config.prod.json, theming.scss) are essential for the successful deployment of OpenSlice, thus created automatically during the initial deployment at `org.etsi.osl.tmf.web/src/assets/config` directory as a copy of the default ones from the remote repository.
-<br>
-
-Ensure that you check the **config.prod.json** file and readjust to your deployment if needed.
+Ensure that you check the `config.prod.json` file and readjust to your deployment if needed.
-```
+```bash
+# Starting from the root project directory
cd org.etsi.osl.tmf.web/src/assets/config
```
-and edit config.prod.json
+```bash
+sudo cp config.theming.default.json config.theming.json
+```
+
+E.g. Edit "TITLE" or "WIKI" property with your domain title
+```yaml
+{
+ TITLE: "OpenSlice by ETSI",
+ WIKI: "https://osl.etsi.org/documentation/latest/deployment/",
+}
+```
-E.g. Edit "TITLE" or "WIKI" property with your domain title
+> The {BASEURL} placeholder in the file automatically detects the Origin (Protocol://Domain:Port) of the deployment and applies it to every respective property. E.g. If you are attempting a local deployment of Openslice, then {BASEURL} is automatically translated to "http://localhost". Similarly, you may use {BASEURL} to translate to a public deployment configuration, e.g. "https://portal.openslice.io".
+If further customization, apart from the default provided, is needed for branding (Logo, Footer) then config.theming.json needs to be created in io.openslice.tmf.web/src/assets/config directory, as follows:
+
+```bash
+# Starting from the root project directory
+cd org.etsi.osl.tmf.web/src/assets/config
```
-TITLE: 'Openslice',
-WIKI: 'https://openslice.io',
+```bash
+sudo cp config.theming.default.json config.theming.json
```
-_NOTE:_ The {BASEURL} placeholder in the file automatically detects the Origin (Protocol://Domain:Port) of the deployment and applies it to every respective property. E.g. If you are attempting a local deployment of Openslice, then {BASEURL} is automatically translated to "http://localhost". Similarly, you may use {BASEURL} to translate to a public deployment configuration, e.g. "https://portal.openslice.io".
+> ***IMPORTANT NOTE:***
+If you want to apply changes to the JSON configuration files without the need to rebuild the
+application, you have to apply the changes at the `org.etsi.osl.tmf.web/dist/io-openslice-portal-web/assets/config`
+directory. Although, it is <u>mandatory</u> to also apply these changes to the `org.etsi.osl.tmf.web/src/assets/config`
+for <u>persistancy</u>, as after any future rebuild of OpenSlice the `/dist` directory is being overwritten along with its
+contents. The OpenSlice team strongly recommends to always apply your changes to the TMF web UI configuration files
+at `org.etsi.osl.tmf.web/src/assets/config` and rebuild the application.
-<br>
+## Deploy OpenSlice via Docker Compose
-If further customization, apart from the default provided, is needed for branding (Logo, Footer) then **config.theming.json** needs to be created in **org.etsi.osl.tmf.web/src/assets/config** directory, as follows:
+After configuring the services, and editing the docker compose file accordingly, the docker compose instantiation command can be performed.
+```bash
+# Starting from the root project directory
+cd org.etsi.osl.main/compose/
```
-cd org.etsi.osl.tmf.web/src/assets/config
-sudo cp config.theming.default.json config.theming.json
+```bash
+sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build
```
-<br>
+> Depending on your machine, this process might take time. if for any reason the deployment fails during first time, please rerun the above before any further measures.
-> **_IMPORTANT NOTE:_** If you want to apply changes to the JSON configuration files without the need to rebuild the application, you have to apply the changes at the **org.etsi.osl.tmf.web/dist/io-openslice-portal-web/assets/config** directory. Although, it is <u>mandatory</u> to also apply these changes to the **org.etsi.osl.tmf.web/src/assets/config** for <u>persistancy</u>, as after any future rebuild of Openslice the **/dist** directory is being ovewritten along with its contents. The Openslice team strongly recommends to always apply your changes to the TMF web UI configuration files at **org.etsi.osl.tmf.web/src/assets/config** and rebuild the application.
-<br>
+## Validating deployments and container monitoring
+
+You can monitor containers' status with portainer at port 9000 (http://your-ip:9000).
+Initially, you may monitor the local machine at portainer.
-# Deploying docker compose
+Please check that all containers are in running state.
+## Post installation steps
+After the successful deployment of OpenSlice, to ensure the E2E user experience, **this section is mandatory**. It contains crucial configuration in regard of authentication and user creation.
-Go to compose directory and issue:
-```
-sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build
-```
+### Configure Keycloak server
-Note: Depending on your machine, this process might take time.
+The Keycloack server is managing authentication and running on a container at port 8080. It is also proxied to your host via nginx under http://localhost/auth.
+- Navigate to http://domain.com/auth/ or https://domain.com/auth/, (http://ipaddress:8080/auth/ or https://ipaddress:8443/auth/ which are directly accessible without proxy)
-<br>
+- Navigate to Administration Console
+- Login with the credentials from section [Configure keycloak container](#Configure-keycloak-container). Default values are:
+ - user: admin and
+ - password: KEYCLOAK_PASSWORD
-# Validating deployments and container monitoring
+> if you are running in HTTP you will get a message: HTTPS required.
-You can monitor containers status with portainer at port 9000 (http://your-ip:9000)
+To resolve this issue <u>when running in HTTP</u>:
-Initially, you may monitor the local machine at portainer.
+- Select the master realm from top left corner
+- Go to login Tab and select "Require SSL": None
+- Repeat for realm Openslice
+
+
+> If you are running in HTTPS, then "Require SSL" can be left unchanged to external requests.
+
+#### 1. Configure redirects
+
+Navigate to realm Openslice > client > osapiWebClientId and change the Root URL to your domain.
+
+Also, insert your domain, e.g. http://example.org/*, at:
+* Valid Redirect URIs
+* Web Origins
+
+#### 2. Configure email
+
+Keycloak allows new users to register. Subsequently, this will also allow new users to register to the OpenSlice portal.
+
+On Tab Login > check User registration, Verify email, Forgot password etc.
+
+Also, enter the details on Realm > Email > Enable Authentication.
+
+#### 3. Add an OpenSlice admin user
+
+This step is mandatory so as to access the OpenSlice Web UI. To add an OpenSlice admin user you must:
+- Navigate to manage/users and add an OpenSlice admin user, e.g. username=admin.
+- Set a password
+- Navigate to Role Mappings and add ADMIN and MENTOR to Assigned Roles.
+
+> That user is different from the Keycloak admin user. It is required to login and browse the OpenSlice Web UI. The Roles ADMIN and MENTOR guarantee full access through the Openslice UI, thus such a user is always required.
+
+### Keycloak at localhost
+
+> **This is an important step if you run Keycloak on localhost!**
+
+1 - Edit your Hosts File, adding the line below
+
+```127.0.0.1 keycloak```
+
+Hosts File Location:
+
+ - In Linux/Unix, the file's location is at /etc/hosts
+
+ - In Windows, its location is at c:\Windows\System32\Drivers\etc\hosts
+
+2 - Replace http://localhost/auth/ with http://keycloak:8080/auth/ in your Keycloak config for AngularJS and Angular (see examples below).
+
+
+Explanation:
+
+ Nginx uses the http://keycloak:8080 URL, which is accessible via the internal docker system's network.
+ The Front-end (TS/Angular) shall also use the http://keycloak:8080.
+ This way, you will not get the invalid token error, as the API is acquiring the token from http://keycloak:8080 (internally) and the Front-end is getting verified by an issuer at the same URL, as well.
+
+
+
+- For the Angular configuration (TMF portal UI), navigate to org.etsi.osl.tmf.web/src/assets/config and edit config.prod.json
+ ```bash
+ # Starting from the root project directory
+ cd org.etsi.osl.tmf.web/src/assets/config
+ ```
+ ```bash
+ nano config.prod.json
+ ```
+
+ After editing it should look like the example bellow:
+ ```yaml
+ {
+ "TITLE": "OpenSlice by ETSI",
+ "PORTALVERSION":"2023-Q3 1.2.0-SNAPSHOT",
+ "WIKI": "https://openslice.readthedocs.io/en/stable/",
+ "BUGZILLA": "{BASEURL}/bugzilla/",
+ "STATUS": "http://status.localhost/",
+ "WEBURL": "{BASEURL}",
+ "PORTAL_REPO_APIURL": "{BASEURL}/osapi",
+ "ASSURANCE_SERVICE_MGMT_APIURL": "{BASEURL}/oas-api",
+ "APITMFURL": "{BASEURL}/tmf-api",
+ "OAUTH_CONFIG" : {
+ "issuer": "http://keycloak:8080/auth/realms/openslice",
+ "loginUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth",
+ "tokenEndpoint": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token",
+ "userinfoEndpoint": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/userinfo",
+ "redirectUri": "{BASEURL}/redirect",
+ "logoutUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/logout",
+ "postLogoutRedirectUri": "{BASEURL}",
+
+ "responseType": "code",
+ "oidc": false,
+ "clientId": "osapiWebClientId",
+ "dummyClientSecret": "secret",
+
+ "requireHttps": false,
+ "useHttpBasicAuth": true,
+ "clearHashAfterLogin": false,
+
+ "showDebugInformation": true
+ }
+ }
+ ```
+
+ > Note the difference in changing {BASEURL} -> http://keycloak:8080
+
+ > If you want the changes to take place immediately without rebuilding the project, then repeat the process for org.etsi.osl.tmf.web/dist/org.etsi.osl.tmf.web/assets/config/config.prod.json
+
+- For the AngularJS configuration (NVF portal UI), navigate to org.etsi.osl.portal.web/src/js and edit config.js
+ ```bash
+ # Starting from the root project directory
+ cd org.etsi.osl.portal.web/src/js
+ ```
+ ```bash
+ nano config.js
+ ```
+ after editing it should look like the example bellow:
+
+ ```js
+ var appConfig = angular.module('portalwebapp.config',[]);
+
+
+ appConfig.factory('APIEndPointService', function() {
+ return {
+ TITLE: "OpenSlice by ETSI",
+ WIKI: "https://openslice.readthedocs.io/en/stable/",
+ BUGZILLA: "ROOTURL/bugzilla/",
+ STATUS: "ROOTURL/status/",
+ APIURL: "http://localost:13000",
+ WEBURL: "ROOTURL/nfvportal",
+ APIOAUTHURL: "ROOTURL/auth/realms/openslice",
+ APITMFURL: "ROOTURL/tmf-api/serviceCatalogManagement/v4"
+ };
+ });
+ ```
+ > Note the difference in "APIOAUTHURL" property
+
+
+### NFV Orchestrator Configuration
+
+After successfully deploying and configuring OpenSlice, you may configure its environment (e.g. the NFVO) that will facilitate the deployment of NFV artifacts.
+
+See [NFV Orchestrator Configuration](./nfvoconfig.md).
-Please check that all containers are in running state.
<br>
-# Kubernetes installation
+## Kubernetes installation
+
+Openslice can be installed in a Kubernetes cluster.
+**This is a work in progress, and should be used for stable deployments!**.
-Openslice can be installed in a Kubernetes cluster. (This is a work in progress)
+Please reference "develop" tagged documentation for any latest progress.
The related scripts are inside the kubernetes folder. Follow these steps along the lines. You need to configure the ingress properly depending on how you want to expose Openslice.
-1) Create an openslice namespace
+1 - Create an openslice namespace
-```
+```bash
kubectl create namespace openslice
```
-2) Apply or create an ingress. Ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster. Traffic routing is controlled by rules defined on the Ingress resource.
+2 - Apply or create an ingress. Ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster. Traffic routing is controlled by rules defined on the Ingress resource.
An Ingress may be configured to give Services externally-reachable URLs, load balance traffic, terminate SSL / TLS, and offer name-based virtual hosting. An Ingress controller is responsible for fulfilling the Ingress, usually with a load balancer, though it may also configure your edge router or additional frontends to help handle the traffic. You must have an Ingress controller to satisfy an Ingress.
You may need to deploy an Ingress controller such as ingress-nginx.
You can also adapt it to connect to public cloud load balancers depending on your needs.
-The following will expose an ingress resource from one of your a k8s nodes on port 80
+The following will expose an ingress resource from one of your a k8s nodes on port 80.
-```
+```bash
kubectl apply -f openslice-ingress.yaml
```
@@ -276,7 +514,7 @@ The following will expose an ingress resource from one of your a k8s nodes on po
Finding the ingress IP:
-```
+```bash
kubectl describe -f openslice-ingress.yaml
@@ -304,16 +542,16 @@ Events:
From the above example, our exposed ingress is at Address: 10.10.10.35
-3) We need to configure the expose address and deploy openslice (IP or URL e.g. http://myopenslice.xxx)
+3 - We need to configure the expose address and deploy openslice (IP or URL e.g. http://myopenslice.xxx)
-```
+```bash
./k8sdeploy.sh 10.10.10.35
```
-4) Check the status of Openslice in the cluster. Should be similar to the following:
+4 - Check the status of Openslice in the cluster. Should be similar to the following:
-```
+```bash
kubectl get pods --namespace=openslice -o wide
@@ -330,8 +568,8 @@ osportalapi-5fff744db8-5g4zs 1/1 Running 0 103s 192.168.4
osscapi-6d68b54d97-jn8tz 0/1 Running 0 102s 192.168.12.104 kc-3 <none> <none>
portalweb-8469d57df4-94tfj 1/1 Running 0 101s 192.168.48.44 kc-nfs <none> <none>
tmfweb-868f7bb9c5-x4lfh 1/1 Running 0 102s 192.168.48.43 kc-nfs <none> <none>
-
-
+```
+```bash
kubectl get deployments --namespace=openslice -o wide
NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR
@@ -346,8 +584,8 @@ osportalapi 1/1 1 1 2m9s openslice-portalapi
osscapi 1/1 1 1 2m8s openslice-scapi openslice/org.etsi.osl.tmf.api:latest org.etsi.osl.service=osscapi
portalweb 1/1 1 1 2m7s openslice-portalweb openslice/org.etsi.osl.portal.web:latest org.etsi.osl.service=portalweb
tmfweb 1/1 1 1 2m8s openslice-tmfweb openslice/org.etsi.osl.tmf.web:latest org.etsi.osl.service=tmfweb
-
-
+```
+```bash
kubectl get services --namespace=openslice -o wide
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
@@ -364,178 +602,4 @@ osscapi ClusterIP 10.108.6.161 <none> 13082/TCP
portalweb ClusterIP 10.97.126.98 <none> 80/TCP 2m15s org.etsi.osl.service=portalweb
tmfweb ClusterIP 10.98.56.82 <none> 80/TCP 2m15s org.etsi.osl.service=tmfweb
-```
-
-<br>
-
-# Post installation steps
-
-<br>
-
-## Configure Keycloak server
-
-Keycloack server is managing authentication and running on a container at port 8080. It is proxied to your host via nginx under http://localhost/auth.
-
-* Go to http://domain.com/auth/ or https://domain.com/auth/ , (http://ipaddress:8080/auth/ or https://ipaddress:8443/auth/ are direct with no proxy)
-
-* Navigate to Administration Console
-
-
-> NOTE: if you are running in HTTP you will get a message: HTTPS required
-
-Go to https://ipaddress:8443/auth/
-
-Login with the credentials from section 2.2
-
-user admin and your KEYCLOAK_PASSWORD
-
-Select the master realm from top left corner, go to login Tab and select "Require SSL": None
-
-Do the same for realm Openslice
-
-> NOTE: If you are running in HTTPS, then leave Require SSL to external requests
-
-<br>
-
-### Configure redirects
-
-Go to realm Openslice, client, osapiWebClientId and change Root URL to your domain.
-
-Also, insert your domain, e.g. http://example.org/*, at:
-* Valid Redirect URIs
-* Web Origins
-
-<br>
-
-### Configure email in Keycloak
-
-Keycloak also allows new users to register.
-
-On Tab Login -> check User registration, Verify email, Forgot password etc.
-
-Also, enter the details on Realm -> Email -> Enable Authentication
-
-<br>
-
-### Add an Openslice admin user
-
-Go to manage/users and add an Openslice admin user, e.g. username=admin. Set a password and go also to Role Mappings and add to Assigned Roles ADMIN and MENTOR.
-
-> Note: That user is different from the Keycloak admin user. It is used to login and browse the OpenSlice Web UI. The Roles ADMIN and MENTOR guarantee full access through the Openslice UI, thus such a user is always required.
-
-<br>
-
-## Keycloak at localhost
-
-> **This is an important step if you run Keycloak on localhost**
-
-1 - Edit your hosts file, adding the line below
-
-```127.0.0.1 keycloak```
-
-2 - Replace http://localhost/auth/ with http://keycloak:8080/auth/ in your Keycloak config for TypeScript/Angular (see examples below).
-
-
-Hosts File Location:
-
- - In Linux/Unix, the file's location is at /etc/hosts
-
- - In Windows, its location is at c:\Windows\System32\Drivers\etc\hosts
-
-Explanation:
-
- Nginx uses the http://keycloak:8080 URL, which is accessible via the internal docker system's network.
- The Front-end (TS/Angular) shall also use the http://keycloak:8080.
- This way, you will not get the invalid token error, as the API is getting the token from http://keycloak:8080 (internally) and the Front-end is getting verified with the same URL, as well.
-
-
-
-Nginx serves the Front-end from the project org.etsi.osl.tmf.web.
-
-
-
-
-If you would like to use the Front-end to test your backend, then:
-
-1. config.prod.json (org.etsi.osl.tmf.web project) should look similar to the following example:
-
-```
-{
- "TITLE": "Openslice demo",
- "PORTALVERSION":"1.1.0-SNAPSHOT",
- "WIKI": "http://wiki.localhost",
- "BUGZILLA": "{BASEURL}/bugzilla/",
- "STATUS": "http://status.localhost/",
- "WEBURL": "{BASEURL}",
- "PORTAL_REPO_APIURL": "{BASEURL}/osapi",
- "ASSURANCE_SERVICE_MGMT_APIURL": "{BASEURL}/oas-api",
- "APITMFURL": "http://localhost:13082/tmf-api",
- "OAUTH_CONFIG" : {
- "issuer": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth",
- "loginUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth",
- "tokenEndpoint": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token",
- "redirectUri": "{BASEURL}/redirect",
- "logoutUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/logout",
- "postLogoutRedirectUri": "{BASEURL}/services/services_marketplace",
-
- "responseType": "code",
- "oidc": false,
- "clientId": "osapiWebClientId",
- "dummyClientSecret": "secret",
-
- "requireHttps": false,
- "useHttpBasicAuth": true,
- "clearHashAfterLogin": false,
-
- "showDebugInformation": true
- }
-}
-```
-> Note the difference in changing {BASEURL} -> http://keycloak:8080
-
-2. config.js (org.etsi.osl.portal.web) should look similar to the following example:
-
-```
-var appConfig = angular.module('portalwebapp.config',[]);
-
-
-appConfig.factory('APIEndPointService', function() {
- return {
- TITLE: "Openslice",
- WIKI: "ROOTURL",
- BUGZILLA: "ROOTURL/bugzilla/",
- STATUS: "ROOTURL/status/",
- APIURL: "http://localhost:13000",
- WEBURL: "ROOTURL/nfvportal",
- APIOAUTHURL: "http://keycloak:8080/auth/realms/openslice",
- APITMFURL: "http://localhost:13082/tmf-api/serviceCatalogManagement/v4"
-
- };
-});
-```
-> Note the difference in "APIOAUTHURL" property
-
-<br>
-
-## NFV Portal Landing page
-
-You may configure the landing page for the NFV Portal at
-
-```
-org.etsi.osl.portal.web/src/openslicehome/index.html
-```
-
-<br>
-
-## NFV Orchestrator Configuration
-
-See [NFV Orchestrator Configuration](./nfvoconfig.md).
-
-<br>
-
-## Important Note
-
-There is a case where the first time the services fail to start due to failed mysql connections. Please just issue again:
-
-`sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build`
-
+```
\ No newline at end of file
diff --git a/doc/index.md b/doc/index.md
index f74e48f3..e8c0cbc2 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -2,15 +2,15 @@
version: 2023Q4 - Release 0
-Openslice is a prototype open source, operations support system. It supports VNF/NSD onboarding to OpenSourceMANO (OSM) and NSD deployment management. It also supports TMFORUM OpenAPIs regarding Service Catalog Management, Ordering, Resource, etc.
+The ETSI Software Development Group for OpenSlice (SDG OSL) is developing an open source service based Operations Support System (OSS) to deliver Network Slice as a Service (NSaaS) following specifications from major SDOs including ETSI, TM Forum and GSMA. See more details [here](https://osl.etsi.org/about/).
## Usage
-Openslice allows Vertical Customers to browse the available offered service specifications and also allows NFV developers to onboard and manage VNF and Network Service artifacts.
-The following figure displays the usage of Openslice.
+OpenSlice allows Vertical Customers to browse the available offered service specifications and also allows NFV developers to onboard and manage VNF and Network Service artifacts. It also supports TMFORUM OpenAPIs regarding Service Catalog Management, Ordering, Resource, etc.
+The following figure displays the usage of OpenSlice.
-[](./images/index_intro_architecture.png)
+[](./images/index_intro_architecture.png)
There are two portals offering UI friendly access to users:
@@ -18,23 +18,23 @@ There are two portals offering UI friendly access to users:
* The Services portal allows users to access services and service providers to design services.
* The NFV portal allows users to self-manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator.
-3rd party applications can use Openslice through TMForum Open APIs.
+3rd party applications can use OpenSlice through TMForum Open APIs.
-Service Specifications reside into Service Catalogs, grouped in Categories. Openslice offers a Service Orchestrator called [OSOM](./architecture/osom.md). OSOM instantiates Service Specifications by requesting Network Services from target MANOs/NFVOs. NFV artifacts reside into a VNF/NSD catalog and are onboarded to a target MANO/NFV Orchestrator. Service Specifications reference NSD from the VNF/NSD catalog.
+Service Specifications reside into Service Catalogs, grouped in Categories. OpenSlice offers a Service Orchestrator called [OSOM](./architecture/osom.md). OSOM instantiates Service Specifications by requesting Network Services from target MANOs/NFVOs. NFV artifacts reside into a VNF/NSD catalog and are onboarded to a target MANO/NFV Orchestrator. Service Specifications reference NSD from the VNF/NSD catalog.
-Customers make Service Orders and Openslice instantiates the requested Service Specifications of the Service Order. Running Services instantiated by Openslice, reside in Openslice Service Inventory. The following picture displays how Service Specifications are related to Running Services and how Running Services relate with instantiated running Network Services. (See also [Service Inventory](./service_inventory.md))
+Customers make Service Orders and OpenSlice instantiates the requested Service Specifications of the Service Order. Running Services instantiated by OpenSlice, reside in OpenSlice Service Inventory. The following picture displays how Service Specifications are related to Running Services and how Running Services relate with instantiated running Network Services. (See also [Service Inventory](./service_inventory.md))
-[](./images/service_specification_instantiation.png)
+[](./images/service_specification_instantiation.png)
## Service Lifecycle Rules
-Openslice constains support for defining rules of services, affecting their behavior. See [LCM Rules](./lcm.md).
+OpenSlice constains support for defining rules of services, affecting their behavior. See [LCM Rules](./lcm.md).
## Multidomain scenarios and federation
-Openslice can be used to exchange service specifications/catalogs and make service orders between Organizations as the following figure displays.
+OpenSlice can be used to exchange service specifications/catalogs and make service orders between Organizations as the following figure displays.
-[](./images/multi-domain-organizations.png)
+[](./images/multi-domain-organizations.png)
An Identity federation is also possible since our authentication service is based on Keycloak (see [OAuth](./architecture/oauth.md)).
@@ -43,9 +43,9 @@ See more on [Consuming Services From External Partner Organizations](./architect
## Live Demo
-* Openslice demo: <http://portal.openslice.io/>
-* Openslice Service Catalogs and ordering: <http://portal.openslice.io/services/>
-* Openslice NFV Services onboarding: <http://portal.openslice.io/nfvportal>
+* OpenSlice demo: <http://portal.openslice.io/>
+* OpenSlice Service Catalogs and ordering: <http://portal.openslice.io/services/>
+* OpenSlice NFV Services onboarding: <http://portal.openslice.io/nfvportal>
> username=admin, password=openslice <br> or <br>username=admin, password=changeme
@@ -67,13 +67,16 @@ The complete environment consists of microservices deployed as docker containers
If you would like to operate all APIs, OSOM, the Mysql Server, nginx, etc then you need at least:
-- 4 cores
-- 8GB RAM
-- 20GB HD space
+| **Minimum Hardware Requirements** | **Recomended Hardware Requirements** |
+| --------------------------------- | ------------------------------------ |
+| 4 CPU cores | 8 CPU cores |
+| 8 GB RAM | 16 GB RAM |
+| 20 GB storage | 40 GB storage |
+
(NOTE: Bugzilla or ELK are not included and we assume they run elsewhere)
-However you can try with a minimum installation on a VM on a laptop with:
+However, you may try the front facing services of OpenSlice with a minimum installation on a VM on a laptop with:
- 2 cores
- 4GB of RAM
@@ -82,32 +85,36 @@ However you can try with a minimum installation on a VM on a laptop with:
## Supported APIs
-For a quick access check our swagger links:
+Quick overview of the supported APIs through our Swagger links:
-* TMF APIs: <http://portal.openslice.io/tmf-api/swagger-ui/index.html>
-* API for VNF/NSD management: <http://portal.openslice.io/osapi/swagger-ui/index.html>
+* [TMF APIs](http://portal.openslice.io/tmf-api/swagger-ui/index.html)
+* [API for VNF/NSD management](http://portal.openslice.io/osapi/swagger-ui/index.html)
## Source code
-Get source code here: <https://labs.etsi.org/rep/osl/code>
+OpenSlice source code is available at [OSL GitLab repository](https://labs.etsi.org/rep/osl/code).
## Contributing
-[Contributing](./contributing/developing.md)
+You may contribute following the guidelines at [Contributing page](./contributing/developing.md).
## Social Media
-* Twitter: <https://twitter.com/OpensliceOSS>
-* Slack: https://openslice.slack.com
+* [Twitter](https://twitter.com/OpensliceOSS)
+* [Slack](https://openslice.slack.com)
## History
-* The NFV portal part of Openslice was initially developed in H2020 European project 5GinFIRE (https://5ginfire.eu) by University of Patras, Greece
-* Openslice services, APIs and current version are actively maintained by University of Patras, Greece in H2020 European project 5G-VINNI (https://5g-vinni.eu/)
+* The NFV portal part of OpenSlice was initially developed in H2020 European Research project [5GinFIRE](https://5ginfire.eu) by University of Patras, Greece
+* OpenSlice core services, APIs was further developed and maintained in H2020 European project [5G-VINNI](https://5g-vinni.eu/) by University of Patras, Greece
+* OpenSlice has been a part off OSM's OSS/BSS ecosystem
[](https://osm.etsi.org/wikipub/index.php/OSS_BSS)
+## Ecosystem
+
+Discover the current OpenSlice ecosystem [here](https://osl.etsi.org/ecosystem/).
## Citation
--
GitLab