diff --git a/.gitignore b/.gitignore index b25c15b..eaf5daf 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ *~ +.* +*.pyc diff --git a/README.md b/README.md index 399b153..b2ebdd1 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,7 @@ [![](https://img.shields.io/badge/FIWARE-Data_Monetization-51b6a3.svg?label=FIWARE&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABsAAAAVCAYAAAC33pUlAAAABHNCSVQICAgIfAhkiAAAA8NJREFUSEuVlUtIFlEUx+eO+j3Uz8wSLLJ3pBiBUljRu1WLCAKXbXpQEUFERSQF0aKVFAUVrSJalNXGgmphFEhQiZEIPQwKLbEUK7VvZrRvbr8zzjfNl4/swplz7rn/8z/33HtmRhn/MWzbXmloHVeG0a+VSmAXorXS+oehVD9+0zDN9mgk8n0sWtYnHo5tT9daH4BsM+THQC8naK02jCZ83/HlKaVSzBey1sm8BP9nnUpdjOfl/Qyzj5ust6cnO5FItJLoJqB6yJ4QuNcjVOohegpihshS4F6S7DTVVlNtFFxzNBa7kcaEwUGcbVnH8xOJD67WG9n1NILuKtOsQG9FngOc+lciic1iQ8uQGhJ1kVAKKXUs60RoQ5km93IfaREvuoFj7PZsy9rGXE9G/NhBsDOJ63Acp1J82eFU7OIVO1OxWGwpSU5hb0GqfMydMHYSdiMVnncNY5Vy3VbwRUEydvEaRxmAOSSqJMlJISTxS9YWTYLcg3B253xsPkc5lXk3XLlwrPLuDPKDqDIutzYaj3eweMkPeCCahO3+fEIF8SfLtg/5oI3Mh0ylKM4YRBaYzuBgPuRnBYD3mmhA1X5Aka8NKl4nNz7BaKTzSgsLCzWbvyo4eK9r15WwLKRAmmCXXDoA1kaG2F4jWFbgkxUnlcrB/xj5iHxFPiBN4JekY4nZ6ccOiQ87hgwhe+TOdogT1nfpgEDTvYAucIwHxBfNyhpGrR+F8x00WD33VCNTOr/Wd+9C51Ben7S0ZJUq3qZJ2OkZz+cL87ZfWuePlwRcHZjeUMxFwTrJZAJfSvyWZc1VgORTY8rBcubetdiOk+CO+jPOcCRTF+oZ0okUIyuQeSNL/lPrulg8flhmJHmE2gBpE9xrJNkwpN4rQIIyujGoELCQz8ggG38iGzjKkXufJ2Klun1iu65bnJub2yut3xbEK3UvsDEInCmvA6YjMeE1bCn8F9JBe1eAnS2JksmkIlEDfi8R46kkEkMWdqOv+AvS9rcp2bvk8OAESvgox7h4aWNMLd32jSMLvuwDAwORSE7Oe3ZRKrFwvYGrPOBJ2nZ20Op/mqKNzgraOTPt6Bnx5citUINIczX/jUw3xGL2+ia8KAvsvp0ePoL5hXkXO5YvQYSFAiqcJX8E/gyX8QUvv8eh9XUq3h7mE9tLJoNKqnhHXmCO+dtJ4ybSkH1jc9XRaHTMz1tATBe2UEkeAdKu/zWIkUbZxD+veLxEQhhUFmbnvOezsJrk+zmqMo6vIL2OXzPvQ8v7dgtpoQnkF/LP8Ruu9zXdJHg4igAAAABJRU5ErkJgggA=)](https://www.fiware.org/developers/catalogue/) [![License badge](https://img.shields.io/github/license/FIWARE-TMForum/Business-API-Ecosystem.svg)](https://opensource.org/licenses/AGPL-3.0) [![Documentation badge](https://img.shields.io/readthedocs/business-api-ecosystem.svg)](https://business-api-ecosystem.rtfd.io) -[![Docker](https://img.shields.io/docker/pulls/fiware/business-api-ecosystem.svg)](https://hub.docker.com/r/fiware/business-api-ecosystem) -[![](https://img.shields.io/badge/tag-fiware-orange.svg?logo=stackoverflow)](http://stackoverflow.com/questions/tagged/fiware) -[![Support](https://img.shields.io/badge/support-askbot-yellowgreen.svg)](https://ask.fiware.org) +[![Docker](https://img.shields.io/docker/pulls/fiware/business-api-ecosystem.svg)](https://hub.docker.com/r/fiware/business-api-ecosystem) [![](https://img.shields.io/badge/tag-fiware-orange.svg?logo=stackoverflow)](http://stackoverflow.com/questions/tagged/fiware) [![Support](https://img.shields.io/badge/support-askbot-yellowgreen.svg)](https://ask.fiware.org) * [Introduction](#introduction) * [GEi Overall Description](#gei-overall-description) diff --git a/apiary.apib b/apiary.apib index 0a998ff..ebd4164 100644 --- a/apiary.apib +++ b/apiary.apib @@ -2,10 +2,10 @@ FORMAT: 1A HOST: https://store.lab.fiware.org/ TITLE: FIWARE Business API Ecosystem Open API Specification DATE: 23 January 2017 -VERSION: v6.4.0 -PREVIOUS_VERSION: v5.4.1 +VERSION: v7.4.0 +PREVIOUS_VERSION: vpdate APIARY_PROJECT: fiwaretmfbizecosystem -SPEC_URL: https://fiware-tmforum.github.io/Business-API-Ecosystem/ +SPEC_URL: https://fiwareckanextensions.docs.apiary.io/# GITHUB_SOURCE: https://github.com/FIWARE-TMForum # FIWARE TMF Business API Ecosystem @@ -25,16 +25,16 @@ inventory management, usage management, billing, customer, and party APIs. ## Status This is a work in progress and is changing on a daily basis. You can check the latest -available version on [GitHub](https://github.com/FIWARE-TMForum). +available version on [GitHub](https://github.com/FIWARE-TMForum/Business-API-Ecosystem). -Please send your comments to . +The current specification includes the latest API specification. For the API specification +of particular releases, please refer to [GitHub Pages](https://fiware-tmforum.github.io/Business-API-Ecosystem/) This specification is licensed under the [FIWARE Open Specification License](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specification_Legal_Notice_%28implicit_patents_license%29) ## Acknowledgements -The editors would like to express their gratitude to the following people who actively contributed to this specification: -Pierre Gauthier, Aitor Magán, and Álvaro Arranz García +The editors would like to express their gratitude to Aitor Magán and Álvaro Arranz who actively contributed to this specification. ## Copyright @@ -44,8 +44,7 @@ Pierre Gauthier, Aitor Magán, and Álvaro Arranz García ## License This specification is licensed under the -[FIWARE Open Specification License (implicit patent license)] -(https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/Implicit_Patents_License). +[FIWARE Open Specification License (implicit patent license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/Implicit_Patents_License). ## Specification @@ -108,12 +107,12 @@ API for retrieving information about the running instance. It manages the follow + Response 200 (application/json) { - "version": "v6.4.0", - "release_date": "2017-12-20", + "version": "v7.4.0", + "release_date": "2018-10-12", "uptime": "2 d, 3 h, 15 m, 50 s", "git_hash": "808f4bf995bddf0f6a05576956987f2568522062", "doc": "http://business-api-ecosystem.readthedocs.io/", - "user_doc": "http://business-api-ecosystem.readthedocs.io/en/v6.4.0/user-guide.html" + "user_doc": "http://business-api-ecosystem.readthedocs.io/en/v7.4.0/user-guide.html" } @@ -2343,59 +2342,6 @@ For the different individuals of the system the following information is used: }] } ] - -### Create Individual [POST] - -+ Request (application/json) - - + Headers - - Authorization: Bearer YOUR_OAUTH2_TOKEN - - + Body - - { - "id": "francisco-de-la-vega", - "birthDate": "1970-01-04T01:00:00+01:00", - "countryOfBirth": "DZ", - "familyName": "de la Vega", - "gender": "Male", - "givenName": "Francisco", - "maritalStatus": "Married", - "nationality": "spanish", - "placeOfBirth": "Madrid", - "title": "Mr", - "contactMedium": [{ - "type": "Email", - "preferred": "false", - "medium": { - "emailAddress": "fdelavega@conwet.com" - } - }] - } - -+ Response 201 (application/json) - - { - "id": "francisco-de-la-vega", - "href": "http://store.lab.fiware.org/DSPartyManagement/api/partyManagement/v2/individual/francisco-de-la-vega", - "birthDate": "1970-01-04T01:00:00+01:00", - "countryOfBirth": "DZ", - "familyName": "de la Vega", - "gender": "Male", - "givenName": "Francisco", - "maritalStatus": "Married", - "nationality": "spanish", - "placeOfBirth": "Madrid", - "title": "Mr", - "contactMedium": [{ - "type": "Email", - "preferred": "false", - "medium": { - "emailAddress": "fdelavega@conwet.com" - } - }] - } ## Individual Entry [/DSPartyManagement/api/partyManagement/v2/individual/{id}] @@ -3212,7 +3158,7 @@ This API uses the following fields: * **href** - URL pointing to the Usage Specification * **name** - Name of the usage specification * **description** - Textual description of the Usage Specification -* ** usageSpecCharacteristic** - List of characteristics which define the specific attributes of the described usage documents. Each characteristic is defined with the same format as the *productSpecCharacteristic* field of the Product Specification object, defined in the *Product Specification Management API* section +* **usageSpecCharacteristic** - List of characteristics which define the specific attributes of the described usage documents. Each characteristic is defined with the same format as the *productSpecCharacteristic* field of the Product Specification object, defined in the *Product Specification Management API* section Note, that for a usage document to be processed and understood by the system, it is required to include some fields which must also be defined as characteristics of the Usage Specification. This fields are: @@ -3222,7 +3168,8 @@ Note, that for a usage document to be processed and understood by the system, it * **unit** - Unit being monitored while accounting the service (e.g second, call, megabyte, etc) * **value** - Usage made of the service of the given unit -## Usage Specification Collection [DSUsageManagement/api/usageManagement/v2/usageSpecification] + +## Usage Specification Collection [/DSUsageManagement/api/usageManagement/v2/usageSpecification] ### List Usage Specifications [GET] @@ -3301,6 +3248,17 @@ Note, that for a usage document to be processed and understood by the system, it ### Create Usage Specification [POST] +As can be seen, the *Create Usage Specification* request includes a header *X-API-Key*. This header +has been included in order to enable the authentication of accounting applications which generate +the usage information. + +It is important to note, that the API key which must be used to create usage records cannot be +requested directly by users of the platform, since they are only issued to approved accounting applications. +In this regard, there are two mechanisms to get an API Key: + +* **manually** - The API key can be requested to an admin of the system who can manually create and deliver it. +* **automatically** - The API key can be generated automatically from the code of an asset plugin and then sent to the accounting application using the plugin event handlers. See the [programmer guide](http://business-api-ecosystem.readthedocs.io/en/latest/programmer-guide.html) for details on this topic. + + Request (application/json) + Headers @@ -3436,7 +3394,7 @@ Note, that for a usage document to be processed and understood by the system, it }] } -## Usage Specification Entry [DSUsageManagement/api/usageManagement/v2/usageSpecification/{id}] +## Usage Specification Entry [/DSUsageManagement/api/usageManagement/v2/usageSpecification/{id}] ### Get Usage Specification [GET] @@ -3550,7 +3508,7 @@ Note, that for a usage document to be processed and understood by the system, it * **unit** - Unit being monitored while accounting the service (e.g second, call, megabyte, etc) * **value** - Usage made of the service of the given unit -## Usage Collection [DSUsageManagement/api/usageManagement/v2/usage] +## Usage Collection [/DSUsageManagement/api/usageManagement/v2/usage] ### List Usages [GET] @@ -3616,6 +3574,18 @@ Note, that for a usage document to be processed and understood by the system, it ### Create Usage [POST] + +As can be seen, the *Create Usage* request includes a header *X-API-Key*. This header +has been included in order to enable the authentication of accounting applications which generate +the usage information. + +It is important to note, that the API key which must be used to create usage records cannot be +requested directly by users of the platform, since they are only issued to approved accounting applications. +In this regard, there are two mechanisms to get an API Key: + +* **manually** - The API key can be requested to an admin of the system who can manually create and deliver it. +* **automatically** - The API key can be generated automatically from the code of an asset plugin and then sent to the accounting application using the plugin event handlers. See the [programmer guide](http://business-api-ecosystem.readthedocs.io/en/latest/programmer-guide.html) for details on this topic. + + Request (application/json) + Headers @@ -3725,7 +3695,7 @@ Note, that for a usage document to be processed and understood by the system, it ] } -## Usage Entry [DSUsageManagement/api/usageManagement/v2/usage/{id}] +## Usage Entry [/DSUsageManagement/api/usageManagement/v2/usage/{id}] ### Get Usage [GET] diff --git a/doc/configuration-guide.rst b/doc/configuration-guide.rst new file mode 100644 index 0000000..5fcc4ba --- /dev/null +++ b/doc/configuration-guide.rst @@ -0,0 +1,466 @@ +=================== +Configuration Guide +=================== + +This guide covers the different configuration options that are available in order to setup a working Business API +Ecosystem instance. The different Business API Ecosystem components can be configured using two different mecahnisms, +settings files and environment variables. + +At this step, the different components of the Business API Ecosystem are installed. In the case of the TMForum APIs and +the RSS, this installation process has already required to configure their database connection before their deployment, +so they are already configured. Nevertheless, this section contains an explanation of the function of the different +settings of the RSS properties files. + +------------------------ +Configuring the TMF APIs +------------------------ + +When the TMF APIs are deployed from sources, the connection to the MySQL database is configured during the installation process +setting up the jdbc connection as described in the *Installation and Administration* guide. + +On the other hand, the Docker image biz-ecosystem-apis, which is used to the deploy TMF APIs using Docker, uses two environment +variables for configuring such connection. :: + + MYSQL_ROOT_PASSWORD=my-secret-pw + MYSQL_HOST=mysql + +Finally, the TMF APIs can optinally use a configuration file called *settings.properties* which is located by default at */etc/default/apis*. +This file include a setting *server* which allows to provide the URL used to access to the Business API Ecosystem and, in particular, by the APIs +in order to generate *hrefs* with the proper reference. :: + + server=https://store.lab.fiware.org/ + +This setting can also be configured using the environment variable *BAE_SERVICE_HOST* :: + + export BAE_SERVICE_HOST=https://store.lab.fiware.org/ + + +------------------- +Configuring the RSS +------------------- + +The RSS has its settings included in two files located at */etc/default/rss*. The file *database.properties* contains +by default the following fields: :: + + database.url=jdbc:mysql://localhost:3306/RSS + database.username=root + database.password=root + database.driverClassName=com.mysql.jdbc.Driver + +This file contains the configuration required in order to connect to the database. + +* database.url: URL used to connect to the database, this URL includes the host and port of the database as well as the concrete database to be used +* database.username: User to be used to connect to the database +* database.password: Password of the database user +* database.driverClassName: Driver class of the database. By default MySQL + +In addition, database settings can be configured using the environment. In particular, using the following variables: :: + + export BAE_RSS_DATABASE_URL=jdbc:mysql://mysql:3306/RSS + export BAE_RSS_DATABASE_USERNAME=root + export BAE_RSS_DATABASE_PASSWORD=my-secret-pw + export BAE_RSS_DATABASE_DRIVERCLASSNAME=com.mysql.jdbc.Driver + +The file *oauth.properties* contains by default the following fields (It is recommended not to modify them) :: + + config.grantedRole=admin + config.sellerRole=Seller + config.aggregatorRole=aggregator + +This file contains the name of the roles (registered in the idm) that are going to be used by the RSS. + +* config.grantedRole: Role in the IDM of the users with admin privileges +* config.sellerRole: Role in the IDM of the users with seller privileges +* config.aggregatorRole: Role of the users who are admins of an store instance. In the context of the Business API Ecosystem there is only a single store instance, so you can safely ignore this flag + +Those settings can also be configured using the environment as :: + + export BAE_RSS_OAUTH_CONFIG_GRANTEDROLE=admin + export BAE_RSS_OAUTH_CONFIG_SELLERROLE=Seller + export BAE_RSS_OAUTH_CONFIG_AGGREGATORROLE=Aggregator + +-------------------------------- +Configuring the Charging Backend +-------------------------------- + +The Charging Backend creates some objects and connections in the different APIs while working, so the first step is +configuring the different URLs of the Business API Ecosystem components by modifying the file *services_settings.py*, +which by default contains the following content: :: + + SITE = 'http://localhost:8004/' + LOCAL_SITE = 'http://localhost:8006/' + + CATALOG = 'http://localhost:8080/DSProductCatalog' + INVENTORY = 'http://localhost:8080/DSProductInventory' + ORDERING = 'http://localhost:8080/DSProductOrdering' + BILLING = 'http://localhost:8080/DSBillingManagement' + RSS = 'http://localhost:8080/DSRevenueSharing' + USAGE = 'http://localhost:8080/DSUsageManagement' + AUTHORIZE_SERVICE = 'http://localhost:8004/authorizeService/apiKeys' + +This settings points to the different APIs accessed by the charging backend. In particular: + +* SITE: External URL of the complete Business API Ecosystem using for Href creation +* LOCAL_SITE: URL where the Charging Backend is going to run +* CATALOG: URL of the catalog API including its path +* INVENTORY: URL of the inventory API including its path +* ORDERING: URL of the ordering API including its path +* BILLING: URL of the billing API including its path +* RSS: URL of the RSS including its path +* USAGE: URL of the Usage API including its path +* AUTHORIZE_SERVICE: Complete URL of the usage authorization service. This service is provided by the logic proxy, and is used to generate API Keys to be used by accounting systems when providing usage information. + +Once the services have been configured, the next step is configuring the database. In this case, the charging backend uses +MongoDB, and its connection can be configured modifying the *DATABASES* setting of the *settings.py* file. :: + + DATABASES = { + 'default': { + 'ENGINE': 'django_mongodb_engine', + 'NAME': 'wstore_db', + 'USER': '', + 'PASSWORD': '', + 'HOST': '', + 'PORT': '', + 'TEST_NAME': 'test_database', + } + } + +This setting contains the following fields: + +* ENGINE: Database engine, must be fixed to django_mongodb_engine +* NAME: Name of the database to be used +* USER: User of the database. If empty the software creates a non authenticated connection +* PASSWORD: Database user password. If empty the software creates a non authenticated connection +* HOST: Host of the database. If empty it uses the default *localhost* host +* PORT: Port of the database. If empty it uses the default *27017* port +* TEST_NAME: Name of the database to be used when running the tests + +Once the database connection has been configured, the next step is configuring the name of the IdM roles to be used by +updating *settings.py* :: + + ADMIN_ROLE = 'provider' + PROVIDER_ROLE = 'seller' + CUSTOMER_ROLE = 'customer' + +This settings contain the following values: + +* ADMIN_ROLE: IDM role of the system admin +* PROVIDER_ROLE: IDM role of the users with seller privileges +* CUSTOMER_ROLE: IDM role of the users with customer privileges + +The charging backend is the component in charge of maintaining the supported currencies and the timeframe of the different +periods using in recurring pricing models. To configure both, the following settings are used: :: + + CURRENCY_CODES = [ + ('EUR', 'Euro'), + ('AUD', 'Australia Dollar'), + ... + ] + CHARGE_PERIODS = { + 'daily': 1, # One day + 'weekly': 7, # One week + 'monthly': 30, # One month + ... + } + +* CURRENCY_CODES: Includes the list of currencies supported by the system as a tuple of currency code and currency name. +* CHARGE_PERIODS: Includes the list of supported periods for recurring models, specifing the time (in days) between periodic charges + +The Charging Backend component is able to send email notifications to the users when they are charged or receive a payment. +In this way, it is possible to provide email configuration in the *settings.py* file by modifying the following fields: :: + + WSTOREMAILUSER = 'email_user' + WSTOREMAIL = 'wstore_email' + WSTOREMAILPASS = 'wstore_email_passwd' + SMTPSERVER = 'wstore_smtp_server' + SMTPPORT = 587 + +This settings contain the following values: +* WSTOREMAILUSER: Username used for authenticating in the email server +* WSTOREMAIL: Email to be used as the sender of the notifications +* WSTOREMAILPASS: Password of the user for authenticating in the email server +* SMTPSERVER: Email server host +* SMTPPORT: Email server port + +.. note:: + The email configuration in optional. However, the field WSTOREMAIL must be provided since it is used internally for RSS configuration + +Additionally, the Charging Backend is the component that charges customers and pays providers. For this purpose it uses +PayPal. For configuring paypal, the first step is setting *PAYMENT_METHOD* to *paypal* in the *settings.py* file :: + + PAYMENT_METHOD = 'paypal' + +Then, it is required to provide PayPal application credentials by updating the file *src/wstore/charging_engine/payment_client/paypal_client.py* :: + + PAYPAL_CLIENT_ID = '' + PAYPAL_CLIENT_SECRET = '' + MODE = 'sandbox' # sandbox or live + +This settings contain the following values: + +* PAYPAL_CLIENT_ID: Id of the application provided by PayPal +* PAYPAL_CLIENT_SECRET: Secret of the application provided by PayPal +* MODE: Mode of the connection. It can be *sandbox* if using the PayPal sandbox for testing the system. Or *live* if using the real PayPal APIs + +Moreover, the Charging Backend is the component that activates the purchased services. In this regard, the Charging Backend +has the possibility of signing its acquisition notifications with a certificate, so the external system being offered can +validate that is the Charging Backend the one making the request. To use this functionality it is needed to configure the +certificate and the private Key to be used by providing its path in the following settings of the *settings.py* file :: + + NOTIF_CERT_FILE = None + NOTIF_CERT_KEY_FILE = None + +The Charging Backend uses a Cron task to check the status of recurring and usage subscriptions, and for paying sellers. +The periodicity of this tasks can be configured using the CRONJOBS setting of settings.py using the standard Cron format :: + + CRONJOBS = [ + ('0 5 * * *', 'django.core.management.call_command', ['pending_charges_daemon']), + ('0 6 * * *', 'django.core.management.call_command', ['resend_cdrs']), + ('0 4 * * *', 'django.core.management.call_command', ['resend_upgrade'] + ] + +Once the Cron task has been configured, it is necessary to include it in the Cron tasks using the command: +:: + + $ ./manage.py crontab add + +It is also possible to show current jobs or remove jobs using the commands: +:: + + $ ./manage.py crontab show + + $ ./manage.py crontab remove + +--------------------------- +Configuring the Logic Proxy +--------------------------- + +Configuration of the Logic Proxy is located at *config.js* and can be provided in two different ways: providing the values +in the file or using the defined environment variables. Note that the environment variables override the values in *config.js*. + +The first setting to be configured is the port and host where the proxy is going to run, this settings are located in *config.js* :: + + config.port = 80; + config.host = 'localhost'; + +In addition, the environment variables *BAE_LP_PORT* and *BAE_LP_HOST* can be used to override those values. :: + + export BAE_LP_PORT=80 + export BAE_LP_HOST=localhost + +If you want to run the proxy in HTTPS you can update *config.https* setting :: + + config.https = { + enabled: false, + certFile: 'cert/cert.crt', + keyFile: 'cert/key.key', + caFile: 'cert/ca.crt', + port: 443 + }; + +In this case you have to set *enabled* to true, and provide the paths to the certificate (*certFile*), to the private key (*keyFile*), +and to the CA certificate (*caFile*). + +In order to provide the HTTPS configuration using the environment, the following variables has been defined. :: + + export BAE_LP_HTTPS_ENABLED=true + export BAE_LP_HTTPS_CERT=cert/cert.crt + export BAE_LP_HTTPS_CA=cert/key.key + export BAE_LP_HTTPS_KEY=cert/ca.crt + export BAE_LP_HTTPS_PORT=443 + +The logic proxy supports the BAE to be deployed behind a proxy (or NGINX, Apache, etc) not sending X-Forwarding headers. In this +regard, the following setting is used in order to provide information about the actual endpoint which is used to access to the +Business API Ecosystem: :: + + config.proxy = { + enabled: true, + host: 'store.lab.fiware.org', + secured: true, + port: 443 + }; + +Which can be also configured using the *BAE_SERVICE_HOST* environment variable. :: + + export BAE_SERVICE_HOST=https://store.lab.fiware.org/ + +Then, it is possible to modify some of the URLs of the system. Concretely, it is possible to provide a prefix for the API, +a prefix for the portal, and modifying the login and logout URLS :: + + config.proxyPrefix = ''; + config.portalPrefix = ''; + config.logInPath = '/login'; + config.logOutPath = '/logOut'; + +In addition, it is possible to configure the theme to be used by providing its name. Details about the configuration of +Themes are provided in the *Configuring Themes* section:: + + config.theme = ''; + +The theme can be configured using the *BAE_LP_THEME* variable. :: + + export BAE_LP_THEME=fiwaretheme + +Additionally, the proxy is the component that acts as the front end of the Business API Ecosystem, both providing a web portal, +and providing the endpoint for accessing to the different APIs. In this regard, the Proxy has to have the OAuth2 configuration +of the FIWARE IDM. + +To provide OAUth2 configuration, an application has to be created in an instance of the FIWARE IdM (e.g `https://account.lab.fiware.org`), +providing the following information: + +* URL: http|https://: +* Callback URL: http|https://:/auth/fiware/callback +* Create a role *Seller*, a role *Admin*, and a role *orgAdmin* + +Once the application has been created in the IdM, it is possible to provide OAuth2 configuration by modifying the following settings :: + + config.oauth2 = { + 'server': 'https://account.lab.fiware.org', + 'clientID': '', + 'clientSecret': '', + 'callbackURL': 'http://:/auth/fiware/callback', + 'isLegacy': false, + 'roles': { + 'admin': 'admin', + 'customer': 'customer', + 'seller': 'seller', + 'orgAdmin': 'orgAdmin' + } + }; + +In this settings, it is needed to include the IDM instance being used (*server*), the client id given by the IdM (*clientID*), +the client secret given by the IdM (*clientSecret*), and the callback URL configured in the IdM (*callbackURL*). + +In addition, the different roles allow to specify what users are admins of the system (*Admin*), what users can create products +and offerings (*Seller*), and what users are admins of a particular organization, enabling to manage its information (*orgAdmin*). +Note that while *admin* and *seller* roles are granted directly to the users in the Business API Ecosystem application, the *orgAdmin* +role has to be granted to users within IdM organizations. + +.. note:: + Admin, Seller, and orgAdmin roles are configured in the Proxy settings, so any name can be chosen for them in the IDM + +The *isLegacy* flag is used to specify whether the configured IDM is version 6 or lower, by default this setting is false. + +The OAuth2 settings cane be configured using the environment as follows: :: + + export BAE_LP_OAUTH2_SERVER=https://account.lab.fiware.org + export BAE_LP_OAUTH2_CLIENT_ID=client_id + export BAE_LP_OAUTH2_CLIENT_SECRET=client_secret + export BAE_LP_OAUTH2_CALLBACK=http://:/auth/fiware/callback + export BAE_LP_OAUTH2_ADMIN_ROLE=admin + export BAE_LP_OAUTH2_SELLER_ROLE=seller + export BAE_LP_OAUTH2_ORG_ADMIN_ROLE=orgAdmin + + export BAE_LP_OAUTH2_IS_LEGACY=false + +Moreover, the Proxy uses MongoDB for maintaining some info, such as the current shopping cart of a user. you can configure +the connection to MongoDB by updating the following setting: :: + + config.mongoDb = { + server: 'localhost', + port: 27017, + user: '', + password: '', + db: 'belp' + }; + +In this setting you can configure the host (*server*), the port (*port*), the database user (*user*), the database user password +(*password*), and the database name (*db*). + +In addition, the database connection can be configured with the environment as following: :: + + export BAE_LP_MONGO_USER=user + export BAE_LP_MONGO_PASS=pass + export BAE_LP_MONGO_SERVER=localhost + export BAE_LP_MONGO_PORT=27017 + export BAE_LP_MONGO_DB=belp + +As already stated, the Proxy is the component that acts as the endpoint for accessing the different APIs. In this way, +the proxy needs to know the URLs of them in order to redirect the different requests. This endpoints can be configured using the +following settings :: + + config.endpoints = { + 'catalog': { + 'path': 'DSProductCatalog', + 'host': 'localhost' + 'port': '8080', + 'appSsl': false + }, + 'ordering': { + 'path': 'DSProductOrdering', + 'host': 'localhost' + 'port': '8080', + 'appSsl': false + }, + + ... + +The setting *config.endpoints* contains the specific configuration of each of the APIs, including its *path*, its *host*, +its *port*, and whether the API is using SSL or not. + +.. note:: + The default configuration included in the config file is the one used by the installation script, so if you have used the script for + installing the Business API Ecosystem you do not need to modify these fields + +Each of the different APIs can be configured with environment variables with the following pattern: :: + + export BAE_LP_ENDPOINT_CATALOG_PATH=DSProductCatalog + export BAE_LP_ENDPOINT_CATALOG_PORT=8080 + export BAE_LP_ENDPOINT_CATALOG_HOST=localhost + export BAE_LP_ENDPOINT_CATALOG_SECURED=false + +Finally, there are two fields that allow to configure the behaviour of the system while running. On the one hand, *config.revenueModel* +allows to configure the default percentage that the Business API Ecosystem is going to retrieve in all the transactions. +On the other hand, *config.usageChartURL* allows to configure the URL of the chart to be used to display product usage to +customers in the web portal. They can be configured with environment variables with *BAE_LP_REVENUE_MODEL* and *BAE_LP_USAGE_CHART* + +------------------ +Configuring Themes +------------------ + +The Business API Ecosystem provides a basic mechanism for the creation of themes intended to customize the web portal +of the system. Themes include a set of files which can override any of the default portal files located in the *public/resources* +or *views* directories of the logic proxy. To do that, themes map the directory structure and include files with the same +name of the default ones to be overridden. + +The Logic Proxy can include multiple themes which should be stored in the *themes* directory located at the root of the +project. + +To enable themes, the *config.theme* setting is provided within the *config.js* file of the Logic Proxy. Themes are +enabled by providing the name of the theme directory in this setting. :: + + config.theme = 'dark-theme'; + +.. note:: + Setting *config.theme* to an empty string makes the Business API Ecosystem to use its default theme + +To start using a theme the following command has to be executed: :: + + $ node collect_static.js + +This command merges the theme files and the default ones into a *static* directory used by the Logic Proxy to retrieve +portal static files. + +------------------- +Enabling Production +------------------- + +The default installation of the Business API Ecosystem deploys its different components in *debug* mode. This is useful +for development and testing but it is not adequate for production environments. + +Enabling the production mode makes the different components to start caching requests and views and minimizing JavaScript +files. + +To enable the production mode, the first step is setting the environment variable *NODE_ENV* to *production* in the machine +containing the Logic Proxy. :: + + $ export NODE_ENV=production + +Then, it is needed to collect static files in order to compress JavaScript files. :: + + $ node collect_static.js + + +Finally, change the setting *DEBUG* of the Charging Backend to False. :: + + DEBUG=False diff --git a/doc/docker-guide.rst b/doc/docker-guide.rst new file mode 100644 index 0000000..2c98aac --- /dev/null +++ b/doc/docker-guide.rst @@ -0,0 +1,273 @@ +======================= +Docker Deployment Guide +======================= + +This guide covers the deployment of the Business API Ecosystem version 7.4.0 using the Docker images provided in docker hub. + +As stated, the Business API Ecosystem in made up of a set of different components which work jointly in order to provide +the functionality. In this regard the following images has been defined: + +* fiware/biz-ecosystem-apis: This image includes all the TMForum APIs and can be found in `Docker Hub `__ +* fiware/biz-ecosystem-charging-backend: This image includes the Charging Backend component and can be found in `Docker Hub `__ +* fiware/biz-ecosystem-logic-proxy: This image includes the Logic Proxy component and can be found in `Docker Hub `__ +* fiware/biz-ecosystem-rss: This Image include the Revenue Sharing Component and can be found in `Docker Hub `__ + +The easiest way to deploy the Business API Ecosystem with Docker is using *docker-compose*. The following *docker-compose.yml* +file deploys the whole system and databases (A running version of this file can be found in GitHub): :: + + version: '3' + services: + mongo: + image: mongo:3.2 + restart: always + ports: + - 27017:27017 + networks: + main: + volumes: + - ./mongo-data:/data/db + + mysql: + image: mysql:5.7 + restart: always + ports: + - 3333:3306 + volumes: + - ./mysql-data:/var/lib/mysql + networks: + main: + environment: + - MYSQL_ROOT_PASSWORD=my-secret-pw + - MYSQL_DATABASE=RSS + + charging: + image: fiware/biz-ecosystem-charging-backend:v7.4.0 + links: + - mongo + depends_on: + - mongo + networks: + main: + aliases: + - charging.docker + ports: + - 8006:8006 + volumes: + # - ./charging-settings:/business-ecosystem-charging-backend/src/user_settings # Used if the settings files are provided through the volume + - ./charging-bills:/business-ecosystem-charging-backend/src/media/bills + - ./charging-assets:/business-ecosystem-charging-backend/src/media/assets + - ./charging-plugins:/business-ecosystem-charging-backend/src/plugins + - ./charging-inst-plugins:/business-ecosystem-charging-backend/src/wstore/asset_manager/resource_plugins/plugins + environment: + - BAE_CB_PAYMENT_METHOD=None # Paypal or None (testing mode payment disconected) + # - BAE_CB_PAYPAL_CLIENT_ID=client_id + # - BAE_CB_PAYPAL_CLIENT_SECRET=client_secret + + # ----- Database configuration ------ + - BAE_CB_MONGO_SERVER=mongo + - BAE_CB_MONGO_PORT=27017 + - BAE_CB_MONGO_DB=charging_db + # - BAE_CB_MONGO_USER=user + # - BAE_CB_MONGO_PASS=passwd + + # ----- Roles Configuration ----- + - BAE_LP_OAUTH2_ADMIN_ROLE=admin + - BAE_LP_OAUTH2_SELLER_ROLE=seller + - BAE_LP_OAUTH2_CUSTOMER_ROLE=customer + + # ----- Email configuration ------ + - BAE_CB_EMAIL=charging@email.com + # - BAE_CB_EMAIL_USER=user + # - BAE_CB_EMAIL_PASS=pass + # - BAE_CB_EMAIL_SMTP_SERVER=smtp.server.com + # - BAE_CB_EMAIL_SMTP_PORT=587 + + - BAE_CB_VERIFY_REQUESTS=True # Whether or not the BAE validates SSL certificates on requests to external components + + # ----- Site configuration ----- + - BAE_SERVICE_HOST=http://proxy.docker:8004/ # External URL used to access the BAE + - BAE_CB_LOCAL_SITE=http://charging.docker:8006/ # Local URL of the charging backend + + # ----- APIs Conection config ----- + - BAE_CB_CATALOG=http://apis.docker:8080/DSProductCatalog + - BAE_CB_INVENTORY=http://apis.docker:8080/DSProductInventory + - BAE_CB_ORDERING=http://apis.docker:8080/DSProductOrdering + - BAE_CB_BILLING=http://apis.docker:8080/DSBillingManagement + - BAE_CB_RSS=http://rss.docker:8080/DSRevenueSharing + - BAE_CB_USAGE=http://apis.docker:8080/DSUsageManagement + - BAE_CB_AUTHORIZE_SERVICE=http://proxy.docker:8004/authorizeService/apiKeys + + proxy: + image: fiware/biz-ecosystem-logic-proxy:v7.4.0 + links: + - mongo + depends_on: + - mongo + networks: + main: + aliases: + - proxy.docker + ports: + - 8004:8000 + volumes: + # - ./proxy-conf:/business-ecosystem-logic-proxy/etc # To be used when congiguring the system with a config file provided in the volume + - ./proxy-indexes:/business-ecosystem-logic-proxy/indexes + - ./proxy-themes:/business-ecosystem-logic-proxy/themes + - ./proxy-static:/business-ecosystem-logic-proxy/static + - ./proxy-locales:/business-ecosystem-logic-proxy/locales + environment: + - NODE_ENV=development # Deployment in development or in production + - COLLECT=True # Execute the collect static command on startup + + - BAE_LP_PORT=8000 # Port where the node service is going to run in the container + - BAE_LP_HOST=proxy.docker # Host where the node service if going to run in the container + # - BAE_SERVICE_HOST=https://store.lab.fiware.org/ # If provided, this URL specifies the actual URL that is used to access the BAE, when the component is proxied (e.g Apache) + # - BAE_LP_HTTPS_ENABLED=true # If provided specifies whether the service is running in HTTPS, default: false + # - BAE_LP_HTTPS_CERT=cert/cert.crt # Certificate for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_CA=cert/ca.crt # CA certificate for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_KEY=cert/key.key # Key sfile for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_PORT=443 # Port where the service runs when SSL is enabled (when HTTPS enabled is true) + + # ------ OAUTH2 Config ------ + - BAE_LP_OAUTH2_SERVER=http://idm.docker:8000 # URL of the FIWARE IDM used for user authentication + - BAE_LP_OAUTH2_CLIENT_ID=id # OAuth2 Client ID of the BAE applicaiton + - BAE_LP_OAUTH2_CLIENT_SECRET=secret # OAuth Client Secret of the BAE application + - BAE_LP_OAUTH2_CALLBACK=http://proxy.docker:8004/auth/fiware/callback # Callback URL for receiving the access tokens + - BAE_LP_OAUTH2_ADMIN_ROLE=admin # Role defined in the IDM client app for admins of the BAE + - BAE_LP_OAUTH2_SELLER_ROLE=seller # Role defined in the IDM client app for sellers of the BAE + - BAE_LP_OAUTH2_CUSTOMER_ROLE=customer # Role defined in the IDM client app for customers of the BAE + - BAE_LP_OAUTH2_ORG_ADMIN_ROLE=orgAdmin # Role defined in the IDM client app for organization admins of the BAE + - BAE_LP_OAUTH2_IS_LEGACY=false # Whether the used FIWARE IDM is version 6 or lower + + # - BAE_LP_THEME=theme # If provided custom theme to be used by the web site, it must be included in themes volume + + # ----- Mongo Config ------ + # - BAE_LP_MONGO_USER=user + # - BAE_LP_MONGO_PASS=pass + - BAE_LP_MONGO_SERVER=mongo + - BAE_LP_MONGO_PORT=27017 + - BAE_LP_MONGO_DB=belp + + - BAE_LP_REVENUE_MODEL=30 # Default market owner precentage for Revenue Sharing models + + # ----- APIs Configuration ----- + # If provided, it supports configuring the contection to the different APIs managed by the logic proxy, by default + # apis.docker, charging.docker and rss.docker domains are configured + # - BAE_LP_ENDPOINT_CATALOG_PATH=DSProductCatalog + # - BAE_LP_ENDPOINT_CATALOG_PORT=8080 + # - BAE_LP_ENDPOINT_CATALOG_HOST=apis.docker + # - BAE_LP_ENDPOINT_CATALOG_SECURED=false + # ... + + apis: + image: fiware/biz-ecosystem-apis:v7.4.0 + restart: always + ports: + - 4848:4848 + - 8080:8080 + links: + - mysql + depends_on: + - mysql + networks: + main: + aliases: + - apis.docker + # volumes: + # - ./apis-conf:/etc/default/tmf/ # Used if not configured by environment + environment: + - BAE_SERVICE_HOST=http://proxy.docker:8004/ + - MYSQL_ROOT_PASSWORD=my-secret-pw + - MYSQL_HOST=mysql + + rss: + image: fiware/biz-ecosystem-rss:v7.4.0 + restart: always + ports: + - 9999:8080 + - 4444:4848 + - 1111:8181 + links: + - mysql + depends_on: + - mysql + networks: + main: + aliases: + - rss.docker + # volumes: + # - ./rss-conf:/etc/default/rss # Used if not configured by environment + environment: + - BAE_RSS_DATABASE_URL=jdbc:mysql://mysql:3306/RSS + - BAE_RSS_DATABASE_USERNAME=root + - BAE_RSS_DATABASE_PASSWORD=my-secret-pw + - BAE_RSS_DATABASE_DRIVERCLASSNAME=com.mysql.jdbc.Driver + - BAE_RSS_OAUTH_CONFIG_GRANTEDROLE=admin + - BAE_RSS_OAUTH_CONFIG_SELLERROLE=seller + - BAE_RSS_OAUTH_CONFIG_AGGREGATORROLE=Aggregator + networks: + main: + external: true + +.. note:: + The previous example uses an external network called *main*, which need to exist. If you do not want to use such network just remove the network tags + + +The different images provided can be configured in two different ways as it is done with the software. On the one hand, +configuration parameters can be included as environment variables (as shown in the example). On the other hand, the different +images can be configured by providing configuration files throught volumes. + +For details on the different configuration options, please refer to the `*Configuration Guide* `__ + +It can be seen that the different images used as part of the Business API Ecosystem provide several volumes. Following +it is descrived the diffent options provided by each image. + +The **biz-ecosystem-logic-proxy** image defines 4 volumes. In particular: + +* */business-ecosystem-logic-proxy/etc*: When file configuration is used, this volume must include the `config.js` file with the software configuration +* */business-ecosystem-logic-proxy/indexes*: This volume contains the indexes used by the Business API Ecosystem for searching +* */business-ecosystem-logic-proxy/themes*: In this volume, it can be provided the themes that can be used to customize the web portal +* */business-ecosystem-logic-proxy/static*: This volume includes the static files ready to be rendered including the selected theme and js files + +Additionally, the **biz-ecosystem-logic-proxy** image defines two environment variables intended to optimize the production deployment of the BAE Logic proxy: + +* *NODE_ENV*: Specifies whether the system is in *development* or in *production* (default: development) +* *COLLECT*: Specifies if the container should execute the collect static command to generate static files or use the existing on start up (default: True) + +On the other hand, the **biz-ecosystem-charging-backend** image defines 4 volumes. In particular: + +* */business-ecosystem-charging-backend/src/user_settings*: This directory must include the *settings.py* and *services_settings.py* files with the software configuration, when the volume configuration is used. +* */business-ecosystem-charging-backend/src/media/bills*: This directory contains the PDF invoices generated by the Business Ecosystem Charging Backend +* */business-ecosystem-charging-backend/src/media/assets*: This directory contains the different digital assets uploaded by sellers to the Business Ecosystem Charging Backend +* */business-ecosystem-charging-backend/src/plugins*: This directory is used for providing asset plugins (see section *Installing Asset Plugins*) +* */business-ecosystem-charging-backend/src/wstore/asset_manager/resource_plugins/plugins*: This directory includes the code of the plugins already installed + +------------------------ +Installing Asset Plugins +------------------------ + +As you may know, the Business API Ecosystem is able to sell different types of digital assets +by loading asset plugins in its Charging Backend. In this context, it is possible to install +asset plugins in the current Docker image as follows: + +1) Copy the plugin file into the host directory of the volume */business-ecosystem-charging-backend/src/plugins* + +2) Enter the running container: :: + + docker exec -i -t your-container bash + + +3) Go to the installation directory :: + + cd /business-ecosystem-charging-backend/src + + +4) Load the plugin :: + + ./manage.py loadplugin ./plugins/pluginfile.zip + + +5) Restart Apache :: + + service apache2 graceful + diff --git a/doc/index.rst b/doc/index.rst index 48e6ee8..155db18 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -26,12 +26,26 @@ Concretely, the Business API Ecosystem is made of the following components: * *Business Ecosystem RSS*: Is in charge of distributing the revenues originated by the usage of a given service among the involved stakeholders. In particular, it focuses on distributing part of the revenue generated by a service between the Business API Ecosystem instance provider and the Service Provider(s) responsible for the service. With the term "service" we refer to both final applications and backend application services (typically exposed through an API). Note that, in the case of composite services, more than one service provider may have to receive a share of the revenues. * *Business Ecosystem Logic Proxy*: Acts as the endpoint for accessing the Business API Ecosystem. On the one hand, it orchestrates the APIs validating user requests, including authentication, authorization, and the content of the request from a business logic point of view. On the other hand, it serves a web portal that can be used to interact with the system. +The current documentation covers the Business API Ecosystem version 7.4.0, corresponding to FIWARE release 7. Any feedback on this document is highly welcomed, including bugs, +typos or things you think should be included but aren't. Please send them to the "Contact Person" email that appears in the +`Catalogue page for this GEi`_. Or create an issue at `GitHub Issues`_ + +.. _Catalogue page for this GEi: https://catalogue.fiware.org/enablers/business-api-ecosystem-biz-ecosystem-ri +.. _GitHub Issues: https://github.com/FIWARE-TMForum/Business-API-Ecosystem/issues/new + + Index ===== :doc:`installation-administration-guide` The guide for maintainers that explains how to install it. +:doc:`docker-guide` + The guide for maintainers that explains how to use Docker for deploying it + +:doc:`configuration-guide` + The guide for administrations which explains the different configuration options + :doc:`user-guide` The guide for users that explains how to use it. @@ -48,6 +62,8 @@ Index :caption: Documentation installation-administration-guide + docker-guide + configuration-guide user-guide programmer-guide plugins-guide diff --git a/doc/installation-administration-guide.rst b/doc/installation-administration-guide.rst index 4678093..e869d11 100644 --- a/doc/installation-administration-guide.rst +++ b/doc/installation-administration-guide.rst @@ -2,20 +2,15 @@ Installation and Administration Guide ===================================== ------------- -Introduction ------------- - -This installation and administration guide covers the Business API Ecosystem version 6.4.0, corresponding to FIWARE release 6. -Any feedback on this document is highly welcomed, including bugs, typos or things you think should be included but aren't. -Please send them to the "Contact Person" email that appears in the `Catalogue page for this GEi`_. Or create an issue at `GitHub Issues`_ +This guide covers the installation of the Business API Ecosystem v7.4.0 from the sources available in GitHub, installing manually +the software dependencies and using the existing scripts for setting up the system. -.. _Catalogue page for this GEi: https://catalogue.fiware.org/enablers/business-api-ecosystem-biz-ecosystem-ri -.. _GitHub Issues: https://github.com/FIWARE-TMForum/Business-API-Ecosystem/issues/new - -The current version of the software has been tested under Ubuntu 14.04, Ubuntu 15.10, Ubuntu 16.04, Debian 7, Debian 8, +The current version of the software has been tested under Ubuntu 15.10, Ubuntu 16.04, Ubuntu 18.04, Debian 7, Debian 8, and CentOS 7. THESE ARE THEREFORE CONSIDERED AS THE SUPPORTED OPERATING SYSTEMS. +.. note:: + The preferred mechanism for the deployment of the Business API Ecosystem is Docker as described in `Docker deployment guide `__ + ------------ Installation ------------ @@ -24,7 +19,7 @@ Requirements ============ As described in the GEri overview, the Business API Ecosystem is not a single software, but a set of projects that -work together for proving business capabilities. In this regard, this section contains the basic dependencies of +work together for providing business capabilities. In this regard, this section contains the basic dependencies of the different components that made up the Business API Ecosystem. .. note:: @@ -35,7 +30,7 @@ TM Forum APIs and RSS requirements * Java 8 * Glassfish 4.1 -* MySQL 5.5 +* MySQL 5.7 Charging Backend requirements ----------------------------- @@ -47,7 +42,7 @@ Charging Backend requirements Logic Proxy requirements ------------------------ -* NodeJS 4.5.0+ (Including NPM) +* NodeJS 6.9.1+ (Including NPM) Installing basic dependencies @@ -56,7 +51,7 @@ Installing basic dependencies Basic dependencies such as Java 8, Glassfish, MySQL, Python, etc. Can be installed using the package management tools provided by your operating system. However, in order to easy the installation process some scripts have been provided. -.. note:: +.. warning:: The installation script may override some of the packages already installed in the system. so if you have software with common dependencies you may want to manually resolve them. Installing basic dependencies using the script @@ -340,7 +335,7 @@ The installation for all of them is similar. The first step is cloning the repos $ git clone https://github.com/FIWARE-TMForum/DSPRODUCTCATALOG2.git $ cd DSPRODUCTCATALOG2 - $ git checkout v6.4.0 + $ git checkout v7.4.0 Once the software has been downloaded, it is needed to create the connection to the database. To do that, the first step is editing the *src/main/resources/META-INF/persistence.xml* to have something similar to the following: :: @@ -403,7 +398,7 @@ The first step for installing the RSS component is downloading it and moving to $ git clone https://github.com/FIWARE-TMForum/business-ecosystem-rss.git $ cd business-ecosystem-rss - $ git checkout v6.4.0 + $ git checkout v7.4.0 Then, the next step is coping, *database.properties* and *oauth.properties* files to its default location at */etc/default/rss* :: @@ -450,7 +445,7 @@ The first step for installing the charging backend component is downloading it a $ git clone https://github.com/FIWARE-TMForum/business-ecosystem-charging-backend.git $ cd business-ecosystem-charging-backend - $ git checkout v6.4.0 + $ git checkout v7.4.0 Once the code has been downloaded, it is recommended to create a virtualenv for installing python dependencies (This is not mandatory). :: @@ -464,232 +459,8 @@ To install python libs, execute the *python-dep-install.sh* script :: .. note:: If you have not created and activated a virtualenv you will need to execute the script using sudo -Installing the Logic Proxy -++++++++++++++++++++++++++ - -The Logic Proxy sources can be found in`GitHub `__ - -The first step for installing the logic proxy component is downloading it and moving to the correct release :: - - $ git clone https://github.com/FIWARE-TMForum/business-ecosystem-logic-proxy.git - $ cd business-ecosystem-logic-proxy - $ git checkout v6.4.0 - -Once the code has been downloaded, Node dependencies can be installed with the provided script as follows :: - - $ ./install.sh - -Upgrading from 5.4.1 -==================== - -For upgrading Business API Ecosystem version 5.4.1 installations to version 6.4.0 a new command has been incorporated -within the *install.py* script. This command downloads new components software, updates it, and migrates the -different databases, so it lets the software ready to be used. - -.. note:: - It is highly recommended to make a backup of the different databases before upgrading the software - -The first step for upgrading the Business API Ecosystem is downloading new version of the main repository in order to -update installation scripts. :: - - cd Business-API-Ecosystem - git fetch - git checkout v6.4.0 - git pull origin v6.4.0 - -The new version of *install.py* has a new dependency (PyMSQL) that has to be manually solved in order to execute -the upgrading command. :: - - $ pip3 install pymysql - -Once the main repository is upgraded, the next step is using the provided script for upgrading the software. :: - - $ ./install.py upgrade - -This command do not change your configuration parameters. Nevertheless, you should review the *Configuration* section -as new settings has been included. - -The *upgrade* command uses a set of new commands that have been incorporated within *install.py* in order to manage the -upgrade. In particular: - -* **download**: Downloads the new software for the different components of the Business API Ecosystem -* **dump**: Creates a dump of the different MySQL databases within */tmp* -* **migrate**: Migrates database contents from v5.4.1 to v6.4.0 - -------------- -Configuration -------------- - -At this step, the different components of the Business API Ecosystem are installed. In the case of the TMForum APIs and -the RSS, this installation process has already required to configure their database connection before their deployment, -so they are already configured. Nevertheless, this section contains an explanation of the function of the different -settings of the RSS properties files. - -Configuring the RSS -=================== - -The RSS has its settings included in two files located at */etc/default/rss*. The file *database.properties* contains -by default the following fields: :: - - database.url=jdbc:mysql://localhost:3306/RSS - database.username=root - database.password=root - database.driverClassName=com.mysql.jdbc.Driver - -This file contains the configuration required in order to connect to the database. - -* database.url: URL used to connect to the database, this URL includes the host and port of the database as well as the concrete database to be used -* database.username: User to be used to connect to the database -* database.password: Password of the database user -* database.driverClassName: Driver class of the database. By default MySQL - -The file *oauth.properties* contains by default the following fields (It is recommended not to modify them) :: - - config.grantedRole=Provider - config.sellerRole=Seller - config.aggregatorRole=aggregator - -This file contains the name of the roles (registered in the idm) that are going to be used by the RSS. - -* config.grantedRole: Role in the IDM of the users with admin privileges -* config.sellerRole: Role in the IDM of the users with seller privileges -* config.aggregatorRole: Role of the users who are admins of an store instance. In the context of the Business API Ecosystem there is only a single store instance, so you can safely ignore this flag - -Configuring the Charging Backend -================================ - -The Charging Backend creates some objects and connections in the different APIs while working, so the first step is -configuring the different URLs of the Business API Ecosystem components by modifying the file *services_settings.py*, -which by default contains the following content: :: - - SITE = 'http://localhost:8004/' - LOCAL_SITE = 'http://localhost:8006/' - - CATALOG = 'http://localhost:8080/DSProductCatalog' - INVENTORY = 'http://localhost:8080/DSProductInventory' - ORDERING = 'http://localhost:8080/DSProductOrdering' - BILLING = 'http://localhost:8080/DSBillingManagement' - RSS = 'http://localhost:8080/DSRevenueSharing' - USAGE = 'http://localhost:8080/DSUsageManagement' - AUTHORIZE_SERVICE = 'http://localhost:8004/authorizeService/apiKeys' - -This settings points to the different APIs accessed by the charging backend. In particular: - -* SITE: External URL of the complete Business API Ecosystem using for Href creation -* LOCAL_SITE: URL where the Charging Backend is going to run -* CATALOG: URL of the catalog API including its path -* INVENTORY: URL of the inventory API including its path -* ORDERING: URL of the ordering API including its path -* BILLING: URL of the billing API including its path -* RSS: URL of the RSS including its path -* USAGE: URL of the Usage API including its path -* AUTHORIZE_SERVICE: Complete URL of the usage authorization service. This service is provided by the logic proxy, and is used to generate API Keys to be used by accounting systems when providing usage information. - -Once the services have been configured, the next step is configuring the database. In this case, the charging backend uses -MongoDB, and its connection can be configured modifying the *DATABASES* setting of the *settings.py* file. :: - - DATABASES = { - 'default': { - 'ENGINE': 'django_mongodb_engine', - 'NAME': 'wstore_db', - 'USER': '', - 'PASSWORD': '', - 'HOST': '', - 'PORT': '', - 'TEST_NAME': 'test_database', - } - } - -This setting contains the following fields: - -* ENGINE: Database engine, must be fixed to django_mongodb_engine -* NAME: Name of the database to be used -* USER: User of the database. If empty the software creates a non authenticated connection -* PASSWORD: Database user password. If empty the software creates a non authenticated connection -* HOST: Host of the database. If empty it uses the default *localhost* host -* PORT: Port of the database. If empty it uses the default *27017* port -* TEST_NAME: Name of the database to be used when running the tests - -Once the database connection has been configured, the next step is configuring the name of the IdM roles to be used by -updating *settings.py* :: - - ADMIN_ROLE = 'provider' - PROVIDER_ROLE = 'seller' - CUSTOMER_ROLE = 'customer' - -This settings contain the following values: - -* ADMIN_ROLE: IDM role of the system admin -* PROVIDER_ROLE: IDM role of the users with seller privileges -* CUSTOMER_ROLE: IDM role of the users with customer privileges - -The Charging Backend component is able to send email notifications to the users when they are charged or receive a payment. -In this way, it is possible to provide email configuration in the *settings.py* file by modifying the following fields: :: - - WSTOREMAILUSER = 'email_user' - WSTOREMAIL = 'wstore_email' - WSTOREMAILPASS = 'wstore_email_passwd' - SMTPSERVER = 'wstore_smtp_server' - SMTPPORT = 587 - -This settings contain the following values: -* WSTOREMAILUSER: Username used for authenticating in the email server -* WSTOREMAIL: Email to be used as the sender of the notifications -* WSTOREMAILPASS: Password of the user for authenticating in the email server -* SMTPSERVER: Email server host -* SMTPPORT: Email server port - -.. note:: - The email configuration in optional. However, the field WSTOREMAIL must be provided since it is used internally for RSS configuration - -Additionally, the Charging Backend is the component that charges customers and pays providers. For this purpose it uses -PayPal. For configuring paypal, the first step is setting *PAYMENT_METHOD* to *paypal* in the *settings.py* file :: - - PAYMENT_METHOD = 'paypal' - -Then, it is required to provide PayPal application credentials by updating the file *src/wstore/charging_engine/payment_client/paypal_client.py* :: - - PAYPAL_CLIENT_ID = '' - PAYPAL_CLIENT_SECRET = '' - MODE = 'sandbox' # sandbox or live - -This settings contain the following values: - -* PAYPAL_CLIENT_ID: Id of the application provided by PayPal -* PAYPAL_CLIENT_SECRET: Secret of the application provided by PayPal -* MODE: Mode of the connection. It can be *sandbox* if using the PayPal sandbox for testing the system. Or *live* if using the real PayPal APIs - -Moreover, the Charging Backend is the component that activates the purchased services. In this regard, the Charging Backend -has the possibility of signing its acquisition notifications with a certificate, so the external system being offered can -validate that is the Charging Backend the one making the request. To use this functionality it is needed to configure the -certificate and the private Key to be used by providing its path in the following settings of the *settings.py* file :: - - NOTIF_CERT_FILE = None - NOTIF_CERT_KEY_FILE = None - -The Charging Backend uses a Cron task to check the status of recurring and usage subscriptions, and for paying sellers. -The periodicity of this tasks can be configured using the CRONJOBS setting of settings.py using the standard Cron format :: - - CRONJOBS = [ - ('0 5 * * *', 'django.core.management.call_command', ['pending_charges_daemon']), - ('0 6 * * *', 'django.core.management.call_command', ['resend_cdrs']), - ('0 4 * * *', 'django.core.management.call_command', ['resend_upgrade'] - ] - -Once the Cron task has been configured, it is necessary to include it in the Cron tasks using the command: -:: - - $ ./manage.py crontab add - -It is also possible to show current jobs or remove jobs using the commands: -:: - - $ ./manage.py crontab show - - $ ./manage.py crontab remove - Configure Apache for running the Charging Backend -------------------------------------------------- +################################################# The Charging Backend is a Django App that can be deployed in different ways. In this case, this installation guide covers two different mechanisms: using the Django *runserver* command (as seen in *Running the Charging Backend* section) or @@ -797,117 +568,57 @@ Or in CentOS :: Ensure that the directory where the Changing Backend is installed can be accessed by the Apache user (www-data in Ubuntu/Debian, and apache in CentOS) -Configuring the Logic Proxy -=========================== - -The first step for configuring the proxy is creating the configuration file by coping *config.js.template* to *config.js* :: - - $ cp config.js.template config.js - -The first setting to be configured is the port and host where the proxy is going to run, this settings are located in *config.js* :: - - config.port = 80; - config.host = 'localhost'; - -If you want to run the proxy in HTTPS you can update *config.https* setting :: - - config.https = { - enabled: false, - certFile: 'cert/cert.crt', - keyFile: 'cert/key.key', - caFile: 'cert/ca.crt', - port: 443 - }; - -In this case you have to set *enabled* to true, and provide the paths to the certificate (*certFile*), to the private key (*keyFile*), -and to the CA certificate (*caFile*). - -Then, it is possible to modify some of the URLs of the system. Concretely, it is possible to provide a prefix for the API, -a prefix for the portal, and modifying the login and logout URLS :: - - config.proxyPrefix = ''; - config.portalPrefix = ''; - config.logInPath = '/login'; - config.logOutPath = '/logOut'; +Installing the Logic Proxy +++++++++++++++++++++++++++ -In addition, it is possible to configure the theme to be used by providing its name. Details about the configuration of -Themes are provided in the *Configuring Themes* section:: +The Logic Proxy sources can be found in `GitHub `__ - config.theme = ''; +The first step for installing the logic proxy component is downloading it and moving to the correct release :: -Additionally, the proxy is the component that acts as the front end of the Business API Ecosystem, both providing a web portal, -and providing the endpoint for accessing to the different APIs. In this regard, the Proxy has to have the OAUth2 configuration -of the FIWARE IDM. + $ git clone https://github.com/FIWARE-TMForum/business-ecosystem-logic-proxy.git + $ cd business-ecosystem-logic-proxy + $ git checkout v7.4.0 -To provide OAUth2 configuration, an application has to be created in an instance of the FIWARE IdM (e.g `https://account.lab.fiware.org`), -providing the following information: +Once the code has been downloaded, Node dependencies can be installed with the provided script as follows :: -* URL: http|https://: -* Callback URL: http|https://:/auth/fiware/callback -* Create a role *Seller* + $ ./install.sh -Once the application has been created in the IdM, it is possible to provide OAuth2 configuration by modifying the following settings :: +Upgrading from 5.4.1 +==================== - config.oauth2 = { - 'server': 'https://account.lab.fiware.org', - 'clientID': '', - 'clientSecret': '', - 'callbackURL': 'http://:/auth/fiware/callback', - 'roles': { - 'admin': 'provider', - 'customer': 'customer', - 'seller': 'seller' - } - }; +For upgrading Business API Ecosystem version 5.4.1 installations to version 7.4.0 a new command has been incorporated +within the *install.py* script. This command downloads new components software, updates it, and migrates the +different databases, so it lets the software ready to be used. -In this settings, it is needed to include the IDM instance being used (*server*), the client id given by the IdM (*clientID*), -the client secret given by the IdM (*clientSecret*), and the callback URL configured in the IdM (*callbackURL*) +.. note:: + It is highly recommended to make a backup of the different databases before upgrading the software -Moreover, the Proxy uses MongoDB for maintaining some info, such as the current shopping cart of a user. you can configure -the connection to MongoDB by updating the following setting: :: +The first step for upgrading the Business API Ecosystem is downloading new version of the main repository in order to +update installation scripts. :: - config.mongoDb = { - server: 'localhost', - port: 27017, - user: '', - password: '', - db: 'belp' - }; + cd Business-API-Ecosystem + git fetch + git checkout v7.4.0 + git pull origin v7.4.0 -In this setting you can configure the host (*server*), the port (*port*), the database user (*user*), the database user password -(*password*), and the database name (*db*). +The new version of *install.py* has a new dependency (PyMSQL) that has to be manually solved in order to execute +the upgrading command. :: -As already stated, the Proxy is the component that acts as the endpoint for accessing the different APIs. In this way, -the proxy needs to know the URLs of them in order to redirect the different requests. This endpoints can be configured using the -following settings :: + $ pip3 install pymysql - config.endpoints = { - 'catalog': { - 'path': 'DSProductCatalog', - 'host': 'localhost' - 'port': '8080', - 'appSsl': false - }, - 'ordering': { - 'path': 'DSProductOrdering', - 'host': 'localhost' - 'port': '8080', - 'appSsl': false - }, +Once the main repository is upgraded, the next step is using the provided script for upgrading the software. :: - ... + $ ./install.py upgrade -The setting *config.endpoints* contains the specific configuration of each of the APIs, including its *path*, its *host*, -its *port*, and whether the API is using SSL or not. +This command do not change your configuration parameters. Nevertheless, you should review the *Configuration* section +as new settings has been included. -.. note:: - The default configuration included in the config file is the one used by the installation script, so if you have used the script for - installing the Business API Ecosystem you do not need to modify these fields +The *upgrade* command uses a set of new commands that have been incorporated within *install.py* in order to manage the +upgrade. In particular: -Finally, there are two fields that allow to configure the behaviour of the system while running. On the one hand, *config.revenueModel* -allows to configure the default percentage that the Business API Ecosystem is going to retrieve in all the transactions. -On the other hand, *config.usageChartURL* allows to configure the URL of the chart to be used to display product usage to -customers in the web portal. +* **download**: Downloads the new software for the different components of the Business API Ecosystem +* **dump**: Creates a dump of the different MySQL databases within */tmp* +* **migrate**: Migrates database contents from v5.4.1 to v7.4.0 ----------- Final steps @@ -937,54 +648,6 @@ You can populate at any time the indexes directory using the *fill_indexes.js* s $ node fill_indexes.js -Configuring Themes -================== - -The Business API Ecosystem provides a basic mechanism for the creation of themes intended to customize the web portal -of the system. Themes include a set of files which can override any of the default portal files located in the *public/resources* -or *views* directories of the logic proxy. To do that, themes map the directory structure and include files with the same -name of the default ones to be overridden. - -The Logic Proxy can include multiple themes which should be stored in the *themes* directory located at the root of the -project. - -To enable themes, the *config.theme* setting is provided within the *config.js* file of the Logic Proxy. Themes are -enabled by providing the name of the theme directory in this setting. :: - - config.theme = 'dark-theme'; - -.. note:: - Setting *config.theme* to an empty string makes the Business API Ecosystem to use its default theme - -To start using a theme the following command has to be executed: :: - - $ node collect_static.js - -This command merges the theme files and the default ones into a *static* directory used by the Logic Proxy to retrieve -portal static files. - -Enabling Production -=================== - -The default installation of the Business API Ecosystem deploys its different components in *debug* mode. This is useful -for development and testing but it is not adequate for production environments. - -Enabling the production mode makes the different components to start caching requests and views and minimizing JavaScript -files. - -To enable the production mode, the first step is setting the environment variable *NODE_ENV* to *production* in the machine -containing the Logic Proxy. :: - - $ export NODE_ENV=production - -Then, it is needed to collect static files in order to compress JavaScript files. :: - - $ node collect_static.js - - -Finally, change the setting *DEBUG* of the Charging Backend to False. :: - - DEBUG=False ---------------------------------- Running the Business API Ecosystem @@ -1039,46 +702,6 @@ Or if you want to start it in background: :: $ nohup node server.js & ------------------------- -Installing Asset Plugins ------------------------- - -The Business API Ecosystem is intended to support the monetization of different kind of digital assets. The different -kind of assets that may be wanted to be monetized will be heterogeneous and potentially very different between them. - -Additionally, for each type of asset different validations and activation mechanisms will be required. For example, if the -asset is a CKAN dataset, it will be required to validate that the provider is the owner of the dataset. Moreover, when a customer -acquires the dataset, it will be required to notify CKAN that a new user has access to it. - -The huge differences between the different types of assets that can be monetized in the Business API Ecosystem makes -impossible to include its validations and characteristics as part of the core software. For this reason, it has been created -a plugin based solution, where all the characteristics of an asset type are implemented in a plugin that can be loaded -in the Business API Ecosystem. - -To include an asset plugin execute the following command in the Charging Backend: :: - - $ ./manage.py loadplugin ckandataset.zip - -It is possible to list the existing plugins with the following command: :: - - $ ./manage.py listplugins - -To remove an asset plugin, execute the following command providing the plugin id given by the *listplugins* command :: - - $ ./manage.py removeplugin ckan-dataset - - -.. note:: - For specific details on how to create a plugin and its internal structure, have a look at the Business API Ecosystem Programmer Guide - -At the time of writing, the following plugins are available: - -* `Basic File `__: Allows the creation of products by providing files as digital assets. No validations or processing is done -* `Basic URL `__: Allows the creation of products by providing URLs as digital assets. No validations or processing is done -* `WireCloud Component `__: Allows the monetization of WireCloud components, including Widgets, operators, and mashups -* `Accountable Service `__ : Allows the monetization of services protected by the `Accounting Proxy `__, including Orion Context Broker queries -* `CKAN Dataset `__ : Allows the monetization of CKAN datasets - ----------------------- Sanity check Procedures diff --git a/doc/plugins-guide.rst b/doc/plugins-guide.rst index 5ee1ebf..d98859a 100644 --- a/doc/plugins-guide.rst +++ b/doc/plugins-guide.rst @@ -2,58 +2,66 @@ Plugins Guide ============= ------------- -Introduction ------------- +This plugins guide covers the available plugins (defining digital asset types) for the Business API Ecosystem v7.4.0 -This plugins guide covers the available plugins (defining digital asset types) for the Business API Ecosystem v6.4.0 -Any feedback on this document is highly welcomed, including bugs, typos or things you think should be included but aren't. -Please send them to the "Contact Person" email that appears in the `Catalogue page for this GEi`_. Or create an issue at `GitHub Issues`_ +------------------------ +Installing Asset Plugins +------------------------ -.. _Catalogue page for this GEi: https://catalogue.fiware.org/enablers/business-api-ecosystem-biz-ecosystem-ri -.. _GitHub Issues: https://github.com/FIWARE-TMForum/Business-API-Ecosystem/issues/new +The Business API Ecosystem is intended to support the monetization of different kind of digital assets. The different +kind of assets that may be wanted to be monetized will be heterogeneous and potentially very different between them. +Additionally, for each type of asset different validations and activation mechanisms will be required. For example, if the +asset is a CKAN dataset, it will be required to validate that the provider is the owner of the dataset. Moreover, when a customer +acquires the dataset, it will be required to notify CKAN that a new user has access to it. ------------------------- -Basic File and Basic URL ------------------------- +The huge differences between the different types of assets that can be monetized in the Business API Ecosystem makes +impossible to include its validations and characteristics as part of the core software. For this reason, it has been created +a plugin based solution, where all the characteristics of an asset type are implemented in a plugin that can be loaded +in the Business API Ecosystem. -The *Basic File* and *Basic URL* plugins are available at `GitHub `__ -These plugins are intended to enable the creation of digital products in the Business API Ecosystem without the need -of specifying a particular type or validation process. In this regard, these plugins allow the publication of any file -or any URL as digital asset respectively, and can be used for the creation of simple file catalogs or for testing the -Business API Ecosystem. +To include an asset plugin execute the following command in the Charging Backend: :: -These plugins do not implement any event handler. + $ ./manage.py loadplugin ckandataset.zip -------------------- -WireCloud Component -------------------- +It is possible to list the existing plugins with the following command: :: -The *WireCloud Component* plugin is available in `GitHub `__. -This plugin defines an asset type intended to manage and monetize the different WireCloud components (Widgets, Operators, -and Mashups) in particular by enabling the creation of product specifications providing the WGT file of the specific -component. (For more details on the WireCloud platform see its documentation in `ReadTheDocs `__) + $ ./manage.py listplugins -The WireCloud component plugin allows to provide the WGT file in the two ways supported by the Business API Ecosystem, -that is, uploading the WGT file when creating the product and providing a URL where the platform can download the file. +To remove an asset plugin, execute the following command providing the plugin id given by the *listplugins* command :: -In addition, the plugin only allows the media type *Mashable application component*. Nevertheless, the plugin code uses the WGT -metainfo to determine the type of the WireCloud component (Widget, Operator, or Mashup) and overrides the media type with the -proper one understood by the WireCloud platform (*wirecloud/widget*, *wirecloud/operator* or *wirecloud/mashup*). + $ ./manage.py removeplugin ckan-dataset -.. image:: ./images/plugin/wirecloud1.png - :align: center -.. image:: ./images/plugin/wirecloud2.png - :align: center +.. note:: + For specific details on how to create a plugin and its internal structure, have a look at the Business API Ecosystem Programmer Guide -This plugin implements the following event handlers: +At the time of writing, the following plugins are available: -* **on_post_product_spec_validation**: In this handler the plugin validates the WGT file to ensure that it is a valid WireCloud Component -* **on_post_product_spec_attachment**: In this handler the plugin determines the media type of the WGT file and overrides the media type value in the specific product specification +* `Basic File `__: Allows the creation of products by providing files as digital assets. No validations or processing is done +* `Basic URL `__: Allows the creation of products by providing URLs as digital assets. No validations or processing is done +* `CKAN Dataset `__ : Allows the monetization of CKAN datasets +* `CKAN API Dataset `__ Allows the monetization of CKAN datasets whose resources are served by an external APIs (e.g NGSI Queries) secured with `API Umbrella `__. +* `Umbrella Service `__ Allows the monetization of services secured by API Umbrella with FIWARE IDM users and roles. +* `WireCloud Component `__: Allows the monetization of WireCloud components, including Widgets, operators, and mashups +* `Accountable Service `__ : Allows the monetization of services protected by the `Accounting Proxy `__, including Orion Context Broker queries + + +----------------- +Available Plugins +----------------- + +Basic File and Basic URL +------------------------ + +The *Basic File* and *Basic URL* plugins are available at `GitHub `__ +These plugins are intended to enable the creation of digital products in the Business API Ecosystem without the need +of specifying a particular type or validation process. In this regard, these plugins allow the publication of any file +or any URL as digital asset respectively, and can be used for the creation of simple file catalogs or for testing the +Business API Ecosystem. + +These plugins do not implement any event handler. ---------------------------------- CKAN Dataset and CKAN API Dataset --------------------------------- @@ -125,17 +133,88 @@ This plugins implements the following event handlers: In addition, the *CKAN API Dataset* requires some settings to be configured before being deployed. This settings are available in the *setting.py* file, and are: -* **AUTH_METHOD**: Authorization mechanism used by the backend service, *idm* or *umbrella* +* **UMBRELLA_SERVER**: Administration endpoint of the API Umbrella instanceused to sercure backend services * **UMBRELLA_KEY**: API Key used for accessing to the API Umbrella instance used to secure the backend service * **UMBRELLA_ADMIN_TOKEN**: Admin token used for accessing to the API Umbrella instance used to secure the backend service * **KEYSTONE_USER**: Keystone user used for authenticate requests to the FIWARE IdM * **KEYSTONE_PASSWORD**: Keystone password used for authenticate requests to the FIWARE IdM * **KEYSTONE_HOST**: Host of the Keystone service of the FIWARE IdM used for authorizing customers +* **IS_LEGACY_IDM**: False if the FIWARE Idm is at least v7.0.0 +* **CKAN_TOKEN_TYPE**: Whether CKAN has to be accessed using X-Auth-Token or Authorization headers + +In addition, these settings can be configured using environment variables: + +* BAE_ASSET_UMBRELLA_SERVER +* BAE_ASSET_UMBRELLA_KEY +* BAE_ASSET_UMBRELLA_TOKEN +* BAE_ASSET_IDM_USER +* BAE_ASSET_IDM_PASSWORD +* BAE_ASSET_IDM_HOST +* BAE_ASSET_LEGACY_IDM +* BAE_ASSET_TOKEN_TYPE + +Umbrella Service +---------------- +The *Umbrella Service* plugin is available in `GitHub `__. +This plugin deines an asset type intended to manage and monetize any HTTP service secured with the combination of a +FIWARE IDM for users and roles management and API Umbrella as PEP proxy. + +The Umbrella Service plugin allows to provide services in different ways using the options it defined in its metadata +form, which can be selected by sellers when registering the product. In particular: + +* **Authorization Method**: Whether user access to backend service is controlled using FIWARE IDM roles or API Umbrella native roles +* **Acquisition Role**: Role to be granted to customers +* **Access to sub-paths allowed**: If true, customers will be able to access to any sub-path of the monetized service +* **Additional query strings allowed**: If true, customers will be able to call the service with different query strings as the included in the asset URL +* **Admin API Key**: API key to be used by the BAE to access to the API Umbrella admin API +* **Admin Auth Token**: Admin token to be used by the BAE to access to the Umbrella admin API + +Moreover, this plugin support pay-per-use pricing supporting the *api call* unit. The accounting information is retrieved +from the API Umbrella logging API using the service details provided as metadata when the product is created. + +This plugin implements the following event handlers: + +* **on_post_product_spec_validation**: In this event handler the plugin validates all the provided information, including URL, Umbrella credentials and role. +* **on_post_product_offering_validation**: In this event handler the plugin validates that the provided procing model is supported by the plugin (Usage model) +* **on_product_acquisition**: In this event handler the plugin grants access to the customer using the provided role +* **on_product_suspension**: In this event handler the plugin revokes access to the customer removing the provided role +* **get_pending_accounting**: In this event handler the plugin accesses Umbrella API to retrieve the pending accounting information + +WireCloud Component ------------------- + +The *WireCloud Component* plugin is available in `GitHub `__. +This plugin defines an asset type intended to manage and monetize the different WireCloud components (Widgets, Operators, +and Mashups) in particular by enabling the creation of product specifications providing the WGT file of the specific +component. (For more details on the WireCloud platform see its documentation in `ReadTheDocs `__) + +The WireCloud component plugin allows to provide the WGT file in the two ways supported by the Business API Ecosystem, +that is, uploading the WGT file when creating the product and providing a URL where the platform can download the file. + +In addition, the plugin only allows the media type *Mashable application component*. Nevertheless, the plugin code uses the WGT +metainfo to determine the type of the WireCloud component (Widget, Operator, or Mashup) and overrides the media type with the +proper one understood by the WireCloud platform (*wirecloud/widget*, *wirecloud/operator* or *wirecloud/mashup*). + +.. image:: ./images/plugin/wirecloud1.png + :align: center + +.. image:: ./images/plugin/wirecloud2.png + :align: center + +This plugin implements the following event handlers: + +* **on_post_product_spec_validation**: In this handler the plugin validates the WGT file to ensure that it is a valid WireCloud Component +* **on_post_product_spec_attachment**: In this handler the plugin determines the media type of the WGT file and overrides the media type value in the specific product specification + + Accountable Service ------------------- +.. warning:: + This plugin is deprecated, and will not evolve. This plugin has been replaced by Umbrella Service Plugin + + The *Accountable Service* plugin is available in `GitHub `__. This plugin defines a generic asset type which is used jointly with the `Accounting Proxy `__ in order to offer services under a pay-per-use model. In particular, this plugin is able to validate services URLs, @@ -177,7 +256,7 @@ Having this software deployed allows service owners to protect their services an without the need of making any modification in the specific service. Installation ------------- +############ This software is a pure NodeJS server, to install basic dependencies execute the following command: :: @@ -285,7 +364,7 @@ the following configuration params are used: } Administration --------------- +############## The Accounting Proxy is able to manage multiple services. In this regard, it has been provided a *cli* tool that can be used by admins in order to register, delete, and manage its services. The available commands are: @@ -359,7 +438,7 @@ To display a brief description of the *cli* tool you can use : `./cli -h` or `./ information for a specific command you can use: `./cli help [cmd]`. Authentication and Authorization --------------------------------- +################################ The Accounting Proxy relies on the FIWARE IdM for authenticating users. To do that, the proxy expects that all the requests include a header *Authorization: Bearer access_token* or *X-Auth-Token: access_token* with a valid access token given @@ -382,7 +461,7 @@ it in a header *X-API-Key: api_key* when making requests, enables it to know wha around the request Proxy API ---------- +######### The Accounting Proxy runs by default in the port 9000; nevertheless, this port can be configured as described in *Configuration* section. In this regard, the different services configured though the administration *cli* tool can be accessed directly @@ -489,7 +568,7 @@ header with a valid access token from the IdM. Accounting modules ------------------- +################## By default, the Accounting Proxy includes three different modules for accounting. Nevertheless, it is possible to extend the proxy with new modules by creating them in the *acc_modules* directory, those modules have to have the following structure: diff --git a/doc/programmer-guide.rst b/doc/programmer-guide.rst index 5588378..3d4b4d1 100644 --- a/doc/programmer-guide.rst +++ b/doc/programmer-guide.rst @@ -2,28 +2,6 @@ Programmer Guide ================ -Introduction -============ - -This programmer guide covers the Business API Ecosystem version 6.4.0, corresponding to FIWARE release 6. -Any feedback on this document is highly welcomed, including bugs, typos or things you think should be included but aren't. -Please send them to the "Contact Person" email that appears in the `Catalogue page for this GEi`_. Or create an issue at `GitHub Issues`_ - -.. _Catalogue page for this GEi: https://catalogue.fiware.org/enablers/business-api-ecosystem-biz-ecosystem-ri -.. _GitHub Issues: https://github.com/FIWARE-TMForum/Business-API-Ecosystem/issues/new - -The Business API Ecosystem allows to offer any kind of digital asset. In this regard, some kind of digital assets may -require to perform specific actions and validations that require to know the format of the asset. To deal with this -issue the Business API Ecosystem allows to register types of assets by creating plugins. This section explains how these plugins are created. - -Additionally, the Business API Ecosystem exposes an API that can be used by developers in order to integrate the monetization -features offered with their own solutions. The complete description of this API can be found in: - - -* `Apiary `__ -* `GitHub Pages `__ - - Plugin Package ============== diff --git a/doc/user-guide.rst b/doc/user-guide.rst index 2181d2c..176cdad 100644 --- a/doc/user-guide.rst +++ b/doc/user-guide.rst @@ -2,24 +2,13 @@ User Guide ========== -Introduction -============ - -This user guide covers the Business API Ecosystem version 6.4.0, corresponding to FIWARE release 6. -Any feedback on this document is highly welcomed, including bugs, typos or things you think should be included but aren't. -Please send them to the "Contact Person" email that appears in the `Catalogue page for this GEi`_. Or create an issue at `GitHub Issues`_ - -.. _Catalogue page for this GEi: https://catalogue.fiware.org/enablers/business-api-ecosystem-biz-ecosystem-ri -.. _GitHub Issues: https://github.com/FIWARE-TMForum/Business-API-Ecosystem/issues/new - - This user guide contains a description of the different tasks that can be performed in the Business API Ecosystem using its web interface. This section is organized so the actions related to a particular user role are grouped together. Using Organizations =================== -Starting on version 6.4.0, the Business API Ecosystem supports organizations as defined by the FIWARE IdM. These organizations +The Business API Ecosystem supports organizations as defined by the FIWARE IdM. These organizations can use the system as if they were users, being possible to create organizations catalogs and offerings or acquire them. To use the platform on behalf an organization the user belongs, it is needed to change the platform context. To do that, diff --git a/docker/README.md b/docker/README.md index 04e8d3f..712ca3f 100644 --- a/docker/README.md +++ b/docker/README.md @@ -3,8 +3,9 @@ The [Business API Ecosystem](https://github.com/FIWARE-TMForum/Business-API-Ecosystem) can be deployed with Docker using two different approaches. On the one hand, for all the components that made up the Business API Ecosystem it has been provided a Docker image that can be used jointly with `docker-compose` in order to deploy and configure the ecosystem. + On the other hand, this repo includes a single Docker image which already includes all the different Business API Ecosystem -modules. +modules. NOTE: THIS OPTION HAS BEEN DEPRECATED, BEING THE LAST VERSION THE 6.4.0 The Business API Ecosystem requires instances of MySQL and MongoDB running. In this regard, you have three possibilities: * You can have your own instances deployed in your machine @@ -27,10 +28,10 @@ There you have to use the following info for registering the app: As stated, it is possible to deploy the Business API Ecosystem using the Docker images available for each of the BAE modules with `docker-compose`. In particular, the following images have to be deployed: -* [biz-ecosystem-apis](https://hub.docker.com/r/conwetlab/biz-ecosystem-apis/): Image including the TMForum APIs -* [biz-ecosystem-rss](https://hub.docker.com/r/conwetlab/biz-ecosystem-rss/): Image Including the RSS module -* [biz-ecosystem-charging-backend](https://hub.docker.com/r/conwetlab/biz-ecosystem-charging-backend/): Image including the charging backend module -* [biz-ecosystem-logic-proxy](https://hub.docker.com/r/conwetlab/biz-ecosystem-logic-proxy/): Image including the logic proxy module +* [biz-ecosystem-apis](https://hub.docker.com/r/fiware/biz-ecosystem-apis/): Image including the TMForum APIs +* [biz-ecosystem-rss](https://hub.docker.com/r/fiware/biz-ecosystem-rss/): Image Including the RSS module +* [biz-ecosystem-charging-backend](https://hub.docker.com/r/fiware/biz-ecosystem-charging-backend/): Image including the charging backend module +* [biz-ecosystem-logic-proxy](https://hub.docker.com/r/fiware/biz-ecosystem-logic-proxy/): Image including the logic proxy module For deploying the BAE using this method the first step is creating a `docker-compose.yml` file with the following contents: @@ -40,18 +41,14 @@ services: mongo: image: mongo:3.2 restart: always - ports: - - 27019:27017 networks: main: volumes: - ./mongo-data:/data/db mysql: - image: mysql:latest + image: mysql:5.7 restart: always - ports: - - 3333:3306 volumes: - ./mysql-data:/var/lib/mysql networks: @@ -61,54 +58,126 @@ services: - MYSQL_DATABASE=RSS charging: - image: conwetlab/biz-ecosystem-charging-backend:develop - restart: always + image: fiware/biz-ecosystem-charging-backend:develop links: - mongo depends_on: - mongo - - apis - - rss - ports: - - 8006:8006 networks: main: aliases: - charging.docker + ports: + - 8006:8006 volumes: + # - ./charging-settings:/business-ecosystem-charging-backend/src/user_settings # Used if the settings files are provided through the volume - ./charging-bills:/business-ecosystem-charging-backend/src/media/bills - ./charging-assets:/business-ecosystem-charging-backend/src/media/assets - ./charging-plugins:/business-ecosystem-charging-backend/src/plugins - - ./charging-settings:/business-ecosystem-charging-backend/src/user_settings - ./charging-inst-plugins:/business-ecosystem-charging-backend/src/wstore/asset_manager/resource_plugins/plugins environment: - - PAYPAL_CLIENT_ID=client_id - - PAYPAL_CLIENT_SECRET=client_secret + - BAE_CB_PAYMENT_METHOD=None # Paypal or None (testing mode payment disconected) + # - BAE_CB_PAYPAL_CLIENT_ID=client_id + # - BAE_CB_PAYPAL_CLIENT_SECRET=client_secret + + # ----- Database configuration ------ + - BAE_CB_MONGO_SERVER=mongo + - BAE_CB_MONGO_PORT=27017 + - BAE_CB_MONGO_DB=charging_db + # - BAE_CB_MONGO_USER=user + # - BAE_CB_MONGO_PASS=passwd + + # ----- Roles Configuration ----- + - BAE_LP_OAUTH2_ADMIN_ROLE=admin + - BAE_LP_OAUTH2_SELLER_ROLE=seller + - BAE_LP_OAUTH2_CUSTOMER_ROLE=customer + + # ----- Email configuration ------ + - BAE_CB_EMAIL=charging@email.com + # - BAE_CB_EMAIL_USER=user + # - BAE_CB_EMAIL_PASS=pass + # - BAE_CB_EMAIL_SMTP_SERVER=smtp.server.com + # - BAE_CB_EMAIL_SMTP_PORT=587 + + - BAE_CB_VERIFY_REQUESTS=True # Whether or not the BAE validates SSL certificates on requests to external components + + # ----- Site configuration ----- + - BAE_SERVICE_HOST=http://proxy.docker:8004/ # External URL used to access the BAE + - BAE_CB_LOCAL_SITE=http://charging.docker:8006/ # Local URL of the charging backend + + # ----- APIs Conection config ----- + - BAE_CB_CATALOG=http://apis.docker:8080/DSProductCatalog + - BAE_CB_INVENTORY=http://apis.docker:8080/DSProductInventory + - BAE_CB_ORDERING=http://apis.docker:8080/DSProductOrdering + - BAE_CB_BILLING=http://apis.docker:8080/DSBillingManagement + - BAE_CB_RSS=http://rss.docker:8080/DSRevenueSharing + - BAE_CB_USAGE=http://apis.docker:8080/DSUsageManagement + - BAE_CB_AUTHORIZE_SERVICE=http://proxy.docker:8004/authorizeService/apiKeys proxy: - image: conwetlab/biz-ecosystem-logic-proxy:develop - restart: always + image: fiware/biz-ecosystem-logic-proxy:develop links: - mongo depends_on: - mongo - - apis - ports: - - 8004:8000 networks: main: aliases: - proxy.docker + ports: + - 8004:8000 volumes: - - ./proxy-conf:/business-ecosystem-logic-proxy/etc + # - ./proxy-conf:/business-ecosystem-logic-proxy/etc # To be used when congiguring the system with a config file provided in the volume - ./proxy-indexes:/business-ecosystem-logic-proxy/indexes - ./proxy-themes:/business-ecosystem-logic-proxy/themes - ./proxy-static:/business-ecosystem-logic-proxy/static + - ./proxy-locales:/business-ecosystem-logic-proxy/locales environment: - - NODE_ENV=production + - NODE_ENV=development # Deployment in development or in production + - COLLECT=True # Execute the collect static command on startup + + - BAE_LP_PORT=8000 # Port where the node service is going to run in the container + - BAE_LP_HOST=proxy.docker # Host where the node service if going to run in the container + # - BAE_SERVICE_HOST=https://store.lab.fiware.org/ # If provided, this URL specifies the actual URL that is used to access the BAE, when the component is proxied (e.g Apache) + # - BAE_LP_HTTPS_ENABLED=true # If provided specifies whether the service is running in HTTPS, default: false + # - BAE_LP_HTTPS_CERT=cert/cert.crt # Certificate for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_CA=cert/ca.crt # CA certificate for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_KEY=cert/key.key # Key sfile for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_PORT=443 # Port where the service runs when SSL is enabled (when HTTPS enabled is true) + + # ------ OAUTH2 Config ------ + - BAE_LP_OAUTH2_SERVER=http://idm.docker:3000 # URL of the FIWARE IDM used for user authentication + - BAE_LP_OAUTH2_CLIENT_ID=e3d43e88-7049-434f-9824-2f0387d9860d # OAuth2 Client ID of the BAE applicaiton + - BAE_LP_OAUTH2_CLIENT_SECRET=06c888d5-a17a-4386-9e26-8ee4f7f77135 # OAuth Client Secret of the BAE application + - BAE_LP_OAUTH2_CALLBACK=http://proxy.docker:8004/auth/fiware/callback # Callback URL for receiving the access tokens + - BAE_LP_OAUTH2_ADMIN_ROLE=admin # Role defined in the IDM client app for admins of the BAE + - BAE_LP_OAUTH2_SELLER_ROLE=seller # Role defined in the IDM client app for sellers of the BAE + - BAE_LP_OAUTH2_CUSTOMER_ROLE=customer # Role defined in the IDM client app for customers of the BAE + - BAE_LP_OAUTH2_ORG_ADMIN_ROLE=orgAdmin # Role defined in the IDM client app for organization admins of the BAE + - BAE_LP_OAUTH2_IS_LEGACY=false # Whether the used FIWARE IDM is version 6 or lower + + # - BAE_LP_THEME=theme # If provided custom theme to be used by the web site, it must be included in themes volume + + # ----- Mongo Config ------ + # - BAE_LP_MONGO_USER=user + # - BAE_LP_MONGO_PASS=pass + - BAE_LP_MONGO_SERVER=mongo + - BAE_LP_MONGO_PORT=27017 + - BAE_LP_MONGO_DB=belp + + - BAE_LP_REVENUE_MODEL=30 # Default market owner precentage for Revenue Sharing models + + # ----- APIs Configuration ----- + # If provided, it supports configuring the contection to the different APIs managed by the logic proxy, by default + # apis.docker, charging.docker and rss.docker domains are configured + # - BAE_LP_ENDPOINT_CATALOG_PATH=DSProductCatalog + # - BAE_LP_ENDPOINT_CATALOG_PORT=8080 + # - BAE_LP_ENDPOINT_CATALOG_HOST=apis.docker + # - BAE_LP_ENDPOINT_CATALOG_SECURED=false + # ... apis: - image: conwetlab/biz-ecosystem-apis:develop + image: fiware/biz-ecosystem-apis:develop restart: always ports: - 4848:4848 @@ -121,12 +190,15 @@ services: main: aliases: - apis.docker + # volumes: + # - ./apis-conf:/etc/default/tmf/ # Used if not configured by environment environment: + - BAE_SERVICE_HOST=http://proxy.docker:8004/ - MYSQL_ROOT_PASSWORD=my-secret-pw - MYSQL_HOST=mysql rss: - image: conwetlab/biz-ecosystem-rss:develop + image: fiware/biz-ecosystem-rss:develop restart: always ports: - 9999:8080 @@ -140,47 +212,50 @@ services: main: aliases: - rss.docker - volumes: - - ./rss-conf:/etc/default/rss + # volumes: + # - ./rss-conf:/etc/default/rss # Used if not configured by environment + environment: + - BAE_RSS_DATABASE_URL=jdbc:mysql://mysql:3306/RSS + - BAE_RSS_DATABASE_USERNAME=root + - BAE_RSS_DATABASE_PASSWORD=my-secret-pw + - BAE_RSS_DATABASE_DRIVERCLASSNAME=com.mysql.jdbc.Driver + - BAE_RSS_OAUTH_CONFIG_GRANTEDROLE=admin + - BAE_RSS_OAUTH_CONFIG_SELLERROLE=seller + - BAE_RSS_OAUTH_CONFIG_AGGREGATORROLE=Aggregator networks: main: external: true + ``` -The next step is providing all the configuration files required by the different components using the configured volumes. -It is possible to find valid configuration files (as well as the `docker-compose.yml`) in the [GitHub repo of the BAE](https://github.com/FIWARE-TMForum/Business-API-Ecosystem) +The next step is providing all the configuration files or environment variables required by the different components. For details +on how to configure the different components please refer to the [BAE Configuration Guide](https://business-api-ecosystem.readthedocs.io/en/develop/configuration-guide.html) -As you can see, the different modules include environment variables and volumes. In particular: +It can be seen that the different images used as part of the Business API Ecosystem provide several volumes. Following +it is descrived the diffent options provided by each image. -**Charging** +The **biz-ecosystem-logic-proxy** image defines 4 volumes. In particular: -The biz-ecosystem-charging-backend needs the following environment variables: -* **PAYPAL_CLIENT_ID**: the client id of your application PayPal credentials used for charging users (a Sandbox account can be used for testing). -* **PAYPAL_CLIENT_SECRET**: the client secret of your application PayPal credentials used for charging users (a Sandbox account can be used for testing). +* */business-ecosystem-logic-proxy/etc*: When file configuration is used, this volume must include the `config.js` file with the software configuration +* */business-ecosystem-logic-proxy/indexes*: This volume contains the indexes used by the Business API Ecosystem for searching +* */business-ecosystem-logic-proxy/themes*: In this volume, it can be provided the themes that can be used to customize the web portal +* */business-ecosystem-logic-proxy/static*: This volume includes the static files ready to be rendered including the selected theme and js files + +Additionally, the **biz-ecosystem-logic-proxy** image defines two environment variables intended to optimize the production deployment of the BAE Logic proxy: -Additionally, the biz-ecosystem-charging-backend image contains 5 volumes. In particular: +* *NODE_ENV*: Specifies whether the system is in *development* or in *production* (default: development) +* *COLLECT*: Specifies if the container should execute the collect static command to generate static files or use the existing on start up (default: True) + +On the other hand, the **biz-ecosystem-charging-backend** image defines 4 volumes. In particular: + +* */business-ecosystem-charging-backend/src/user_settings*: This directory must include the *settings.py* and *services_settings.py* files with the software configuration, when the volume configuration is used. * */business-ecosystem-charging-backend/src/media/bills*: This directory contains the PDF invoices generated by the Business Ecosystem Charging Backend * */business-ecosystem-charging-backend/src/media/assets*: This directory contains the different digital assets uploaded by sellers to the Business Ecosystem Charging Backend * */business-ecosystem-charging-backend/src/plugins*: This directory is used for providing asset plugins (see section *Installing Asset Plugins*) -* */business-ecosystem-charging-backend/src/user_settings*: This directory must include the *settings.py* and *services_settings.py* files with the software configuration. * */business-ecosystem-charging-backend/src/wstore/asset_manager/resource_plugins/plugins*: This directory includes the code of the plugins already installed -**Proxy** - -The biz-ecosystem-logic-proxy image contains 4 volumes. In particular: -* */business-ecosystem-logic-proxy/etc*: This directory must include the `config.js` file with the software configuration -* */business-ecosystem-logic-proxy/indexes*: This directory contains the indexes used by the Business API Ecosystem for searching -* */business-ecosystem-logic-proxy/themes*: This directory contains the themes that can be used to customize the web portal -* */business-ecosystem-logic-proxy/static*: This directory includes the static files ready to be rendered including the selected theme and js files - -Finally, the biz-ecosystem-logic-proxy uses the environment variable *NODE_ENV* to determine if the software is being used -in *development* or in *production* mode. - -> **Note** -> The *config.js* file must include an extra setting not provided by default called *config.extPort* that must include the port where the proxy is going to run in the host machine - Once you have created the files, run the following command: ``` @@ -209,7 +284,9 @@ docker-compose down ### Stand alone Image -In addition, it has been provided a stand alone BAE image which already includes all the modules installed. +THIS OPTION HAS BEEN DEPRECATED, BEING THE LAST VERSION THE 6.4.0 + +It has been provided a stand alone BAE image which already includes all the modules installed. This image can be deployed with `docker-compose` using the following `docker-compose.yml` file: @@ -235,7 +312,7 @@ services: - ./mongo-data:/data/db biz_ecosystem: - image: conwetlab/business-api-ecosystem:develop + image: fiware/business-api-ecosystem:6.4.0 ports: - "8004:8000" links: diff --git a/docker/compose/charging-settings/__init__.py b/docker/compose/charging-settings/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/docker/compose/charging-settings/__init__.pyc b/docker/compose/charging-settings/__init__.pyc deleted file mode 100644 index e9b28bd..0000000 Binary files a/docker/compose/charging-settings/__init__.pyc and /dev/null differ diff --git a/docker/compose/charging-settings/services_settings.py b/docker/compose/charging-settings/services_settings.py deleted file mode 100644 index 27cd493..0000000 --- a/docker/compose/charging-settings/services_settings.py +++ /dev/null @@ -1,14 +0,0 @@ -from __future__ import unicode_literals - -SITE = 'http://proxy.docker:8004/' -LOCAL_SITE = 'http://localhost:8006/' - -CATALOG = 'http://apis.docker:8080/DSProductCatalog' -INVENTORY = 'http://apis.docker:8080/DSProductInventory' -ORDERING = 'http://apis.docker:8080/DSProductOrdering' -BILLING = 'http://apis.docker:8080/DSBillingManagement' -USAGE = 'http://apis.docker:8080/DSUsageManagement' - -RSS = 'http://rss.docker:8080/DSRevenueSharing' - -AUTHORIZE_SERVICE = 'http://proxy.docker:8004/authorizeService/apiKeys' diff --git a/docker/compose/charging-settings/services_settings.pyc b/docker/compose/charging-settings/services_settings.pyc deleted file mode 100644 index 8df856e..0000000 Binary files a/docker/compose/charging-settings/services_settings.pyc and /dev/null differ diff --git a/docker/compose/charging-settings/settings.py b/docker/compose/charging-settings/settings.py deleted file mode 100644 index f45f155..0000000 --- a/docker/compose/charging-settings/settings.py +++ /dev/null @@ -1,142 +0,0 @@ - -from __future__ import unicode_literals - -from os import path - -DEBUG = True -TEMPLATE_DEBUG = DEBUG - -ADMINS = ( - # ('Your Name', 'your_email@example.com'), -) - -MANAGERS = ADMINS - -DATABASES = { - 'default': { - 'ENGINE': 'django_mongodb_engine', # Add 'postgresql_psycopg2', 'mysql', 'sqlite3' or 'oracle'. - 'NAME': 'wstore_db', # Or path to database file if using sqlite3. - 'USER': '', # Not used with sqlite3. - 'PASSWORD': '', # Not used with sqlite3. - 'HOST': 'mongo', # Set to empty string for localhost. Not used with sqlite3. - 'PORT': '', # Set to empty string for default. Not used with sqlite3. - 'TEST_NAME': 'test_database', - } -} - -BASEDIR = "/business-ecosystem-charging-backend/src" - -STORE_NAME = 'WStore' -AUTH_PROFILE_MODULE = 'wstore.models.UserProfile' - -ADMIN_ROLE = 'provider' -PROVIDER_ROLE = 'seller' -CUSTOMER_ROLE = 'customer' - -# Absolute filesystem path to the directory that will hold user-uploaded files. -MEDIA_DIR = 'media/' -MEDIA_ROOT = path.join(BASEDIR, MEDIA_DIR) -BILL_ROOT = path.join(MEDIA_ROOT, 'bills') - -# URL that handles the media served from MEDIA_ROOT. -MEDIA_URL = '/charging/media/' - -INSTALLED_APPS = ( - 'django.contrib.auth', - 'django.contrib.contenttypes', - 'django.contrib.sessions', - 'django.contrib.messages', - 'django.contrib.admin', - 'django_mongodb_engine', - 'djangotoolbox', - 'wstore', - 'wstore.store_commons', - 'wstore.charging_engine', - 'django_crontab', - 'django_nose' -) - -# Make this unique, and don't share it with anybody. -SECRET_KEY = '8p509oqr^68+z)y48_*pv!ceun)gu7)yw6%y9j2^0=o14)jetr' - -TEMPLATE_CONTEXT_PROCESSORS = ( - 'django.contrib.auth.context_processors.auth', - 'django.core.context_processors.debug', - 'django.core.context_processors.i18n', - 'django.core.context_processors.media', - 'django.core.context_processors.request', - 'django.core.context_processors.static', -) - -# List of callables that know how to import templates from various sources. -TEMPLATE_LOADERS = ( - 'django.template.loaders.filesystem.Loader', - 'django.template.loaders.app_directories.Loader', -) - -MIDDLEWARE_CLASSES = ( - 'wstore.store_commons.middleware.URLMiddleware', -) - -WSTOREMAILUSER = 'email_user' -WSTOREMAIL = 'wstore@email.com' -WSTOREMAILPASS = 'wstore_email_passwd' -SMTPSERVER = 'wstore_smtp_server' -SMTPPORT = 587 - -URL_MIDDLEWARE_CLASSES = { - 'default': ( - 'django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'wstore.store_commons.middleware.ConditionalGetMiddleware', - 'django.contrib.auth.middleware.AuthenticationMiddleware', - 'django.contrib.messages.middleware.MessageMiddleware', - ), - 'api': ( - 'django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'wstore.store_commons.middleware.ConditionalGetMiddleware', - 'wstore.store_commons.middleware.AuthenticationMiddleware', - ), - 'media': ( - 'django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'wstore.store_commons.middleware.ConditionalGetMiddleware', - 'wstore.store_commons.middleware.AuthenticationMiddleware', - ) -} - -ROOT_URLCONF = 'urls' - -# Python dotted path to the WSGI application used by Django's runserver. -WSGI_APPLICATION = 'wsgi.application' - -# Payment method determines the payment gateway to be used -# Allowed values: paypal (default), fipay, None -PAYMENT_METHOD = 'paypal' - -AUTHENTICATION_BACKENDS = ( - 'django.contrib.auth.backends.ModelBackend', -) - -TEST_RUNNER = 'django_nose.NoseTestSuiteRunner' - -# Daily job that checks pending pay-per-use charges -CRONJOBS = [ - ('0 5 * * *', 'django.core.management.call_command', ['pending_charges_daemon']), - ('0 6 * * *', 'django.core.management.call_command', ['resend_cdrs']), - ('0 4 * * *', 'django.core.management.call_command', ['resend_upgrade']) -] - -CLIENTS = { - 'paypal': 'wstore.charging_engine.payment_client.paypal_client.PayPalClient', - 'fipay': 'wstore.charging_engine.payment_client.fipay_client.FiPayClient', - None: 'wstore.charging_engine.payment_client.payment_client.PaymentClient' -} - -PAYMENT_CLIENT = CLIENTS[PAYMENT_METHOD] - -NOTIF_CERT_FILE = None -NOTIF_CERT_KEY_FILE = None - -from .services_settings import * diff --git a/docker/compose/charging-settings/settings.pyc b/docker/compose/charging-settings/settings.pyc deleted file mode 100644 index 7e9fe29..0000000 Binary files a/docker/compose/charging-settings/settings.pyc and /dev/null differ diff --git a/docker/compose/docker-compose.yml b/docker/compose/docker-compose.yml index 845b94f..4391657 100644 --- a/docker/compose/docker-compose.yml +++ b/docker/compose/docker-compose.yml @@ -3,18 +3,14 @@ services: mongo: image: mongo:3.2 restart: always - ports: - - 27017:27017 networks: main: volumes: - ./mongo-data:/data/db mysql: - image: mysql:latest + image: mysql:5.7 restart: always - ports: - - 3333:3306 volumes: - ./mysql-data:/var/lib/mysql networks: @@ -24,54 +20,126 @@ services: - MYSQL_DATABASE=RSS charging: - image: conwetlab/biz-ecosystem-charging-backend:develop - restart: always + image: fiware/biz-ecosystem-charging-backend:develop links: - mongo depends_on: - mongo - - apis - - rss - ports: - - 8006:8006 networks: main: aliases: - charging.docker + ports: + - 8006:8006 volumes: + # - ./charging-settings:/business-ecosystem-charging-backend/src/user_settings # Used if the settings files are provided through the volume - ./charging-bills:/business-ecosystem-charging-backend/src/media/bills - ./charging-assets:/business-ecosystem-charging-backend/src/media/assets - ./charging-plugins:/business-ecosystem-charging-backend/src/plugins - - ./charging-settings:/business-ecosystem-charging-backend/src/user_settings - ./charging-inst-plugins:/business-ecosystem-charging-backend/src/wstore/asset_manager/resource_plugins/plugins environment: - - PAYPAL_CLIENT_ID=client_id - - PAYPAL_CLIENT_SECRET=client_secret + - BAE_CB_PAYMENT_METHOD=None # Paypal or None (testing mode payment disconected) + # - BAE_CB_PAYPAL_CLIENT_ID=client_id + # - BAE_CB_PAYPAL_CLIENT_SECRET=client_secret + + # ----- Database configuration ------ + - BAE_CB_MONGO_SERVER=mongo + - BAE_CB_MONGO_PORT=27017 + - BAE_CB_MONGO_DB=charging_db + # - BAE_CB_MONGO_USER=user + # - BAE_CB_MONGO_PASS=passwd + + # ----- Roles Configuration ----- + - BAE_LP_OAUTH2_ADMIN_ROLE=admin + - BAE_LP_OAUTH2_SELLER_ROLE=seller + - BAE_LP_OAUTH2_CUSTOMER_ROLE=customer + + # ----- Email configuration ------ + - BAE_CB_EMAIL=charging@email.com + # - BAE_CB_EMAIL_USER=user + # - BAE_CB_EMAIL_PASS=pass + # - BAE_CB_EMAIL_SMTP_SERVER=smtp.server.com + # - BAE_CB_EMAIL_SMTP_PORT=587 + + - BAE_CB_VERIFY_REQUESTS=True # Whether or not the BAE validates SSL certificates on requests to external components + + # ----- Site configuration ----- + - BAE_SERVICE_HOST=http://proxy.docker:8004/ # External URL used to access the BAE + - BAE_CB_LOCAL_SITE=http://charging.docker:8006/ # Local URL of the charging backend + + # ----- APIs Conection config ----- + - BAE_CB_CATALOG=http://apis.docker:8080/DSProductCatalog + - BAE_CB_INVENTORY=http://apis.docker:8080/DSProductInventory + - BAE_CB_ORDERING=http://apis.docker:8080/DSProductOrdering + - BAE_CB_BILLING=http://apis.docker:8080/DSBillingManagement + - BAE_CB_RSS=http://rss.docker:8080/DSRevenueSharing + - BAE_CB_USAGE=http://apis.docker:8080/DSUsageManagement + - BAE_CB_AUTHORIZE_SERVICE=http://proxy.docker:8004/authorizeService/apiKeys proxy: - image: conwetlab/biz-ecosystem-logic-proxy:develop - restart: always + image: fiware/biz-ecosystem-logic-proxy:develop links: - mongo depends_on: - mongo - - apis - ports: - - 8004:8000 networks: main: aliases: - proxy.docker + ports: + - 8004:8000 volumes: - - ./proxy-conf:/business-ecosystem-logic-proxy/etc + # - ./proxy-conf:/business-ecosystem-logic-proxy/etc # To be used when congiguring the system with a config file provided in the volume - ./proxy-indexes:/business-ecosystem-logic-proxy/indexes - ./proxy-themes:/business-ecosystem-logic-proxy/themes - ./proxy-static:/business-ecosystem-logic-proxy/static + - ./proxy-locales:/business-ecosystem-logic-proxy/locales environment: - - NODE_ENV=development + - NODE_ENV=development # Deployment in development or in production + - COLLECT=True # Execute the collect static command on startup + + - BAE_LP_PORT=8000 # Port where the node service is going to run in the container + - BAE_LP_HOST=proxy.docker # Host where the node service if going to run in the container + # - BAE_SERVICE_HOST=https://store.lab.fiware.org/ # If provided, this URL specifies the actual URL that is used to access the BAE, when the component is proxied (e.g Apache) + # - BAE_LP_HTTPS_ENABLED=true # If provided specifies whether the service is running in HTTPS, default: false + # - BAE_LP_HTTPS_CERT=cert/cert.crt # Certificate for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_CA=cert/ca.crt # CA certificate for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_KEY=cert/key.key # Key sfile for the SSL configuration (when HTTPS enabled is true) + # - BAE_LP_HTTPS_PORT=443 # Port where the service runs when SSL is enabled (when HTTPS enabled is true) + + # ------ OAUTH2 Config ------ + - BAE_LP_OAUTH2_SERVER=http://idm.docker:3000 # URL of the FIWARE IDM used for user authentication + - BAE_LP_OAUTH2_CLIENT_ID=e3d43e88-7049-434f-9824-2f0387d9860d # OAuth2 Client ID of the BAE applicaiton + - BAE_LP_OAUTH2_CLIENT_SECRET=06c888d5-a17a-4386-9e26-8ee4f7f77135 # OAuth Client Secret of the BAE application + - BAE_LP_OAUTH2_CALLBACK=http://proxy.docker:8004/auth/fiware/callback # Callback URL for receiving the access tokens + - BAE_LP_OAUTH2_ADMIN_ROLE=admin # Role defined in the IDM client app for admins of the BAE + - BAE_LP_OAUTH2_SELLER_ROLE=seller # Role defined in the IDM client app for sellers of the BAE + - BAE_LP_OAUTH2_CUSTOMER_ROLE=customer # Role defined in the IDM client app for customers of the BAE + - BAE_LP_OAUTH2_ORG_ADMIN_ROLE=orgAdmin # Role defined in the IDM client app for organization admins of the BAE + - BAE_LP_OAUTH2_IS_LEGACY=false # Whether the used FIWARE IDM is version 6 or lower + + # - BAE_LP_THEME=theme # If provided custom theme to be used by the web site, it must be included in themes volume + + # ----- Mongo Config ------ + # - BAE_LP_MONGO_USER=user + # - BAE_LP_MONGO_PASS=pass + - BAE_LP_MONGO_SERVER=mongo + - BAE_LP_MONGO_PORT=27017 + - BAE_LP_MONGO_DB=belp + + - BAE_LP_REVENUE_MODEL=30 # Default market owner precentage for Revenue Sharing models + + # ----- APIs Configuration ----- + # If provided, it supports configuring the contection to the different APIs managed by the logic proxy, by default + # apis.docker, charging.docker and rss.docker domains are configured + # - BAE_LP_ENDPOINT_CATALOG_PATH=DSProductCatalog + # - BAE_LP_ENDPOINT_CATALOG_PORT=8080 + # - BAE_LP_ENDPOINT_CATALOG_HOST=apis.docker + # - BAE_LP_ENDPOINT_CATALOG_SECURED=false + # ... apis: - image: conwetlab/biz-ecosystem-apis:develop + image: fiware/biz-ecosystem-apis:develop restart: always ports: - 4848:4848 @@ -84,12 +152,15 @@ services: main: aliases: - apis.docker + # volumes: + # - ./apis-conf:/etc/default/tmf/ # Used if not configured by environment environment: + - BAE_SERVICE_HOST=http://proxy.docker:8004/ - MYSQL_ROOT_PASSWORD=my-secret-pw - MYSQL_HOST=mysql rss: - image: conwetlab/biz-ecosystem-rss:develop + image: fiware/biz-ecosystem-rss:develop restart: always ports: - 9999:8080 @@ -103,8 +174,16 @@ services: main: aliases: - rss.docker - volumes: - - ./rss-conf:/etc/default/rss + # volumes: + # - ./rss-conf:/etc/default/rss # Used if not configured by environment + environment: + - BAE_RSS_DATABASE_URL=jdbc:mysql://mysql:3306/RSS + - BAE_RSS_DATABASE_USERNAME=root + - BAE_RSS_DATABASE_PASSWORD=my-secret-pw + - BAE_RSS_DATABASE_DRIVERCLASSNAME=com.mysql.jdbc.Driver + - BAE_RSS_OAUTH_CONFIG_GRANTEDROLE=admin + - BAE_RSS_OAUTH_CONFIG_SELLERROLE=seller + - BAE_RSS_OAUTH_CONFIG_AGGREGATORROLE=Aggregator networks: main: diff --git a/docker/compose/proxy-conf/config.js b/docker/compose/proxy-conf/config.js deleted file mode 100644 index 07bfd36..0000000 --- a/docker/compose/proxy-conf/config.js +++ /dev/null @@ -1,139 +0,0 @@ -var config = {}; - -// Version of the software -config.version = { - version: '6.3.0-rc', - releaseDate: '', - gitHash: '', - doc: 'https://fiware-tmforum.github.io/Business-API-Ecosystem/', - userDoc: 'http://business-api-ecosystem.readthedocs.io/en/develop' -}; - -// The PORT used by -config.port = 8000; -config.host = 'proxy.docker'; - -config.extPort = 8004; - -// Set this var to undefined if you don't want the server to listen on HTTPS -config.https = { - enabled: false, - certFile: 'cert/cert.crt', - keyFile: 'cert/key.key', - caFile: 'cert/ca.crt', - port: 443 -}; - -// Express configuration -config.proxyPrefix = ''; -config.portalPrefix = ''; -config.logInPath = '/login'; -config.logOutPath = '/logOut'; -config.sessionSecret = 'keyboard cat'; -config.theme = ''; - -// OAuth2 configuration -config.oauth2 = { - 'server': 'http://idm.docker:8000/', - 'clientID': '72915972396741ddbd2f810783bcc94a', - 'clientSecret': '3555076ff5624d2a8daf064967273b60', - 'callbackURL': 'http://proxy.docker:8004/auth/fiware/callback', - 'roles': { - 'admin': 'provider', - 'customer': 'customer', - 'seller': 'seller', - 'orgAdmin': 'orgAdmin' - } -}; - -// Customer Role Required to buy items -config.customerRoleRequired = false; - -// MongoDB -config.mongoDb = { - server: 'mongo', - port: 27017, - user: '', - password: '', - db: 'belp' -}; - -// Configure endpoints -config.endpoints = { - 'management': { - 'path': 'management', - 'host': 'localhost', - 'port': config.port, - 'appSsl': config.https.enabled - }, - 'catalog': { - 'path': 'DSProductCatalog', - 'host': 'apis.docker', - 'port': '8080', - 'appSsl': false - }, - 'ordering': { - 'path': 'DSProductOrdering', - 'host': 'apis.docker', - 'port': '8080', - 'appSsl': false - }, - 'inventory': { - 'path': 'DSProductInventory', - 'host': 'apis.docker', - 'port': '8080', - 'appSsl': false - }, - 'charging': { - 'path': 'charging', - 'host': 'charging.docker', - 'port': '8006', - 'appSsl': false - }, - 'rss': { - 'path': 'DSRevenueSharing', - 'host': 'rss.docker', - 'port': '8080', - 'appSsl': false - }, - 'party': { - 'path': 'DSPartyManagement', - 'host': 'apis.docker', - 'port': '8080', - 'appSsl': false - }, - 'billing':{ - 'path': 'DSBillingManagement', - 'host': 'apis.docker', - 'port': '8080', - 'appSsl': false - }, - 'customer': { - 'path': 'DSCustomerManagement', - 'host': 'apis.docker', - 'port': '8080', - 'appSsl': false - }, - 'usage': { - 'path': 'DSUsageManagement', - 'host': 'apis.docker', - 'port': '8080', - 'appSsl': false - } -}; - -// Percentage of the generated revenues that belongs to the system -config.revenueModel = 30; - -// Billing Account owner role -config.billingAccountOwnerRole = 'bill receiver'; - -// list of paths that will not check authentication/authorization -// example: ['/public/*', '/static/css/'] -config.publicPaths = []; - -config.magicKey = undefined; - -config.usageChartURL = 'https://mashup.lab.fiware.org/fdelavega/UsageChart?mode=embedded&theme=wirecloud.fiwarelabtheme'; - -module.exports = config; diff --git a/docker/compose/rss-conf/database.properties b/docker/compose/rss-conf/database.properties deleted file mode 100644 index 039bc3e..0000000 --- a/docker/compose/rss-conf/database.properties +++ /dev/null @@ -1,4 +0,0 @@ -database.url=jdbc:mysql://mysql:3306/RSS -database.username=root -database.password=my-secret-pw -database.driverClassName=com.mysql.jdbc.Driver \ No newline at end of file diff --git a/docker/compose/rss-conf/oauth.properties b/docker/compose/rss-conf/oauth.properties deleted file mode 100644 index 2bc7c73..0000000 --- a/docker/compose/rss-conf/oauth.properties +++ /dev/null @@ -1,4 +0,0 @@ -############## IDM configuration ################ -config.grantedRole=Provider -config.sellerRole=Seller -config.aggregatorRole=aggregator \ No newline at end of file diff --git a/docker/single/conf/proxy/config.js b/docker/single/conf/proxy/config.js index b421fc0..214af26 100644 --- a/docker/single/conf/proxy/config.js +++ b/docker/single/conf/proxy/config.js @@ -2,7 +2,7 @@ var config = {}; // Version of the software config.version = { - version: '6.4.0-rc', + version: '7.4.0-rc', releaseDate: '', gitHash: '', doc: 'https://fiware-tmforum.github.io/Business-API-Ecosystem/', diff --git a/install.py b/install.py index e47d499..ac6468c 100755 --- a/install.py +++ b/install.py @@ -13,49 +13,49 @@ DBPORT = 3306 APIS = [{"url": "https://github.com/FIWARE-TMForum/DSPRODUCTCATALOG2.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "DSPRODUCTCATALOG2", "war": "target/DSProductCatalog.war", "root": "DSProductCatalog", "name": "catalog", "resourcename": "jdbc/pcatv2"}, {"url": "https://github.com/FIWARE-TMForum/DSPRODUCTORDERING.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "DSPRODUCTORDERING", "war": "target/DSProductOrdering.war", "root": "DSProductOrdering", "name": "ordering", "resourcename": "jdbc/podbv2"}, {"url": "https://github.com/FIWARE-TMForum/DSPRODUCTINVENTORY.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "DSPRODUCTINVENTORY", "war": "target/DSProductInventory.war", "root": "DSProductInventory", "name": "inventory", "resourcename": "jdbc/pidbv2"}, {"url": "https://github.com/FIWARE-TMForum/DSPARTYMANAGEMENT.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "DSPARTYMANAGEMENT", "war": "target/DSPartyManagement.war", "root": "DSPartyManagement", "name": "party", "resourcename": "jdbc/partydb"}, {"url": "https://github.com/FIWARE-TMForum/DSBILLINGMANAGEMENT.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "DSBILLINGMANAGEMENT", "war": "target/DSBillingManagement.war", "root": "DSBillingManagement", "name": "billing", "resourcename": "jdbc/bmdbv2"}, {"url": "https://github.com/FIWARE-TMForum/DSCUSTOMER.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "DSCUSTOMER", "war": "target/DSCustomerManagement.war", "root": "DSCustomerManagement", "name": "customer", "resourcename": "jdbc/customerdbv2"}, {"url": "https://github.com/FIWARE-TMForum/DSUSAGEMANAGEMENT.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "DSUSAGEMANAGEMENT", "war": "target/DSUsageManagement.war", "root": "DSUsageManagement", @@ -63,18 +63,18 @@ "resourcename": "jdbc/usagedbv2"}] rss = {"url": "https://github.com/FIWARE-TMForum/business-ecosystem-rss.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "bbdd": "RSS", "war": "fiware-rss/target/DSRevenueSharing.war", "name": "rss", "root": "DSRevenueSharing"} charg = {"url": "https://github.com/FIWARE-TMForum/business-ecosystem-charging-backend.git", - "branch": "v6.4.0", + "branch": "v7.4.0", "name": "charging"} proxy = {"url": "https://github.com/FIWARE-TMForum/business-ecosystem-logic-proxy.git", - "branch": "v6.4.0"} + "branch": "v7.4.0"} @click.group(chain=True) @@ -462,7 +462,7 @@ def migrate(): @cli.command("upgrade") @click.pass_context def upgrade(ctx): - print("Upgrading from version 5.4.1 to 6.4.0") + print("Upgrading from version 5.4.1 to 7.4.0") ctx.invoke(download) ctx.invoke(maveninstall)