Download as
Browse Code »

Commit b6e18ab5ac873b9cf8d030f156e095a31601aa67

Authored by Antonio Terceiro
1 parent bee1d5d6
Exists in master and in 3 other branches oss_2018, oss_2018_siqueira, rework_case_study

content/04-architecture.tex: review

Showing 1 changed file with 96 additions and 86 deletions   Show diff stats
opensym2017/content/04-architecture.tex
  Diff comments   View file @b6e18ab
1 1 \section{Architecture}
2 2 \label{sec:architecture}
3 3  
4   -Based on the great list of functional requirements desired by Brazilian Federal
5   -Government we decided to select some FOSS systems that already contemplate some
6   -of them and improve these systems. And bringing the idea of community, it is
7   -undoable build a platform to be used by communities, which is a complex
8   -scenario, using just one tool.
  4 +Based on the extensive list of functional requirements defined by the
  5 +Brazilian Federal Government, we selected some FOSS systems to form our
  6 +solution. We looked for system that together could provide the largest
  7 +subset possible of the requirements, and were fully aware that we would
  8 +need to improve those systems in order to provide the rest. We were also
  9 +convinced that it would be impossible to provide all of those
  10 +requirements with a single tool.
9 11  
10   -At the point of view of the architecture, two main requirements was brought by
11   -the Brazilian Federal Government for the new platform:
  12 +From the point of view of the architecture, two main requirements was
  13 +brought by the Brazilian Federal Government for the new platform:
12 14  
13 15 \begin{enumerate}
14 16 \item \textit{Integrate existing FOSS systems}, with minimal differences from
... ... @@ -17,69 +19,81 @@ the Brazilian Federal Government for the new platform:
17 19 systems, as well as centralized authentication.
18 20 \end{enumerate}
19 21  
20   -Adopting existing FOSS systems by the government could bring the benefit of
21   -improvements done by the upstream communities, and the maintenance effort. On
22   -the other hand, integrating different tools with distinct intent, it is not an
23   -easy task and it was important to have a consistent user interface which
24   -justifies the last requirement.
  22 +Adopting existing FOSS systems and minimizing locally-made changes had
  23 +the objective of being able to upgrade to newer versions of the original
  24 +software, benefiting from improvements and maintenance done by the
  25 +existing project communities. Providing a consistent user interface on
  26 +top of those different tools was needed to make the transition between
  27 +the different systems seamless from the point of view of users, which
  28 +would be confused by jumping through completely different interfaces
  29 +while interacting with the portal.
25 30  
26 31 For the first requirement, we identified four main systems that required
27   -specialized teams for work in the integration process. The teams learned how to
28   -develop for their assigned systems and contributed to the original
29   -communities, so that the version we used were not significantly different from
30   -the original.
  32 +specialized teams for work in the integration process. The teams learned
  33 +how to develop for their assigned systems and contributed to the
  34 +original communities, so that the version we used were not significantly
  35 +different from the original.
31 36  
32   -At the end of the project, SPB portal was composed of more than ten systems
33   -among them we can highlight: Colab, Noosfero, Mezuro, Gitlab, Mailman, Postfix,
34   -Munin, and so forth. The following sections explained a little bit of Colab,
35   -Noosfero, Mezuro, and Gitlab (the main tools which we contributed). Below, we
36   -described how we integrated those tools and conclude with the deployment.
  37 +At the end of the project, the SPB portal was composed of more than ten
  38 +systems, such as Colab, Noosfero, Mezuro, Gitlab, Mailman, Postfix, and
  39 +Munin. The remainder of this section describes the most relevant of
  40 +them, as well as how they were integrated into the platform.
