summaryrefslogtreecommitdiff
path: root/onboarding.rst
blob: c69829555ed63385c7a15bbe535170ce7709142e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
Developer Onboarding Manual
###########################


Taler installation
==================

This section describes the GNU Taler deployment on ``gv.taler.net``.

User Acccounts
--------------

On ``gv.taler.net``, there are four users that are set up to serve Taler on
the internet:

-  ``taler-test``: serves ``*.test.taler.net`` and gets automatically
   built by Buildbot.

-  ``taler-internal``: serves ``*.int.taler.net``, and does *NOT* get
   automatically built.

The following two users are *never* automatically built, and they both
serve ``*.demo.taler.net``. At any given time, only one is active and
serves the HTTP requests from the outside; the other one can so be
compiled without any downtime. If the compilation succeeds, the inactive
user can be switched to become active (see next section), and vice versa.

-  ``demo-blue``
-  ``demo-green``

Compile and switch color.
-------------------------

If the setup is already bootstrapped, then it should only be needed to
login as ’demo-X’ (with X being the inactive color); and then:

::

   $ source activate
   $ taler-deployment-build

and then switch the color by logging in as the *demo* user, and switch
the color with the following command:

::

   $ taler-deployment-switch-demo-X

Full bootstrap.
---------------

In order to bootstrap a Taler installation under a empty home directory,
do:

::

   $ cd $HOME 
   $ git clone git://git.taler.net/deployment

Then run the prepare script that will (1) download all the repositories
(2) build the codebases, (3) configure the system, and (4) generate the
needed data.

::
   $ ./deployment/bin/taler-deployment-prepare
    
..

   **Note**

   If the DB schema of merchant/exchange/auditor changed, at this point
   it MIGHT be necessary to reset all the tables. To this regard,
   consider running one of the following commands:

   ::

      # To reset the merchant DB.
      $ taler-merchant-dbinit -r

      # To reset the exchange DB.
      $ taler-exchange-dbinit -r

      # To reset the exchange DB.
      $ taler-auditor-dbinit -r

If all the steps succeeded, then it should be possible to launch all the
services. Give:

::

   $ taler-deployment-start

   # or restart, if you want to kill old processes and
   # start new ones.
   $ taler-deployment-restart

Verify that all services are up and running:

::

   $ taler-deployment-arm -I
   $ tail logs/<component>-<date>.log

How to upgrade the code.
------------------------

Some repositories, especially the ones from the released components,
have a *stable* branch, that keeps older and more stable code.
Therefore, upon each release we must rebase those stable branches on the
master.

The following commands do that:

::

   $ cd $REPO

   $ git pull origin master stable
   $ git checkout stable

   # option a: resolve conflicts resulting from hotfixes
   $ git rebase master
   $ ...

   # option b: force stable to master
   $ git update-ref refs/heads/stable master

   $ git push # possibly with --force

   # continue development
   $ git checkout master

.. _Testing-components:

Building the documentation
==========================

All the Taler documentation is built by the user `docbuilder` that
runs a Buildbot worker.  The following commands set the `docbuilder` up,
starting with a empty home directory.

::
  # Log-in as the 'docbuilder' user.

  $ cd $HOME
  $ git clone git://git.taler.net/deployment
  $ ./deployment/bootstrap-docbuilder

  # If the previous step worked, the setup is
  # complete and the Buildbot worker can be started.

  $ buildbot-worker start worker/


Building the Websites.
======================

Taler Websites, `www.taler.net` and `stage.taler.net`, are built by the user `taler-websites`
by the means of a Buildbot worker.  The following commands set the `taler-websites` up,
starting with a empty home directory.

::
  # Log-in as the 'taler-websites' user.

  $ cd $HOME
  $ git clone git://git.taler.net/deployment
  $ ./deployment/bootstrap-sitesbuilder

  # If the previous step worked, the setup is
  # complete and the Buildbot worker can be started.

  $ buildbot-worker start worker/



Testing components
==================

This chapter is a VERY ABSTRACT description of how testing is
implemented in Taler, and in NO WAY wants to substitute the reading of
the actual source code by the user.

In Taler, a test case is a array of ``struct TALER_TESTING_Command``,
informally referred to as ``CMD``, that is iteratively executed by the
testing interpreter. This latter is transparently initiated by the
testing library.

However, the developer does not have to defined CMDs manually, but
rather call the proper constructor provided by the library. For example,
if a CMD is supposed to test feature ``x``, then the library would
provide the ``TALER_TESTING_cmd_x ()`` constructor for it. Obviously,
each constructor has its own particular arguments that make sense to
test ``x``, and all constructor are thoroughly commented within the
source code.

Internally, each CMD has two methods: ``run ()`` and ``cleanup ()``. The
former contains the main logic to test feature ``x``, whereas the latter
cleans the memory up after execution.

