============ Introduction ============ ---------------------- Architectural Overview ---------------------- EDP runs on the cloud or on-premise servers, and assumes a client installed on the edge. This EDP client is a bundle that for most of its functionality relies on an underlying OSGi framework [#f1]_. The framework needs to be installed on edge devices, and is capable of running on various combinations of hardware architectures and operating systems, referred to here as *runtimes*. .. figure:: ./image/image1.png :align: center :alt: intro image OSGi Framework and EDP Client run on devices The EDP Client currently runs on the OSGi framework implementations JamaicaAMS, Apache Felix, Apache Karaf, and Eclipse Equinox. It is through the EDP Client that the connection is established: The client creates a connection between the runtime and the web portal; EDP extends the connection to the server or to the cloud. Basic information, like the runtime's architecture and environment, is stored and is then available to be reported to the system even when it is offline. On the frontend, EDP runs on desktops, laptops and a variety of mobile devices, supporting all major Chromium based browsers. As a bridge between the edge and the cloud, EDP currently uses AWS' services and data storage structures. To run EDP it is necessary that the runtimes to be managed are powered with an OSGi framework and the EDP Client. The EDP Client is available for download directly from the EDP web portal. Once you select **Runtimes** from the main menu, the ``Get Client`` option is located at the **Runtime Group Home**. Section :doc:`Connecting Devices <./connecting-devices>` presents, as an example, step by step instructions on how to establish a connection between a Raspberry Pi and EDP. JamaicaAMS and Apache Felix are both used as examples of OSGi frameworks. .. admonition:: Core Concepts :class: my-custom-note For an efficient usage of EDP, please consider how *aicas* defines its central components: - **Runtimes**: runtimes are elements managed as Things in AWS and can be used as deployment targets. The concept extends the term "devices". While device just describes the physical hardware, here we understand the combination of hardware, OS and OSGi framework. For example, if we have one Raspberry Pi running a certain version of *JamaicaAMS*, one other powered with another version of *JamaicaAMS* and yet another Pi running a version of Apache Felix, we have three different runtimes. On the other hand, I can run multiple runtimes on one single laptop, like multiple instances of an OSGi framework. - **Runtime Group**: this is a hierarchical group of runtimes and runtime groups. Runtime groups can also be seen as a deployment target. However, installations are to be made in each of the runtimes the group contains. - **Fleet**: This is also a collection of runtime groups and runtimes. The members of a fleet are not added statically, but determined dynamically via properties. If a runtime group is included in a fleet, the entire hierarchy of that group is also included. Fleets can also be a deployment target. However, installations are made to the runtime groups and runtimes they contain. - **Bundle**: An OSGi (Open Services Gateway Initiative) bundle is a tightly-coupled, dynamically loadable collection of Java classes, resources and dependencies that, together, provide certain functionality and adhere to OSGi specifications. - **Feature**: A distinct piece of functionality that delivers value to the user. In EDP, features are conceived as a hierarchical group of bundles and features. Features can be deployed to runtimes, runtime groups, or fleets. - **Artifacts**: A deployable unit of software, in EDP's case combining versions of bundles and features. The JAR file contains compiled Java code, metadata, and resources, specifically formatted to work within the OSGi runtime environment. -------------- User Interface -------------- Once a user is registered, it is then time to sign into the EDP account [#f2]_. A password for the first login is provided by a system administrator, and users are advised to change them. It is recommended to always choose strong passwords, avoid sharing them and change them periodically. At this point it should be ensured that the new user is granted the necessary permissions to perform the desired tasks. In EDP, permission levels and roles are defined in the web portal by administrators, that also associate users to one or more of three available environments: **develop**, **staging** and **release**. More information about users' management and the assignment of roles and permissions are given :doc:`here <./roles-and-permissions>`. In its navigation menu, EDP offers functionality to remotely manage single runtimes and runtime groups by installing, uninstalling, starting and stopping bundles and features. Choosing **Features** or **Runtimes** will open a list of the available features, single bundles, runtimes and runtime groups: those components can be searched, filtered, inspected and remotely managed. The main menu also offers the option **Fleets**. Here, users can create new fleets, search and and inspect existing ones, viewing which runtimes and runtime groups it contains. In this area fleets can be deleted and have their metadata edited. To a fleet users can also allocate jobs, which on the other hand can be uploaded, selected or deleted by choosing the menu option **Job Documents**. The option **Deployments** serves as support for creating and managing deployments of EDP from a specific source (feature version of an artifact) to a target, that can be a runtime or a runtime group. Finally, the menu also offers features related to the creation of **Bundle Pipelines**, a workflow hub that administrates how bundles and features are triggered and transitioned in EDP, which are covered :doc:`here <./managing-pipelines>`. .. figure:: ./image/intro-image2.png :alt: EDP main menu :target: ./_static/intro-image2.png :width: 600px :align: center EDP Navigation, Help and Settings. **Open in new tab to see full-size image**. .. Users will notice that, placed at the bottom of the main menu, there is a ``Help`` button .. that allows to access the link to the online Usage Manual. ------------------------------ Organizations and Environments ------------------------------ EDP differentiates access to data and functionality based on two scopes of resources: organizations and environments. Available to each organization, there are three predefined environments (marked in red in the image above): *Develop* : for the development of new applications, *Staging* : for QA testing of release candidates, *Release* : for application releases that are approved to run on production devices. EDP considers an organization as an isolated, independent unit of the portal. Each organization has its own set of runtimes, bundles, features, users, and resources. Functionality and views, like lists of bundles and runtimes, are clustered around the three mentioned environments, designed to support the continuous development, deployment and set to production of OSGi compatible applications. .. figure:: ./image/intro-image3.png :align: center :alt: intro image Organizations as independent units Depending on the permissions they are granted, users have access rights to the different environments. Permissions are issued by an administrator and should reflect users’ roles in the organizations, e.g. as developers or QA engineers. The **develop** environment is for software developers who are working on new features, or new versions of existing features. It contains intermediate bundle artifacts that are not tested yet and can be deployed in prototyping devices. This environment accepts work in progress builds, usually called “snapshots”. That means, a developer can upload versions of a same application or features as many times as it is required, and the portal will handle them correctly, using the latest version when deployment to a runtime is requested. **Develop** is the entry point for bundles, which are only uploaded in this environment. When the developer considers the work ready, the final version of the feature is released to the “Staging” environment, generally through the workflow defined in a bundle pipeline. **Staging** is for stabilization processes and targeted at Quality Assurance teams, who use this environment and the runtimes assigned to it for testing. This environment should only contain final versions of bundles and features, which cannot be changed. After all checks are done, the tested artifact is either rejected or approved and transferred to the **release** environment, that should only contain successfully tested features and runtimes suitable to be used in production. -------- Settings -------- The following image illustrates the relationship between user roles and environments. .. figure:: ./image/pic1.png :align: center :alt: roles and environments image User roles define access to environments Administrators and users with extended rights are the ones able to access settings, which permit to change the UI and manage user roles and privileges. The **Settings** menu offers the possibility to adapt the graphical interface (**Preferences** and **Icons**), manage **Users**, **Roles and Privileges**, view **Permissions**,set **Jara Targets** for bundle acceleration and generate **Maven tokens** for direct uploads. Preferences allows to change the organization’s name and logo, and also the display theme. Icons for bundles and runtimes can be changed. Simply go to the **Settings** menu option Icons to upload and delete icons. To change an icon, navigate to **Runtimes** or **Features**, select an item and hover over the existing icon in the details area: an edit button will appear. Click it and select the icon that you have uploaded. .. figure:: ./image/EDP-settings.png :alt: Settings menu :target: ./_static/EDP-settings.png :width: 600px :align: center Access Settings for preferences and permissions. **Open in new tab to see full-size image**. :doc:`← Previous Page ` | :doc:`Next Page → ` .. rubric:: Footnotes .. [#f1] At least compatible with Release 8. .. [#f2] The link to the portal is customer-specific, its URL depending on where the customer has deployed EDP.