37 41  
38 42 \subsection{Colab}
39 43  
40   -Colab integrates web applications as its main goal, the user of this composed
41   -system should not notice the change between the integrated applications. Colab
42   -was designed to use one plugin for each system under its domain, this is
43   -guaranteed by four levels of integration:
  44 +Colab\footnote{\url{https://github.com/colab}} is a systems integration
  45 +platform for web applications. One of its goals is allowing different
  46 +applications to be combined in such a way that an user does not notice
  47 +the change between applications. For that, Colab provides facilities
  48 +for:
44 49  
45 50 \begin{itemize}
46   - \item Authentication
47   - \item Visual
48   - \item Events
49   - \item Data and search engine
  51 + \item Centralized authentication
  52 + \item Visual consistency
  53 + \item Relaying of events between applications
  54 + \item Integrated search engine
50 55 \end{itemize}
51 56  
52   -The aforementioned integrations levels were possible, because Colab works as a
53   -reverse proxy, therefore all external requests pass through it.
54   -
55   -Single Sign-On (SSO) is used to login users throughout all integrated
56   -applications. REMOTE\_USER HTTP header is sent to the applications and we
57   -expect that they know how to handle it, since this is a common authentication
58   -mechanism. The integrated applications should be on a local network to avoid
59   -security issues. With this the user will be able to navigate through the
60   -platform applications and will not be asked for authentication credentials.
61   -
62   -As Colab\footnote{\url{https://github.com/colab}} is a reverse proxy, it makes
63   -some HTML transformations in the HTTP response of integrated applications to
64   -provide a unified interface. Allows one to define some default templates to be
65   -used by all applications and overwrite when needed in its plugin. This approach
66   -allowed us to reuse some HTML pages which facilitates maintenance.
67   -
68   -A publish-subscribe implementation was used to handle events in the platform.
69   -Thus, if some application want to trigger some action in case that other
70   -application do something is possible. A registration of the desired events and
71   -implementation of the handlers must be done in the plugin of each application.
72   -This bring us many options to innovate in these integrations.
73   -
74   -A integrated search engine is provided by Colab. Each plugin specify which data
75   -will be indexed and will became available for the users, just need an simple
76   -implementation of how should perform the collection of data.
  57 +Colab implements this integration by working as a reverse proxy for the
  58 +integration applications, that is, all external requests pass through
  59 +Colab before reaching them.
  60 +
  61 +Centralized authentication is handled by letting users authenticate to
  62 +Colab, which then sends a REMOTE\_USER HTTP header to applications,
  63 +which are expected to be pre-configured to accept that as an indication
  64 +of the current user (REMOTE\_USER is a standard authentication mechanism
  65 +for web applications). This allows users to be automatically identified
  66 +to each of the applications without having to enter credentials for each
  67 +of them.
  68 +%
  69 +Of course, this requires that the integrated applications are not
  70 +accessible on the public internet, otherwise malicious users could send
  71 +their own crafted REMOTE\_USER headers and impersonate any user.
  72 +
  73 +For the visual consistency, Colab is able to make transformations to the
  74 +HTML produced by the integrated applications, ir order to provide a
  75 +unified interface. It allows one to define default templates to be used
  76 +by all applications, as well as providing extra ones in a plugin. This
  77 +approach allowed us to reuse common HTML pages, what facilitates
  78 +maintenance.
  79 +
  80 +Colab also provides a publish-subscribe event system. This allows one of
  81 +the applications, or Colab itself, to trigger an action in another
  82 +application. For example, when a user registers with Colab, all
  83 +applications need to be notified in order to create their own internal
  84 +representation of that user account.
  85 +
  86 +Colab also provides an integrated search engine, which can be configured
  87 +to specify exactly what data needs to be indexed for each of the
  88 +applications, and how to direct the user to that piece of information on
  89 +the specific application.
77 90  
78 91 Initially, Colab had support for a small set of applications (Trac, GNU
79   -Mailman, and Apache Lucene) and all of them was hard-coded. Our team evolved
80   -Colab so that it can now receive plugins to add support for new applications
81   -with minimal changes to its existing core. We developed plugins to be used in
82   -the SPB platform: Noosfero, GitLab, and Mezuro.
  92 +Mailman, and Apache Lucene) and support for them was hard-coded. Our
  93 +team evolved Colab so that it can now receive plugins that add support
  94 +new applications without the need of changes to the Colab core. We also
  95 +developed plugins to be used in the SPB platform: Noosfero, GitLab, and
  96 +Mezuro.
83 97  
84 98 \subsection{Noosfero}
85 99  
... ... @@ -92,38 +106,34 @@ home pages and documentation, and contact forms.
92 106  
93 107 \subsection{Gitlab}
94 108  
95   -GitLab\footnote{\url{http://gitlab.com}} is a web-based Git repository manager
96   -with wiki pages and issue tracking features. On the one hand, Github is the
97   -most famous and used Git repository manager. On the other hand, it is not a
98   -FOSS. Gitlab is a FOSS platform and focuses on delivering a holistic solution
99   -that will see developers from idea to production seamlessly and on a single
100   -platform. Thus, we have worked on it to integrated to Colab.
101   -
102   -Moreover, Gitlab has several features working properly than Github that is
103   -interesting in SPB context such as free for private projects, built-in
104   -continuous integration and continuous deployment with best practices, more
105   -control during downtime and upgrade, flexible permissions, Work-in-Progress
106   -protection, move issues between projects, Group-level milestones, Create new
107   -branches from issues, Issue board, Time tracking, as well new features and
108   -improvements every month on the 22nd.
  109 +GitLab\footnote{\url{http://gitlab.com}} is a web-based Git repository
  110 +manager with wiki pages and issue tracking features. Gitlab is a FOSS
  111 +platform and focuses on delivering a holistic solution that will see
  112 +developers from idea to production seamlessly and on a single platform.
  113 +
  114 +Gitlab has several unique features, such as built-in continuous
  115 +integration and continuous deployment, flexible permissions, tracking of
  116 +Work-in-Progress work, moving issues between projects, group-level
  117 +milestones, creating new branches from issues, issues board, and time
  118 +tracking.
109 119  
110 120 \subsection{Mezuro}
111 121  
112 122 Mezuro\footnote{\url{http://mezuro.org/}} is a platform to collect source code
113   -metric to monitor the internal quality of softwares written in C, C++,
114   -Java, Python, Ruby, and PHP. GNU Mailman is used for mailing lists.
115   -
116   -In general, source code metric tools also do not present a friendly way to
117   -interpret its results and, even more, do not follow a standardization between
118   -them. Mezuro brings and presents these results to
119   -the end user, specially, by analyzing source code metric history during its
120   -life cycle.
121   -
122   -The Mezuro platform provides a single interface
123   -grouping available tools, allows selection and composition of metrics in a
124   -flexible manner, stores the metrics evolution history, presents
125   -results in a friendly way, as well as, allows users to customize the given
126   -interpretation accordingly to their own context.
  123 +metrics to monitor the internal quality of software written in C, C++,
  124 +Java, Python, Ruby, and PHP.
  125 +
  126 +In general, source code metrics tools also do not present a friendly way
  127 +to interpret its results and, even more, do not follow a standardization
  128 +between them. Mezuro collects and presents these results to the end
  129 +user, specially, by analyzing source code metric history during its life
  130 +cycle.
  131 +
  132 +The Mezuro platform provides a single interface grouping available
  133 +tools, allows selection and composition of metrics in a flexible manner,
  134 +stores the metrics evolution history, presents results in a friendly
  135 +way, as well as, allows users to customize the given interpretation
  136 +accordingly to their own context.
127 137  
128 138 \subsection{System unification}
129 139  
... ...