Installing Simple Bandwidth Scanner

(At the time of writing) sbws depends on two Python libraries.

Sbws relies on a stem feature that is not planned to be in a tagged release until stem 1.7.0.

Read all the information for the installation method of your choice before beginning. Often you will want to be armed with the knowledge of the latest released version of sbws. Determine that by examining its git tags, or visiting its release page. In the remainder of this document, we assume the latest version is 1.5.3, which would be tagged as v1.5.3.

Virtualenv - Development

Choose a directory to store code in. I might choose ~/src.

cd ~/src

Get stem

git clone https://git.torproject.org/stem.git

Get sbws

git clone https://github.com/pastly/simple-bw-scanner.git
cd simple-bw-scanner

Create and enter virtualenv

I like to keep mine in my simple-bw-scanner directory and assume that’s where you’ll put it.

virtualenv -p python3 venv
source venv/bin/activate

Install stem in virtualenv

Sbws requires on features not yet in a released version of stem (1.7.0 has not been released as of the time of writing). You can either install from the master branch, or checkout 60f034ad8b9c3aa48e7e2ecb0a2e159b6ed5bc71 or newer.

pip install ../stem

Install sbws and its remaining dependencies

Here is where you might want to know what the latest release of sbws is (this document assumes it is 1.5.3). Skip the git checkout if you want to run the bleeding edge tip-of-master version of sbws.

git checkout v1.5.3
pip install .

Initialize sbws

This creates ~/.sbws and initializes some files in it.

sbws init

If you would like to keep sbws’s data directory somewhere else, use -d. You will have to use -d every time you run an sbws command to use this custom directory.

sbws -d /tmp/dotsbws-testing init

[OBSOLETE DO NOT FOLLOW] Virtualenv - Production

Installing

git clone https://github.com/pastly/simple-bw-scanner.git
cd simple-bw-scanner
git checkout v1.5.3
virtualenv -p python3 venv
source venv/bin/activate
pip install --process-dependency-links .
sbws init

Note

Because we relay on a -dev version of stem, we need to fetch it from git.torproject.org. Thus --process-dependency-links is necessary.

Warning

Run these commands one at a time and check for errors before continuing.

Updating

cd simple-bw-scanner
git pull
# Determine the newest released version. Assuming it is v1.5.3 ...
git checkout v1.5.3
source venv/bin/activate
pip install --process-dependency-links --upgrade-strategy eager --upgrade .

[OBSOLETE DO NOT FOLLOW] Virtualenv - Development

These are almost exactly the same. The difference is the pip command: we install sbws in an editable state so we don’t have to re-run pip every time we make a change.

git clone https://github.com/pastly/simple-bw-scanner.git
cd simple-bw-scanner
git checkout v1.5.3
virtualenv -p python3 venv-editable
source venv-editable/bin/activate
pip install --process-dependency-links --editable .
sbws init

Note

Because we relay on a -dev version of stem, we need to fetch it from git.torproject.org. Thus --process-dependency-links is necessary.

Warning

Run these commands one at a time and check for errors before continuing.

Updating

cd simple-bw-scanner
git pull
# Determine the newest released version. Assuming it is v1.5.3 ...
git checkout v1.5.3

Todo

This doesn’t update dependencies and needs to be fixed.