Hello! We are running our annual fundraising. Please consider making a donation if you value this freely available service or want to support people around the world working towards liberatory social change. https://riseup.net/donate.

README.rst 4.91 KB
Newer Older
Kali Kaneko's avatar
Kali Kaneko committed
1
Bitmask
2
===========================================================
3

Kali Kaneko's avatar
Kali Kaneko committed
4
*Your internet encryption toolkit*
5

Kali Kaneko's avatar
Kali Kaneko committed
6
7
.. image:: https://badge.fury.io/py/leap.bitmask.svg
    :target: http://badge.fury.io/py/leap.bitmask
Kali Kaneko's avatar
Kali Kaneko committed
8
9
.. image:: https://0xacab.org/leap/bitmask-dev/badges/master/build.svg
    :target: https://0xacab.org/leap/bitmask-dev/pipelines
Kali Kaneko's avatar
Kali Kaneko committed
10
11
12
.. image:: https://readthedocs.org/projects/bitmask/badge/?version=latest
   :target: http://bitmask.readthedocs.io/en/latest/?badge=latest
   :alt: Documentation Status
Kali Kaneko's avatar
Kali Kaneko committed
13
14
15
16
17
18
.. image:: https://img.shields.io/badge/IRC-leap-blue.svg
   :target: http://webchat.freenode.net/?channels=%23leap&uio=d4
   :alt: IRC
.. image:: https://img.shields.io/badge/IRC-bitmask_(es)-blue.svg
   :target: http://webchat.freenode.net/?channels=%23bitmask-es&uio=d4
   :alt: IRC-es
19
20


Kali Kaneko's avatar
Kali Kaneko committed
21
22
23
24
**Bitmask** is the client for the services offered by `the LEAP Platform`_. It
contains a command-line interface and a multiplatform desktop client. It can be
also used as a set of libraries to communicate with the different services from
third party applications.
25

Kali Kaneko's avatar
Kali Kaneko committed
26
It is written in python using `Twisted`_  and licensed under the `GPL3`_. The
27
28
Graphical User Interface is written in html+js and uses `PyQt5`_ for serving
the application.
Kali Kaneko's avatar
Kali Kaneko committed
29
30
31
32
33
34

.. _`the LEAP Platform`: https://github.com/leapcode/leap_platform
.. _`Twisted`: https://twistedmatrix.com
.. _`PyQt5`: https://pypi.python.org/pypi/PyQt5
.. _`GPL3`: http://www.gnu.org/licenses/gpl.txt

35
Package under development!
36
-----------------------------------------------------------
37

38
The previous client using PySide has been deprecated (Bitmask version 0.9.2,
39
still available at the http://github.com/leapcode/bitmask_client repo).
40
41


Kali Kaneko's avatar
Kali Kaneko committed
42
Read the Docs!
43
-----------------------------------------------------------
Kali Kaneko's avatar
Kali Kaneko committed
44

45
46
47
There is documentation about Bitmask `for users`_ and `for developers`_. For
developers, be sure to read the sections on `hacking`_ and `contributing_`.
Testers should read the section on `testing and QA`_.
Kali Kaneko's avatar
Kali Kaneko committed
48

49
.. _`for users`: https://leap.se/en/docs/client
50
51
52
53
.. _`for developers`: https://bitmask.readthedocs.io
.. _`hacking`: https://bitmask.readthedocs.io/en/latest/hacking/index.html
.. _`contributing`: https://bitmask.readthedocs.io/en/latest/hacking/contributing.html#contributing
.. _`testing and QA`: https://bitmask.readthedocs.io/en/latest/testing/index.html
Kali Kaneko's avatar
Kali Kaneko committed
54
55

Bugs
56
===========================================================
Kali Kaneko's avatar
Kali Kaneko committed
57
58
59

Please report any bugs `in our bug tracker`_.

60
.. _`in our bug tracker`: https://0xacab.org/leap/bitmask-dev/issues/
Kali Kaneko's avatar
Kali Kaneko committed
61

62
63
64
65
66
67
68
69
70
71
72
73
Logs
----

If you want to watch the logs, from the command line::

  bitmaskctl logs watch

The paste command can be handy to do bug reports (needs ``pastebinit`` installed
in the system)::

  bitmaskctl logs send

74
75
but do not upload anything that you do not want to make public ;)

76

Kali Kaneko's avatar
Kali Kaneko committed
77
Development
78
===========================================================
79

80
Running Tests
81
-----------------------------------------------------------
82

Kali Kaneko's avatar
Kali Kaneko committed
83
You need tox to run the tests. If you don't have it in your system yet::
84
85

  pip install tox
Kali Kaneko's avatar
Kali Kaneko committed
86

87
And then run all the python tests::
Kali Kaneko's avatar
Kali Kaneko committed
88

89
90
  tox

91
92
93
94
95
96
97
98
99
There are some minimal end-to-end tests::

  make test_e2e

For testing the UI (aka ``bitmask-js``) you need to have ``mocha``
installed. You can run ui tests like this::

  cd ui && make test

100
101
More info abou testing can be found in the ``docs/hacking/testing`` document.

Kali Kaneko's avatar
Kali Kaneko committed
102
103

Hacking
104
-----------------------------------------------------------
105

106
107
108
109
110
In order to run bitmask in a development environment, you must activate a 
`virtualenv`_ and install the various leap-related python packages using ``pip
install -e``. This installs them as links to the source code, so
that your code changes are immediately reflected in the packages imported from
within the virtualenv.
Kali Kaneko's avatar
Kali Kaneko committed
111

112
The various ``make dev-*`` commands will run the appropriate ``pip install``
113
commands for you.
Kali Kaneko's avatar
Kali Kaneko committed
114

115
116
If you want to setup your whole development environment in a single step, and
you are running a debian-based system, you can use::
117
118
119

  make dev-bootstrap

120
121
That should install all the system dependencies, create a virtualenv for you,
and drop you in a shell inside that virtualenv. In the future, you can enter this
122
`virtualenv`_ again by using `pew`_::
123
124
125

  pew workon bitmask

126
127
128
129
130
131
To upgrade regularly the python dependencies installed inside your virtualenv,
you can run::

  make upgrade-all

inside your virtualenv, and it will install any new version of your
132
dependencies that is found in `pypi`_.
133

134
Check out the ``docs/hacking`` page for more extense instructions `to get
135
136
137
you started`_.

.. _`to get you started`: https://bitmask.readthedocs.io/en/latest/hacking/
138
139
140
.. _`pew`: https://pypi.python.org/pypi/pew
.. _`virtualenv`: https://pypi.python.org/pypi/virtualenv
.. _`pypi`: https://pypi.python.org
141

142

Kali Kaneko's avatar
Kali Kaneko committed
143
License
144
===========================================================
Kali Kaneko's avatar
Kali Kaneko committed
145
146
147
148
149
150

.. image:: https://raw.github.com/leapcode/bitmask_client/develop/docs/user/gpl.png

Bitmask is released under the terms of the `GNU GPL version 3`_ or later.

.. _`GNU GPL version 3`: http://www.gnu.org/licenses/gpl.txt