diff options
| -rw-r--r-- | docs/developerguide/developer-guide.rst | 15 | ||||
| -rw-r--r-- | docs/developerguide/media/build_logs.png | bin | 0 -> 126733 bytes | |||
| -rw-r--r-- | docs/developerguide/media/create_run_config_java.png | bin | 0 -> 83005 bytes | |||
| -rw-r--r-- | docs/developerguide/media/create_run_config_kt.png | bin | 0 -> 99443 bytes | |||
| -rw-r--r-- | docs/developerguide/media/expand_vm_options.PNG | bin | 0 -> 17547 bytes | |||
| -rw-r--r-- | docs/developerguide/media/import_project.png | bin | 0 -> 33478 bytes | |||
| -rw-r--r-- | docs/developerguide/media/reimport_maven.png | bin | 0 -> 138930 bytes | |||
| -rw-r--r-- | docs/developerguide/media/run_config_java.png | bin | 0 -> 73102 bytes | |||
| -rw-r--r-- | docs/developerguide/media/run_config_kt.png | bin | 0 -> 56159 bytes | |||
| -rw-r--r-- | docs/developerguide/media/run_debug.png | bin | 0 -> 4509 bytes | |||
| -rw-r--r-- | docs/developerguide/running-bp-processor-in-ide.rst | 365 | ||||
| -rw-r--r-- | docs/index.rst | 12 |
12 files changed, 390 insertions, 2 deletions
diff --git a/docs/developerguide/developer-guide.rst b/docs/developerguide/developer-guide.rst new file mode 100644 index 000000000..fd849f257 --- /dev/null +++ b/docs/developerguide/developer-guide.rst @@ -0,0 +1,15 @@ +.. This work is a derivative of https://wiki.onap.org/display/DW/Running+Blueprints+Processor+Microservice+in+an+IDE +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + +Developer Guide +================= + +Table of Contents +~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + running-bp-processor-in-ide
\ No newline at end of file diff --git a/docs/developerguide/media/build_logs.png b/docs/developerguide/media/build_logs.png Binary files differnew file mode 100644 index 000000000..558fd60a8 --- /dev/null +++ b/docs/developerguide/media/build_logs.png diff --git a/docs/developerguide/media/create_run_config_java.png b/docs/developerguide/media/create_run_config_java.png Binary files differnew file mode 100644 index 000000000..5d006e2ac --- /dev/null +++ b/docs/developerguide/media/create_run_config_java.png diff --git a/docs/developerguide/media/create_run_config_kt.png b/docs/developerguide/media/create_run_config_kt.png Binary files differnew file mode 100644 index 000000000..6f86a7e3a --- /dev/null +++ b/docs/developerguide/media/create_run_config_kt.png diff --git a/docs/developerguide/media/expand_vm_options.PNG b/docs/developerguide/media/expand_vm_options.PNG Binary files differnew file mode 100644 index 000000000..9cb98d3f9 --- /dev/null +++ b/docs/developerguide/media/expand_vm_options.PNG diff --git a/docs/developerguide/media/import_project.png b/docs/developerguide/media/import_project.png Binary files differnew file mode 100644 index 000000000..06b36c53d --- /dev/null +++ b/docs/developerguide/media/import_project.png diff --git a/docs/developerguide/media/reimport_maven.png b/docs/developerguide/media/reimport_maven.png Binary files differnew file mode 100644 index 000000000..bc49b3dc8 --- /dev/null +++ b/docs/developerguide/media/reimport_maven.png diff --git a/docs/developerguide/media/run_config_java.png b/docs/developerguide/media/run_config_java.png Binary files differnew file mode 100644 index 000000000..4da5d7f34 --- /dev/null +++ b/docs/developerguide/media/run_config_java.png diff --git a/docs/developerguide/media/run_config_kt.png b/docs/developerguide/media/run_config_kt.png Binary files differnew file mode 100644 index 000000000..4e88d2d0a --- /dev/null +++ b/docs/developerguide/media/run_config_kt.png diff --git a/docs/developerguide/media/run_debug.png b/docs/developerguide/media/run_debug.png Binary files differnew file mode 100644 index 000000000..3aa90577f --- /dev/null +++ b/docs/developerguide/media/run_debug.png diff --git a/docs/developerguide/running-bp-processor-in-ide.rst b/docs/developerguide/running-bp-processor-in-ide.rst new file mode 100644 index 000000000..05c825101 --- /dev/null +++ b/docs/developerguide/running-bp-processor-in-ide.rst @@ -0,0 +1,365 @@ +.. This work is a derivative of https://wiki.onap.org/display/DW/Running+Blueprints+Processor+Microservice+in+an+IDE +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2020 Deutsche Telekom AG. + +Running Blueprints Processor Microservice in an IDE +==================================================== + +Objective +~~~~~~~~~~~~ + +Have the processor running locally is to use the IDE to run the code, while having the database running in a container. +This way, code changes can be conveniently tested and debugged. + + +Check out the code +~~~~~~~~~~~~~~~~~~~ + +Check out the code from Gerrit: https://gerrit.onap.org/r/#/admin/projects/ccsdk/cds + +Build it locally +~~~~~~~~~~~~~~~~~~ + +In the checked out directory, type + +.. code-block:: bash + + mvn clean install -DskipTests=true -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -Dadditionalparam=-Xdoclint:none + +Spin up a Docker container with the database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Blueprints Processor project uses a database to store information about the blueprints +and therefore it needs to be online before attempting to run it. + +One way to create the database is by using the :file:`docker-compose.yaml` +file present on the distribution module. This database will require a local directory to mount a volume, before running docker-compose remember to create following directory: + +.. code-block:: bash + + mkdir -p -m 755 /opt/app/cds/mysql/data + +Navigate to the docker-compose file in the distribution module: + +.. tabs:: + + .. group-tab:: Latest + + .. code-block:: bash + + cd ms/blueprintsprocessor/application/src/main/dc + + .. group-tab:: Frankfurt + + .. code-block:: bash + + cd ms/blueprintsprocessor/application/src/main/dc + + .. group-tab:: El Alto + + .. code-block:: bash + + ms/blueprintsprocessor/distribution/src/main/dc + + .. group-tab:: Dublin + + .. code-block:: bash + + ms/blueprintsprocessor/distribution/src/main/dc + +And run docker-composer: + +.. code-block:: bash + + docker-compose up -d db + +This should spin up a container of the MariaDB image in the background. +To check if it has worked, this command can be used: + +.. code-block:: bash + + docker-compose logs -f + +The phrase ``mysqld: ready for connections`` indicates that the database was started correctly. + +From now on, the Docker container will be available on the computer; if it ever gets stopped, +it can be started again by the command: + +.. code-block:: bash + + docker start <id of mariadb container> + + +Set permissions on the local file system +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Blueprints processor uses the local file system for some operations and, therefore, +need some existing and accessible paths to run properly. + +Execute the following commands to create the needed directories, and grant access to the current user to modify them: + +.. code-block:: bash + + mkdir -p -m 755 /opt/app/onap/blueprints/archive + mkdir -p -m 755 /opt/app/onap/blueprints/deploy + mkdir -p -m 755 /opt/app/onap/scripts + sudo chown -R $(id -u):$(id -g) /opt/app/onap/ + +Import the project on the IDE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For this page, the chosen IDE is IntelliJ, but the instructions present here can +be adapted to be used in other IDEs as well. + +Go to *File | Open* and choose the :file:`pom.xml` file of the cds directory: + +|imageImportProject| + +Sometimes it may be necessary to reimport Maven project: + +|imageReimportMaven| + + +Override some application properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After the project is compiled, a Run Configuration profile overriding some application properties +with custom values needs to be created, to reflect the local environment characteristics. + +.. tabs:: + + .. group-tab:: Latest + + Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: + + ``ms/blueprintsprocessor/application/src/main/kotlin/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.kt``. + + Right-click inside it, at any point, to load the context menu and select create + BlueprintProcessorApplication configuration from context: + + |imageCreateRunConfigkt| + + **The following window will open:** + + |imageRunConfigKt| + + **Add the following in the field `VM Options`:** + + .. code-block:: bash + :caption: **Custom values for properties** + + -Dspring.profiles.active=dev + + You can override any value from **application-dev.properties** file here. Use the following pattern: + + .. code-block:: java + + -D<application-dev.properties key>=<application-dev.properties value> + + .. group-tab:: Frankfurt + + Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: + + ``ms/blueprintsprocessor/application/src/main/kotlin/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.kt``. + + Right-click inside it, at any point, to load the context menu and select create + BlueprintProcessorApplication configuration from context: + + |imageCreateRunConfigkt| + + **The following window will open:** + + |imageRunConfigKt| + + **Add the following in the field `VM Options`:** + + .. code-block:: bash + :caption: **Custom values for properties** + + -Dspring.profiles.active=dev + + You can override any value from **application-dev.properties** file here. Use the following pattern: + + .. code-block:: java + + -D<application-dev.properties key>=<application-dev.properties value> + + .. group-tab:: El Alto + + Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: + + ``ms/blueprintsprocessor/application/src/main/java/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.java.`` + + Right-click inside it, at any point, to load the context menu and select create + BlueprintProcessorApplication configuration from context: + + |imageCreateRunConfigJava| + + **The following window will open:** + + |imageRunConfigJava| + + **Add the following in the field `VM Options`:** + + .. code-block:: bash + :caption: **Custom values for properties** + + -Dspring.profiles.active=dev + + You can override any value from **application-dev.properties** file here. Use the following pattern: + + .. code-block:: java + + -D<application-dev.properties key>=<application-dev.properties value> + + .. group-tab:: Dublin + + Navigate to the main class of the Blueprints Processor, the BlueprintProcessorApplication class: + + ``ms/blueprintsprocessor/application/src/main/java/org/onap/ccsdk/cds/blueprintsprocessor/BlueprintProcessorApplication.java``. + + Right-click inside it, at any point, to load the context menu and select create + BlueprintProcessorApplication configuration from context: + + |imageCreateRunConfigJava| + + **The following window will open:** + + |imageRunConfigJava| + + **Add the following in that field:** + + .. code-block:: java + :caption: **Custom values for properties** + + -DappName=ControllerBluePrints + -Dms_name=org.onap.ccsdk.apps.controllerblueprints + -DappVersion=1.0.0 + -Dspring.config.location=opt/app/onap/config/ + -Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/sdnctl + -Dspring.datasource.username=sdnctl + -Dspring.datasource.password=sdnctl + -Dcontrollerblueprints.loadInitialData=true + -Dblueprintsprocessor.restclient.sdncodl.url=http://localhost:8282/ + -Dblueprintsprocessor.db.primary.url=jdbc:mysql://localhost:3306/sdnctl + -Dblueprintsprocessor.db.primary.username=sdnctl + -Dblueprintsprocessor.db.primary.password=sdnctl + -Dblueprintsprocessor.db.primary.driverClassName=org.mariadb.jdbc.Driver + -Dblueprintsprocessor.db.primary.hibernateHbm2ddlAuto=update + -Dblueprintsprocessor.db.primary.hibernateDDLAuto=none + -Dblueprintsprocessor.db.primary.hibernateNamingStrategy=org.hibernate.cfg.ImprovedNamingStrategy + -Dblueprintsprocessor.db.primary.hibernateDialect=org.hibernate.dialect.MySQL5InnoDBDialect + -Dblueprints.processor.functions.python.executor.executionPath=./components/scripts/python/ccsdk_blueprints + -Dblueprints.processor.functions.python.executor.modulePaths=./components/scripts/python/ccsdk_blueprints,./components/scripts/python/ccsdk_netconf,./components/scripts/python/ccsdk_restconf + -Dblueprintsprocessor.restconfEnabled=true + -Dblueprintsprocessor.restclient.sdncodl.type=basic-auth + -Dblueprintsprocessor.restclient.sdncodl.url=http://localhost:8282/ + -Dblueprintsprocessor.restclient.sdncodl.username=admin + -Dblueprintsprocessor.restclient.sdncodl.password=Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U + -Dblueprintsprocessor.grpcEnable=false + -Dblueprintsprocessor.grpcPort=9111 + -Dblueprintsprocessor.blueprintDeployPath=/opt/app/onap/blueprints/deploy + -Dblueprintsprocessor.blueprintArchivePath=/opt/app/onap/blueprints/archive + -Dblueprintsprocessor.blueprintWorkingPath=/opt/app/onap/blueprints/work + -Dsecurity.user.password={bcrypt}$2a$10$duaUzVUVW0YPQCSIbGEkQOXwafZGwQ/b32/Ys4R1iwSSawFgz7QNu + -Dsecurity.user.name=ccsdkapps + -Dblueprintsprocessor.messageclient.self-service-api.kafkaEnable=false + -Dblueprintsprocessor.messageclient.self-service-api.topic=producer.t + -Dblueprintsprocessor.messageclient.self-service-api.type=kafka-basic-auth + -Dblueprintsprocessor.messageclient.self-service-api.bootstrapServers=127.0.0.1:9092 + -Dblueprintsprocessor.messageclient.self-service-api.consumerTopic=receiver.t + -Dblueprintsprocessor.messageclient.self-service-api.groupId=receiver-id + -Dblueprintsprocessor.messageclient.self-service-api.clientId=default-client-id + -Dspring.profiles.active=dev + -Dblueprintsprocessor.httpPort=8080 + -Dserver.port=55555 + + +Add/replace the following in Blueprint's application-dev.properties file: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: java + + blueprintsprocessor.grpcclient.remote-python.type=token-auth + blueprintsprocessor.grpcclient.remote-python.host=localhost + blueprintsprocessor.grpcclient.remote-python.port=50051 + blueprintsprocessor.grpcclient.remote-python.token=Basic Y2NzZGthcHBzOmNjc2RrYXBwcw== + + blueprintprocessor.remoteScriptCommand.enabled=true + + +Run the application +~~~~~~~~~~~~~~~~~~~ + +Select either run or debug for this Run Configuration to start the Blueprints Processor: + +|imageRunDebug| + +|imageBuildLogs| + + +Testing the application +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two main features of the Blueprints Processor that can be of interest of a developer: +blueprint upload and blueprint process. + +To upload custom blueprints, the endpoint ``api/v1/execution-service/upload`` is used. + +To process, the endpoint is ``api/v1/execution-service/process``. + +Postman is a software that can be used to send these request, and an example of +them is present on https://www.getpostman.com/collections/b99863b0cde7565a32fc. + + +Possible Fixes +~~~~~~~~~~~~~~~~~~~ + +Imported packages or annotiations are not found, Run Config not available? +***************************************************************************** + +1. Rebuild with ``maven install ...`` (see above) +2. Potentially change Maven home directory in Settings +3. Maven reimport in IDE + +Compilation error? +******************** + +* Change Java Version to 11 or 8 + +.. |imageRunConfigJava| image:: media/run_config_java.png + :scale: 100 % + :align: middle + +.. |imageRunConfigKt| image:: media/run_config_kt.png + :scale: 100 % + :align: middle + +.. |imageCreateRunConfigJava| image:: media/create_run_config_java.png + :scale: 100 % + :align: middle + +.. |imageCreateRunConfigKt| image:: media/create_run_config_kt.png + :scale: 100 % + :align: middle + +.. |imageImportProject| image:: media/import_project.png + :scale: 100 % + :align: middle + +.. |imageReimportMaven| image:: media/reimport_maven.png + :scale: 70 % + :align: middle + +.. |imageRunDebug| image:: media/run_debug.png + :scale: 100 % + :align: middle + +.. |imageRunDebug| image:: media/run_debug.png + :align: middle + :scale: 100 % + +.. |imageBuildLogs| image:: media/build_logs.png + :align: middle + :scale: 100 %
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index bf6bba508..2b4593d64 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -118,7 +118,15 @@ https://github.com/onap/ccsdk-apps/blob/master/components/scripts/python/ccsdk_n .. |cdsArchitectureImage| image:: media/CDS_architecture_latest.png :scale: 30 % - + +Developer Guide +---------- + +.. toctree:: + :maxdepth: 1 + + developerguide/developer-guide + User Guide ---------- @@ -135,7 +143,7 @@ CDS Desginer UI :maxdepth: 1 CDS_Designer_Guide - + Controller Design Studio Presentation ------------------------------------- |