In a test life, each CMD needs some internal state, made by values it
keeps in memory. Often, the test has to *share* those values with other
CMDs: for example, CMD1 may create some key material and CMD2 needs this
key material to encrypt data.

The offering of internal values from CMD1 to CMD2 is made by *traits*. A
trait is a ``struct TALER_TESTING_Trait``, and each CMD contains a array
of traits, that it offers via the public trait interface to other
commands. The definition and filling of such array happens transparently
to the test developer.

For example, the following example shows how CMD2 takes an amount object
offered by CMD1 via the trait interface.

Note: the main interpreter and the most part of CMDs and traits are
hosted inside the exchange codebase, but nothing prevents the developer
from implementing new CMDs and traits within other codebases.

::

   /* Withouth loss of generality, let's consider the
    * following logic to exist inside the run() method of CMD1 */
   ..

   struct TALER_Amount *a;
   /**
    * the second argument (0) points to the first amount object offered,
    * in case multiple are available.
    */
   if (GNUNET_OK != TALER_TESTING_get_trait_amount_obj (cmd2, 0, &a))
     return GNUNET_SYSERR;
   ...

   use(a); /* 'a' points straight into the internal state of CMD2 */

In the Taler realm, there is also the possibility to alter the behaviour
of supposedly well-behaved components. This is needed when, for example,
we want the exchange to return some corrupted signature in order to
check if the merchant backend detects it.

This alteration is accomplished by another service called *twister*. The
twister acts as a proxy between service A and B, and can be programmed
to tamper with the data exchanged by A and B.

Please refer to the Twister codebase (under the ``test`` directory) in
order to see how to configure it.

.. _Releases:

Releases
========

Release Process and Checklists
------------------------------

This document describes the process for releasing a new version of the
various Taler components to the official GNU mirrors.

The following components are published on the GNU mirrors

-  taler-exchange (exchange.git)
-  taler-merchant (merchant.git)
-  talerdonations (donations.git)
-  talerblog (blog.git)
-  taler-bank (bank.git)
-  taler-wallet-webex (wallet-webex.git)

Tagging
-------

Tag releases with an **annotated** commit, like

::

   git tag -a v0.1.0 -m "Official release v0.1.0"
   git push origin v0.1.0

Database for tests
------------------

For tests in the exchange and merchant to run, make sure that a database
*talercheck* is accessible by *$USER*. Otherwise tests involving the
database logic are skipped.

Exchange, merchant
------------------

Set the version in ``configure.ac``. The commit being tagged should be
the change of the version.

For the exchange test cases to pass, ``make install`` must be run first.
Without it, test cases will fail because plugins can’t be located.

::

   ./bootstrap
   ./configure # add required options for your system
   make dist
   tar -xf taler-$COMPONENT-$VERSION.tar.gz
   cd taler-$COMPONENT-$VERSION
   make install check

Wallet WebExtension
-------------------

The version of the wallet is in *manifest.json*. The ``version_name``
should be adjusted, and *version* should be increased independently on
every upload to the WebStore.

::

   ./configure
   make dist

Upload to GNU mirrors
---------------------

See
*https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads*

Directive file:

::

   version: 1.2
   directory: taler
   filename: taler-exchange-0.1.0.tar.gz

Upload the files in **binary mode** to the ftp servers.

.. _Code:

Code
====

Taler code is versioned via Git. For those users without write access,
all the codebases are found at the following URL:

::

   git://git.taler.net/<repository>

A complete list of all the existing repositories is currently found at
``https://git.taler.net/``. Note: ``<repository>`` must NOT have the
``.git`` extension.

.. _Bugtracking:

Bugtracking
===========

Bug tracking is done with Mantis (https://www.mantisbt.org/). All the
bugs are then showed and managed at ``https://bugs.gnunet.org/``, under
the "Taler" project. A registration on the Web site is needed in order
to use the bug tracker.

.. _Continuous-integration:

Continuous integration
======================

CI is done with Buildbot (https://buildbot.net/), and builds are
triggered by the means of Git hooks. The results are published at
``https://buildbot.wild.gv.taler.net/``.

In order to avoid downtimes, CI uses a "blue/green" deployment
technique. In detail, there are two users building code on the system,
the "green" and the "blue" user; and at any given time, one is running
Taler services and the other one is either building the code or waiting
for that.

There is also the possibility to trigger builds manually, but this is
only reserved to "admin" users.

.. _Code-coverage:

Code coverage
=============

Code coverage is done with the Gcov / Lcov
(http://ltp.sourceforge.net/coverage/lcov.php) combo, and it is run
\*nightly\* (once a day) by a Buildbot worker. The coverage results are
then published at ``https://lcov.taler.net/``.