diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 6c38ff23becc9f0e64f16968834f8f8866f8aedb..20f28f1d47a7888b6d5bd43ca4fed20b2f6aa8a1 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,11 +1,31 @@ pages: stage: deploy - image: python:latest + image: python:3.9.18-slim-bullseye + variables: + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" + PAGES_BRANCH: gl-pages + HTTPS_REMOTE: https://gitlab-ci-token:${ACCESS_TOKEN}@${CI_SERVER_HOST}/rep/${CI_PROJECT_PATH}.git + before_script: + - pip install -q mkdocs-material mike + - apt-get update -qq && apt-get -qq install -y git > /dev/null + - git config --global --replace-all user.name $GITLAB_USER_NAME + - git config --global --replace-all user.email $GITLAB_USER_EMAIL + - git fetch origin $PAGES_BRANCH && git checkout $PAGES_BRANCH || git checkout -b $PAGES_BRANCH origin/$PAGES_BRANCH || echo "Pages branch not deployed yet." + - git checkout $CI_COMMIT_SHA script: - - pip install mkdocs-material - - mkdocs build --site-dir public + - | + if [ -n "$CI_COMMIT_TAG" ]; then + mike deploy --deploy-prefix public -r $HTTPS_REMOTE -p -b $PAGES_BRANCH -u $CI_COMMIT_TAG latest + mike set-default --deploy-prefix public -r $HTTPS_REMOTE -p -b $PAGES_BRANCH latest + elif [ "$CI_COMMIT_REF_NAME" == "develop" ]; then + mike deploy --deploy-prefix public -r $HTTPS_REMOTE -p -b $PAGES_BRANCH -u $CI_COMMIT_BRANCH + fi + - git checkout $PAGES_BRANCH -- public/ artifacts: paths: - - public + - public/ rules: - - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' + - if: '$CI_COMMIT_TAG' + - if: '$CI_COMMIT_REF_NAME == "develop"' + when: always + - when: never \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000000000000000000000000000000000..396a29e6c5ab9b00e609c11f2f98149a296d63f3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,331 @@ +OSL documentation (c) by ETSI + +OSL documentation is licensed under a +Creative Commons Attribution 4.0 International License. + +You can fine the license below and at . + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + + diff --git a/README.md b/README.md deleted file mode 100644 index 2992ddefa3b34c7befccc23644987d2ddc6b7f52..0000000000000000000000000000000000000000 --- a/README.md +++ /dev/null @@ -1,92 +0,0 @@ -# documentation - - - -## Getting started - -To make it easy for you to get started with GitLab, here's a list of recommended next steps. - -Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)! - -## Add your files - -- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files -- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command: - -``` -cd existing_repo -git remote add origin https://labs.etsi.org/rep/osl/documentation.git -git branch -M main -git push -uf origin main -``` - -## Integrate with your tools - -- [ ] [Set up project integrations](https://labs.etsi.org/rep/osl/documentation/-/settings/integrations) - -## Collaborate with your team - -- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/) -- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) -- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically) -- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/) -- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html) - -## Test and Deploy - -Use the built-in continuous integration in GitLab. - -- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html) -- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/) -- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html) -- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/) -- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html) - -*** - -# Editing this README - -When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template. - -## Suggestions for a good README -Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information. - -## Name -Choose a self-explaining name for your project. - -## Description -Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors. - -## Badges -On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge. - -## Visuals -Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method. - -## Installation -Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection. - -## Usage -Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README. - -## Support -Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc. - -## Roadmap -If you have ideas for releases in the future, it is a good idea to list them in the README. - -## Contributing -State if you are open to contributions and what your requirements are for accepting them. - -For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self. - -You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser. - -## Authors and acknowledgment -Show your appreciation to those who have contributed to the project. - -## License -For open source projects, say how it is licensed. - -## Project status -If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers. diff --git a/doc/contributing/developing.md b/doc/contributing/developing.md index 7e4523eaaac1cd20ce5a6970d74f2d9dd3b823da..e8939eeca651aadf2bedef512ed8009df305b4aa 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] ``` -wget https://raw.githubusercontent.com/openslice/org.etsi.osl.main/develop/compose/deploy.sh -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 section) -> 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 of 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 ff6417cb10efaf90549ce9fd2beca076f5425ecc..48aa4950f66ab2832035d882083496724d291e2e 100644 --- a/doc/deployment.md +++ b/doc/deployment.md @@ -1,274 +1,526 @@ -# Preparing the environment +## Requirements -Note: See the Kubernetes section, if you would like to deploy Openslice in a Kubernetes cluster +### Hardware requirements: -
-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 +> Since July 2023 Docker Compose V1 stopped receiving updates. OpenSlice fully reverted to Compose V2, which is integrated in the Docker installation. -_NOTE:_ 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://raw.githubusercontent.com/openslice/org.etsi.osl.main/master/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 +```bash +sudo systemctl restart docker ``` -sudo ./deploy.sh develop [or replace develop with other branch name] -``` -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 -
+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: -
+* 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/)) + +```bash +sudo ./deploy.sh main #[or replace main with other branch name] +``` -## 1. mysql-portal container +> **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.** -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). -delete the exposed ports +## Configure docker-compose services -## 2.keycloak container +### 1. Create configuration specific Docker Compose file from the template + +```bash +cd org.etsi.osl.main/compose/ +``` +```bash +sudo cp docker-compose.yaml.configure docker-compose.yaml +``` +### 2. Configure mysql-portal container *(optional)* + +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. Configure keycloak container *(optional)* + +1. If you made changes to keycloak's mysql credentials: + + In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`. -2.1 Edit the following if you changed mysql credentials ``` DB_DATABASE: keycloak DB_USER: keycloak DB_PASSWORD: password ``` -2.2 Change the keycloak admin password -``` +2. If you want to change the keycloak admin password: + + In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` + +``` KEYCLOAK_PASSWORD: Pa55w0rd ``` +### 4. Configure bugzilla container *(optional)* -## 3.osportalapi container (NFV services) - -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) +If you want to utilise the Bugzilla connector: +In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` + ``` 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" - - + "spring.activemq.brokerUrl": "tcp://anartemis:61616?jms.watchTopicAdvisories=false", + "spring.activemq.user": "artemis", + "spring.activemq.password": "artemis", + "bugzillaurl":"", + "bugzillakey":"", + "main_operations_product":"" +}' ``` - -## 4.bugzilla container - -If you would like to use the Bugzilla connector +And add the provided Bugzilla installation information: ``` "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: -- 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 +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, please create a version named 'unspecified' +Also in the 'Main Site Operations' product, a version named 'unspecified' must be created. +### 5. Configure osportalapi container (NFV services) *(conditional)* -## 5.osscapi container (TMF-API service) +Change the respective fields: -Edit the following if you changed mysql and keycloak credentials +- If you made changes to mysql and keycloak credentials. +- If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR). -``` -"spring.datasource.username":"xx", -"spring.datasource.password":"xx", -"keycloak-admin-password": "Pa55w0rd", -Edit properly with your domain "swagger.authserver" : "http://localhost/auth/realms/openslice", +> ***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.*** +In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.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" +}' ``` -Delete the exposed ports in other services like activemq +### 6. osscapi container (TMF API service) *(conditional)* -
+Change the respective fields: -# Configure nginx +- 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` ``` -cd nginx -sudo cp nginx.conf.default nginx.conf +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" +}' ``` -Edit server_name +## Configure nginx -
+In folder `org.etsi.osl.main/compose/nginx` create a configuration specific `nginx.conf` file. -# Configure Web UI +```bash +cd org.etsi.osl.main/compose/nginx/ ``` -cd org.etsi.osl.portal.web/src/js/ -cp config.js.default config.js + +```bash +sudo cp nginx.conf.default nginx.conf ``` -Edit config.js with your domain +If needed, in the nginx.conf file, edit the server_name for an non-local deployment. + + +## 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 ``` -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" +```bash +sudo cp config.js.default config.js ``` -
+Edit the `config.js` file with the information of your domain -# Configure TMF Web UI -There are 3 files available for configuration: +``` +{ + 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" +} +``` + +## Configure TMF Web UI + +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. -
+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 +``` +```bash +sudo cp config.theming.default.json config.theming.json +``` +E.g. Edit "TITLE" or "WIKI" property with your domain title ``` -cd org.etsi.osl.tmf.web/src/assets/config +{ + TITLE: "OpenSlice by ETSI", + WIKI: "https://osl.etsi.org/documentation/latest/deployment/", +} ``` -and edit config.prod.json -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 mandatory to also apply these changes to the `org.etsi.osl.tmf.web/src/assets/config` for persistancy, 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. -
+## 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 ``` -
+> 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 mandatory to also apply these changes to the **org.etsi.osl.tmf.web/src/assets/config** for persistancy, 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. -
+## 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. + +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. + +### Configure Keycloak server + +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) + +- Navigate to Administration Console + +- Login with the credentials from section [Configure keycloak container](#3-configure-keycloak-container-optional). Default values are: + - user: admin and + - password: KEYCLOAK_PASSWORD + +> if you are running in HTTP you will get a message: HTTPS required. + +To resolve this issue when running in HTTP: + +- 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. -# Deploying docker compose +2.1 - 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 +``` -Go to compose directory and issue: +```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 + } +} ``` -sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build + +> 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 + +2.2 - 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: -Note: Depending on your machine, this process might take time. +``` +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 -# Validating deployments and container monitoring -You can monitor containers status with portainer at port 9000 (http://your-ip:9000) +### NFV Orchestrator Configuration -Initially, you may monitor the local machine at portainer. +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.
-# Kubernetes installation +## Kubernetes installation +Openslice can be installed in a Kubernetes cluster. -Openslice can be installed in a Kubernetes cluster. (This is a work in progress) +**This is a work in progress, and should be used for stable deployments!**. + +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 +528,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 +556,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 +582,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 portalweb-8469d57df4-94tfj 1/1 Running 0 101s 192.168.48.44 kc-nfs tmfweb-868f7bb9c5-x4lfh 1/1 Running 0 102s 192.168.48.43 kc-nfs - - +``` +```bash kubectl get deployments --namespace=openslice -o wide NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR @@ -346,8 +598,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 +616,4 @@ osscapi ClusterIP 10.108.6.161 13082/TCP portalweb ClusterIP 10.97.126.98 80/TCP 2m15s org.etsi.osl.service=portalweb tmfweb ClusterIP 10.98.56.82 80/TCP 2m15s org.etsi.osl.service=tmfweb -``` - -
- -# Post installation steps - -
- -## 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 - -
- -### 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 - -
- -### 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 - -
- -### 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. - -
- -## 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 - -
- -## NFV Portal Landing page - -You may configure the landing page for the NFV Portal at - -``` -org.etsi.osl.portal.web/src/openslicehome/index.html -``` - -
- -## NFV Orchestrator Configuration - -See [NFV Orchestrator Configuration](./nfvoconfig.md). - -
- -## 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/images/favicon.png b/doc/images/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..3c71ab91aa15c554b3d9a228207938182cdefa00 Binary files /dev/null and b/doc/images/favicon.png differ diff --git a/doc/images/logo_osl.png b/doc/images/logo_osl.png new file mode 100644 index 0000000000000000000000000000000000000000..e6eb89a7da94edc6ea26dcb1972d9e101b0dffee Binary files /dev/null and b/doc/images/logo_osl.png differ diff --git a/doc/images/logo_osl_square.png b/doc/images/logo_osl_square.png new file mode 100644 index 0000000000000000000000000000000000000000..37cbc4ba60771e54c3ea2f18fa89a7e3af387360 Binary files /dev/null and b/doc/images/logo_osl_square.png differ diff --git a/doc/images/logo_osl_square_non_transp.png b/doc/images/logo_osl_square_non_transp.png new file mode 100644 index 0000000000000000000000000000000000000000..a7f8684e95a987b15dacb02675bd3ac9ec7ed091 Binary files /dev/null and b/doc/images/logo_osl_square_non_transp.png differ diff --git a/doc/images/openslice_logo.png b/doc/images/openslice_logo.png index 61a38a515223bb67a78da6694c34dbe08c89e942..2fa5efc135209ce66cee07ea7a76dc0a4cff9244 100644 Binary files a/doc/images/openslice_logo.png and b/doc/images/openslice_logo.png differ diff --git a/doc/images/openslice_logo_old.png b/doc/images/openslice_logo_old.png new file mode 100644 index 0000000000000000000000000000000000000000..61a38a515223bb67a78da6694c34dbe08c89e942 Binary files /dev/null and b/doc/images/openslice_logo_old.png differ diff --git a/doc/index.md b/doc/index.md index 3b68017c472df31e7a9f72b7894d5dd1c2af6349..e8c0cbc224a790cb4d22acc2ef3d2a0fdf3b1de3 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,16 +1,16 @@ drawing -version: 2023-Q3 1.2.0-SNAPSHOT +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. -[![Openslice usage](./images/index_intro_architecture.png)](./images/index_intro_architecture.png) +[![OpenSlice usage](./images/index_intro_architecture.png)](./images/index_intro_architecture.png) There are two portals offering UI friendly access to users: @@ -18,34 +18,34 @@ 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)) -[![Openslice Service Specification instantiation](./images/service_specification_instantiation.png)](./images/service_specification_instantiation.png) +[![OpenSlice Service Specification instantiation](./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. -[![Openslice Service Specification instantiation](./images/multi-domain-organizations.png)](./images/multi-domain-organizations.png) +[![OpenSlice Service Specification instantiation](./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) ) +An Identity federation is also possible since our authentication service is based on Keycloak (see [OAuth](./architecture/oauth.md)). -See more on [Consuming Services From External Partner Organizations](./architecture/consumingServicesFromExternalPartners.md) +See more on [Consuming Services From External Partner Organizations](./architecture/consumingServicesFromExternalPartners.md). ## Live Demo -* Openslice demo: -* Openslice Service Catalogs and ordering: -* Openslice NFV Services onboarding: +* OpenSlice demo: +* OpenSlice Service Catalogs and ordering: +* OpenSlice NFV Services onboarding: > username=admin, password=openslice
or
username=admin, password=changeme @@ -57,23 +57,26 @@ See more on [Consuming Services From External Partner Organizations](./architect ## Installing -See [Deployment/Installation](./deployment.md) +See [Deployment/Installation](./deployment.md). --- ## Hardware requirements -The complete environment consists of microservices deployed as docker containers. Portainer is also installed to monitor them at port 9000 +The complete environment consists of microservices deployed as docker containers. Portainer is also installed to monitor them at port 9000. 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: -* API for VNF/NSD management: +* [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: +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: -* 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 [![Part of OSM Ecosystem](./images/osm_ecosystem_ossbss.png)](https://osm.etsi.org/wikipub/index.php/OSS_BSS) +## Ecosystem + +Discover the current OpenSlice ecosystem [here](https://osl.etsi.org/ecosystem/). ## Citation diff --git a/mkdocs.yml b/mkdocs.yml index c0a559547b9b26d5c0c0dd15b938f8ba6e5669b6..2236d6a58e132d88d413d4b156c44b7b3ce958bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,12 @@ # Project information -site_name: Openslice -site_description: Openslice - Open source OSS -site_author: Openslice.io -site_url: http://openslice.io +site_name: ETSI SDG OSL Documentation +site_description: ETSI SDG OSL Documentation page +site_author: OpenSlice by ETSI +site_url: https://osl.etsi.org/ # Repository -repo_name: openslice -repo_url: https://github.com/openslice +repo_name: OSL GitLab +repo_url: https://labs.etsi.org/rep/osl edit_uri: "" docs_dir: doc @@ -17,36 +17,55 @@ docs_dir: doc # remote_branch: gh-pages # Theme and overrides, i.e. language partial +# https://squidfunk.github.io/mkdocs-material/creating-your-site/ theme: - name: mkdocs + name: material # Don't include MkDocs' JavaScript - include_search_page: false - search_index_only: true + #include_search_page: false + #search_index_only: true # Default values, taken from mkdocs_theme.yml language: en - feature: - tabs: true +# feature: +# tabs: true + features: + - navigation.instant + - navigation.instant.progress + - navigation.top + - navigation.footer + - navigation.path + - search + - search.highlight + palette: - primary: 'teal' - accent: 'light blue' - logo: 'images/openslice_logo.png' + primary: 'cyan' + accent: 'blue' + + logo: 'images/logo_osl.png' + favicon: images/favicon.png + + icon: + repo: fontawesome/brands/gitlab # Copyright -copyright: "Copyright © 2019-2023 Openslice Project" +copyright: "Copyright © 2019-2024 Openslice Project" # Options extra: - search: - languages: "en" +# search: +# languages: "en" social: - - type: globe - link: http://openslice.io - - type: github-alt - link: https://github.com/openslice - - type: twitter + - icon: fontawesome/solid/globe + link: https://osl.etsi.org/ + - icon: fontawesome/brands/gitlab + link: https://labs.etsi.org/rep/osl + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/company/openslice/ + - icon: fontawesome/brands/x-twitter link: https://twitter.com/OpensliceOSS + version: + provider: mike # Page tree nav: