From b6e18ab5ac873b9cf8d030f156e095a31601aa67 Mon Sep 17 00:00:00 2001 From: Antonio Terceiro Date: Thu, 18 May 2017 17:07:25 -0300 Subject: [PATCH] content/04-architecture.tex: review --- opensym2017/content/04-architecture.tex | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------------------------------------------------------------------- 1 file changed, 96 insertions(+), 86 deletions(-) diff --git a/opensym2017/content/04-architecture.tex b/opensym2017/content/04-architecture.tex index da0bc8c..62106d7 100644 --- a/opensym2017/content/04-architecture.tex +++ b/opensym2017/content/04-architecture.tex @@ -1,14 +1,16 @@ \section{Architecture} \label{sec:architecture} -Based on the great list of functional requirements desired by Brazilian Federal -Government we decided to select some FOSS systems that already contemplate some -of them and improve these systems. And bringing the idea of community, it is -undoable build a platform to be used by communities, which is a complex -scenario, using just one tool. +Based on the extensive list of functional requirements defined by the +Brazilian Federal Government, we selected some FOSS systems to form our +solution. We looked for system that together could provide the largest +subset possible of the requirements, and were fully aware that we would +need to improve those systems in order to provide the rest. We were also +convinced that it would be impossible to provide all of those +requirements with a single tool. -At the point of view of the architecture, two main requirements was brought by -the Brazilian Federal Government for the new platform: +From the point of view of the architecture, two main requirements was +brought by the Brazilian Federal Government for the new platform: \begin{enumerate} \item \textit{Integrate existing FOSS systems}, with minimal differences from @@ -17,69 +19,81 @@ the Brazilian Federal Government for the new platform: systems, as well as centralized authentication. \end{enumerate} -Adopting existing FOSS systems by the government could bring the benefit of -improvements done by the upstream communities, and the maintenance effort. On -the other hand, integrating different tools with distinct intent, it is not an -easy task and it was important to have a consistent user interface which -justifies the last requirement. +Adopting existing FOSS systems and minimizing locally-made changes had +the objective of being able to upgrade to newer versions of the original +software, benefiting from improvements and maintenance done by the +existing project communities. Providing a consistent user interface on +top of those different tools was needed to make the transition between +the different systems seamless from the point of view of users, which +would be confused by jumping through completely different interfaces +while interacting with the portal. For the first requirement, we identified four main systems that required -specialized teams for work in the integration process. The teams learned how to -develop for their assigned systems and contributed to the original -communities, so that the version we used were not significantly different from -the original. +specialized teams for work in the integration process. The teams learned +how to develop for their assigned systems and contributed to the +original communities, so that the version we used were not significantly +different from the original. -At the end of the project, SPB portal was composed of more than ten systems -among them we can highlight: Colab, Noosfero, Mezuro, Gitlab, Mailman, Postfix, -Munin, and so forth. The following sections explained a little bit of Colab, -Noosfero, Mezuro, and Gitlab (the main tools which we contributed). Below, we -described how we integrated those tools and conclude with the deployment. +At the end of the project, the SPB portal was composed of more than ten +systems, such as Colab, Noosfero, Mezuro, Gitlab, Mailman, Postfix, and +Munin. The remainder of this section describes the most relevant of +them, as well as how they were integrated into the platform. \subsection{Colab} -Colab integrates web applications as its main goal, the user of this composed -system should not notice the change between the integrated applications. Colab -was designed to use one plugin for each system under its domain, this is -guaranteed by four levels of integration: +Colab\footnote{\url{https://github.com/colab}} is a systems integration +platform for web applications. One of its goals is allowing different +applications to be combined in such a way that an user does not notice +the change between applications. For that, Colab provides facilities +for: \begin{itemize} - \item Authentication - \item Visual - \item Events - \item Data and search engine + \item Centralized authentication + \item Visual consistency + \item Relaying of events between applications + \item Integrated search engine \end{itemize} -The aforementioned integrations levels were possible, because Colab works as a -reverse proxy, therefore all external requests pass through it. - -Single Sign-On (SSO) is used to login users throughout all integrated -applications. REMOTE\_USER HTTP header is sent to the applications and we -expect that they know how to handle it, since this is a common authentication -mechanism. The integrated applications should be on a local network to avoid -security issues. With this the user will be able to navigate through the -platform applications and will not be asked for authentication credentials. - -As Colab\footnote{\url{https://github.com/colab}} is a reverse proxy, it makes -some HTML transformations in the HTTP response of integrated applications to -provide a unified interface. Allows one to define some default templates to be -used by all applications and overwrite when needed in its plugin. This approach -allowed us to reuse some HTML pages which facilitates maintenance. - -A publish-subscribe implementation was used to handle events in the platform. -Thus, if some application want to trigger some action in case that other -application do something is possible. A registration of the desired events and -implementation of the handlers must be done in the plugin of each application. -This bring us many options to innovate in these integrations. - -A integrated search engine is provided by Colab. Each plugin specify which data -will be indexed and will became available for the users, just need an simple -implementation of how should perform the collection of data. +Colab implements this integration by working as a reverse proxy for the +integration applications, that is, all external requests pass through +Colab before reaching them. + +Centralized authentication is handled by letting users authenticate to +Colab, which then sends a REMOTE\_USER HTTP header to applications, +which are expected to be pre-configured to accept that as an indication +of the current user (REMOTE\_USER is a standard authentication mechanism +for web applications). This allows users to be automatically identified +to each of the applications without having to enter credentials for each +of them. +% +Of course, this requires that the integrated applications are not +accessible on the public internet, otherwise malicious users could send +their own crafted REMOTE\_USER headers and impersonate any user. + +For the visual consistency, Colab is able to make transformations to the +HTML produced by the integrated applications, ir order to provide a +unified interface. It allows one to define default templates to be used +by all applications, as well as providing extra ones in a plugin. This +approach allowed us to reuse common HTML pages, what facilitates +maintenance. + +Colab also provides a publish-subscribe event system. This allows one of +the applications, or Colab itself, to trigger an action in another +application. For example, when a user registers with Colab, all +applications need to be notified in order to create their own internal +representation of that user account. + +Colab also provides an integrated search engine, which can be configured +to specify exactly what data needs to be indexed for each of the +applications, and how to direct the user to that piece of information on +the specific application. Initially, Colab had support for a small set of applications (Trac, GNU -Mailman, and Apache Lucene) and all of them was hard-coded. Our team evolved -Colab so that it can now receive plugins to add support for new applications -with minimal changes to its existing core. We developed plugins to be used in -the SPB platform: Noosfero, GitLab, and Mezuro. +Mailman, and Apache Lucene) and support for them was hard-coded. Our +team evolved Colab so that it can now receive plugins that add support +new applications without the need of changes to the Colab core. We also +developed plugins to be used in the SPB platform: Noosfero, GitLab, and +Mezuro. \subsection{Noosfero} @@ -92,38 +106,34 @@ home pages and documentation, and contact forms. \subsection{Gitlab} -GitLab\footnote{\url{http://gitlab.com}} is a web-based Git repository manager -with wiki pages and issue tracking features. On the one hand, Github is the -most famous and used Git repository manager. On the other hand, it is not a -FOSS. Gitlab is a FOSS platform and focuses on delivering a holistic solution -that will see developers from idea to production seamlessly and on a single -platform. Thus, we have worked on it to integrated to Colab. - -Moreover, Gitlab has several features working properly than Github that is -interesting in SPB context such as free for private projects, built-in -continuous integration and continuous deployment with best practices, more -control during downtime and upgrade, flexible permissions, Work-in-Progress -protection, move issues between projects, Group-level milestones, Create new -branches from issues, Issue board, Time tracking, as well new features and -improvements every month on the 22nd. +GitLab\footnote{\url{http://gitlab.com}} is a web-based Git repository +manager with wiki pages and issue tracking features. Gitlab is a FOSS +platform and focuses on delivering a holistic solution that will see +developers from idea to production seamlessly and on a single platform. + +Gitlab has several unique features, such as built-in continuous +integration and continuous deployment, flexible permissions, tracking of +Work-in-Progress work, moving issues between projects, group-level +milestones, creating new branches from issues, issues board, and time +tracking. \subsection{Mezuro} Mezuro\footnote{\url{http://mezuro.org/}} is a platform to collect source code -metric to monitor the internal quality of softwares written in C, C++, -Java, Python, Ruby, and PHP. GNU Mailman is used for mailing lists. - -In general, source code metric tools also do not present a friendly way to -interpret its results and, even more, do not follow a standardization between -them. Mezuro brings and presents these results to -the end user, specially, by analyzing source code metric history during its -life cycle. - -The Mezuro platform provides a single interface -grouping available tools, allows selection and composition of metrics in a -flexible manner, stores the metrics evolution history, presents -results in a friendly way, as well as, allows users to customize the given -interpretation accordingly to their own context. +metrics to monitor the internal quality of software written in C, C++, +Java, Python, Ruby, and PHP. + +In general, source code metrics tools also do not present a friendly way +to interpret its results and, even more, do not follow a standardization +between them. Mezuro collects and presents these results to the end +user, specially, by analyzing source code metric history during its life +cycle. + +The Mezuro platform provides a single interface grouping available +tools, allows selection and composition of metrics in a flexible manner, +stores the metrics evolution history, presents results in a friendly +way, as well as, allows users to customize the given interpretation +accordingly to their own context. \subsection{System unification} -- libgit2 0.21.2