INSTALL.rst 3.67 KB
Newer Older
Matt Traudt's avatar
Matt Traudt committed
1
2
.. _install:

3
Installing Simple Bandwidth Scanner
4
===================================
5

6
The recommended method  is to install it from your system package manager.
juga's avatar
juga committed
7

8
In Debian_/Ubuntu_ systems::
juga's avatar
juga committed
9
10
11
12
13
14
15

    sudo apt install sbws

To install also the documentation::

    sudo apt install sbws-doc

16
17
You might need to check in which releases is the package available.

18
19
There is a port_ for FreeBSD.

juga's avatar
juga committed
20
Continue reading to install ``sbws`` in other ways.
juga's avatar
juga committed
21
22
23
24

System requirements
--------------------

25
- Tor (last stable version is recommended)
26
- Python 3 (>= 3.6)
Matt Traudt's avatar
Matt Traudt committed
27

juga's avatar
juga committed
28
29
Python dependencies
--------------------
Matt Traudt's avatar
Matt Traudt committed
30

31
- Stem_ >= 1.7.0
juga's avatar
juga committed
32
- Requests_ (with socks_ support) >= 2.10.0
Matt Traudt's avatar
Matt Traudt committed
33

34
35
36
37
38
39
40
41
42
43
44
It is recommend to install the dependencies from your system package manager.
If that is not possible, because the Python dependencies are not available in
your system, you can install them from their sources.
We only recommend using pip_ for development or testing.

Installing sbws from source
---------------------------

Clone ``sbws``::

    git clone https://git.torproject.org/sbws.git
45
46
47
48
    git checkout maint-1.1

The branch ``maint-1.1`` is the last stable version and the one that should be
used in production.
49
50
51
52
53

and install it::

    cd sbws
    python3 setup.py install
Matt Traudt's avatar
Matt Traudt committed
54

55
56
57
58
59
60
61
Installing sbws for development or testing
------------------------------------------

If you use pip_, it is recommended to use virtualenv_, to avoid having
different versions of the same libraries in your system.

To create a ``virtualenv``::
Matt Traudt's avatar
Matt Traudt committed
62

juga's avatar
juga committed
63
    virtualenv venv -p /usr/bin/python3
Matt Traudt's avatar
Matt Traudt committed
64
65
    source venv/bin/activate

juga's avatar
juga committed
66
Clone ``sbws``::
Matt Traudt's avatar
Matt Traudt committed
67

anadahz's avatar
anadahz committed
68
    git clone https://git.torproject.org/sbws.git
Matt Traudt's avatar
Matt Traudt committed
69

70
Install the python dependencies::
Matt Traudt's avatar
Matt Traudt committed
71

72
73
74
75
    cd sbws && pip install -e .

Configuration and deployment
----------------------------
Matt Traudt's avatar
Matt Traudt committed
76

juga's avatar
juga committed
77
``sbws`` needs :term:`destination` s to request files from.
juga's avatar
juga committed
78

79
Please, see `<DEPLOY.rst>`_ (in the local directory or Tor Project Gitlab) or
80
`<DEPLOY.html>`_ (local build or Read the Docs)
juga's avatar
juga committed
81
to configure, deploy and run ``sbws``.
Matt Traudt's avatar
Matt Traudt committed
82

juga's avatar
juga committed
83
84
85
System physical requirements
-----------------------------

86
- Bandwidth: at least 12.5MB/s (100 Mbit/s).
juga's avatar
juga committed
87
- Free RAM: at least 2GB
juga's avatar
juga committed
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
- Free disk: at least 3GB

``sbws`` and its dependencies need around 20MB of disk space.
After 90 days ``sbws`` data files use around 3GB.
If ``sbws`` is configured to log to files (by default will log to the
system log), it will need a maximum of 500MB.

It is recommended to set up an automatic disk space monitoring on ``sbws`` data
and log partitions.

Details about ``sbws`` data:

``sbws`` produces around 100MB of data a day.
By default raw results' files are compressed after 10 days and deleted after 90.
The bandwidth files are compressed after 7 days and deleted after 1.
After 90 days, the disk space used by the data will be aproximately 3GB.
It will not increase further.
If ``sbws`` is configured to log to files, logs will be rotated after they
are 10MB and it will keep 50 rotated log files.

juga's avatar
juga committed
108
109
110
.. _virtualenv: https://virtualenv.pypa.io/en/stable/installation/
.. _Stem: https://stem.torproject.org/
.. _socks: http://docs.python-requests.org/en/master/user/advanced/#socks
juga's avatar
juga committed
111
112
.. https://readthedocs.org/projects/requests/ redirect to this, but the
.. certificate of this signed by rtd
juga's avatar
juga committed
113
.. _Requests: http://docs.python-requests.org/
juga's avatar
juga committed
114
115
.. http://flake8.pycqa.org/ certificate is signed by rtf
.. _Flake8: https://flake8.readthedocs.org/
juga's avatar
juga committed
116
117
118
.. _pytest: https://docs.pytest.org/
.. _tox: https://tox.readthedocs.io
.. _Coverage: https://coverage.readthedocs.io/
119
120
121
.. _port: https://www.freshports.org/net/py-sbws/
.. _Debian: https://packages.debian.org/search?keywords=sbws&searchon=names&suite=all&section=all
.. _Ubuntu: https://packages.ubuntu.com/search?keywords=sbws&searchon=names&suite=all&section=all
122
.. _pip: https://pypi.org/project/pip/