From 4fc3198ca2754817a021e45166b463b249e9f765 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Fri, 14 Mar 2014 16:08:29 -0300 Subject: Remove some user docs in favor of dl.bitmask.net Also: - Remove link to readthedocs. - Remove advanced instructions in favor of Hacking section. --- docs/client/en.md | 13 ++----- docs/client/user-install.md | 93 +++------------------------------------------ 2 files changed, 10 insertions(+), 96 deletions(-) (limited to 'docs/client') diff --git a/docs/client/en.md b/docs/client/en.md index 0436ec2..2768a55 100644 --- a/docs/client/en.md +++ b/docs/client/en.md @@ -5,15 +5,11 @@ Bitmask ======= -**Bitmask** is the multiplatform desktop client for the services offered by -[the LEAP Platform](platform). It is written in python using -[PySide](http://qt-project.org/wiki/PySide) and licensed under the GPL3. Currently we distribute pre-compiled bundles for Linux and OSX, with Windows bundles following soon. +**Bitmask** is the multiplatform desktop client for the services offered by [the LEAP Platform](platform). -You can find the complete up-to-date documentation [at the python package documentation -site.](http://pythonhosted.org/leap.bitmask "Bitmask documentation") +It is written in python using [PySide](http://qt-project.org/wiki/PySide) and licensed under the GPL3. Currently we distribute pre-compiled bundles for Linux and OSX, with Windows bundles following soon. -We include below some sections of the user guide and the development documentation so -you can get started. +We include below some sections of the user guide and the development documentation so you can get started. User Guide ---------- @@ -23,8 +19,7 @@ User Guide Tester Guide ------------ -This part of the documentation details how to fetch the last development -version and how to report bugs. +This part of the documentation details how to fetch the last development version and how to report bugs. * [Howto for testers](client/testers-howto) diff --git a/docs/client/user-install.md b/docs/client/user-install.md index e29d63e..2a99d66 100644 --- a/docs/client/user-install.md +++ b/docs/client/user-install.md @@ -4,86 +4,16 @@ Installation ============ -This part of the documentation covers the installation of Bitmask. We -assume that you want to get it properly installed before being able to -use it. But we can we wrong. - -Standalone bundle ------------------ - -Maybe the quickest way of running Bitmask in your machine is using the -standalone bundle. That is the recommended way to use Bitmask for the -time being. - -You can get the latest bundles, and their matching signatures at [the -downloads page](https://downloads.leap.se/client/). - -### Linux - -- [Linux 32 bits - bundle](https://downloads.leap.se/client/linux/Bitmask-linux32-latest.tar.bz2) - ([signature](https://downloads.leap.se/client/linux/Bitmask-linux32-latest.tar.bz2.asc)) -- [Linux 64 bits - bundle](https://downloads.leap.se/client/linux/Bitmask-linux64-latest.tar.bz2) - ([signature](https://downloads.leap.se/client/linux/Bitmask-linux64-latest.tar.bz2.asc)) - -### OSX - -- [OSX - bundle](https://downloads.leap.se/client/osx/Bitmask-OSX-latest.dmg) - ([signature](https://downloads.leap.se/client/osx/Bitmask-OSX-latest.dmg.asc)) - -### Windows - -- [Windows 32 bits - bundle](https://downloads.leap.se/client/windows/Bitmask-win32-latest.zip) - ([signature](https://downloads.leap.se/client/windows/Bitmask-win32-latest.zip.asc)) - -### Signature verification - -For the signature verification you can use : - - $ gpg --verify Bitmask-linux64-latest.tar.bz2.asc - -Asuming that you downloaded the linux 64 bits bundle. - -Debian / Ubuntu packages ------------------------- - -First, you need to bootstrap your apt-key: - - # gpg --recv-key 0x1E34A1828E207901 0x485B12FA218E81EB - # gpg --list-sigs 0x1E34A1828E207901 - # gpg --list-sigs 0x485B12FA218E81EB - # gpg -a --export 0x1E34A1828E207901 | sudo apt-key add - - -Add the archive to your sources.list, replace below with your Debian or -Ubuntu suite, which you can find by typing 'lsb_release -c' in a terminal. -Currently the following are available: sid, jessie, trusty, saucy, raring, quantal - - # echo "deb http://deb.leap.se/debian main" >> /etc/apt/sources.list - # apt-get update - # apt-get install leap-keyring - -And then you can happily install bitmask: - - apt-get install bitmask +For download links and installation instructions go to https://dl.bitmask.net/ Distribute & Pip ---------------- -> **note** -> -> The rest of the methods described below in this page assume you are -> familiar with python code, and you can find your way through the -> process of dependencies install. For more insight, you can also refer -> to the sections setting up a working environment or -> fetching latest code for testing. - -![image](https://pypip.in/v/leap.bitmask/badge.png%0A%20%20%20%20%20:target:%20https://crate.io/packages/leap.bitmask) +**Note** -Installing Bitmask is as simple as using -[pip](http://www.pip-installer.org/) for the already released versions : +If you are familiar with python code and you can find your way through the +process of dependencies install, you can installing Bitmask using [pip](http://www.pip-installer.org/) +for the already released versions : $ pip install leap.bitmask @@ -99,16 +29,5 @@ Or from the github mirror : $ git clone https://github.com/leapcode/bitmask_client.git -Once you have grabbed a copy of the sources, and installed all the base -dependencies, the recommended way to proceed is to install things in a virtualenv. - - $ virtualenv bitmask && source bitmask/bin/activate - $ make # compile the resources - $ python2 setup.py install - -Or you can install it into your global site-packages easily : - - $ make # compile the resources - $ sudo python2 setup.py install +For more information go to the [Hacking](client/dev-environment) section :) -WARNING: installing a package in the global site-packages can be harmful because the dependency installation can overwrite some of the existing packages. -- cgit v1.2.3 From 8adb717f7a75e1a7f1a5a285b6a806cc368e7549 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Fri, 14 Mar 2014 16:50:36 -0300 Subject: Update Hacking instructions. Also: - remove manual copy of files already done by bitmask. - update dependency installation instructions. --- docs/client/dev-environment.md | 72 +++++++----------------------------------- 1 file changed, 11 insertions(+), 61 deletions(-) (limited to 'docs/client') diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md index 37aefa6..dc82f0b 100644 --- a/docs/client/dev-environment.md +++ b/docs/client/dev-environment.md @@ -18,27 +18,22 @@ Cloning the repo git clone https://leap.se/git/bitmask_client git checkout develop -Base Dependencies ------------------ +Dependencies +------------ Bitmask depends on these libraries: -- python 2.6 or 2.7 -- qt4 libraries (see also - Troubleshooting PySide install \ about how to - install inside your virtualenv) -- openssl -- [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html) +- python 2.6 or 2.7 +- qt4 libraries +- openssl +- [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html) -### Debian +### Install dependencies in a Debian based distro In debian-based systems: - $ apt-get install openvpn python-pyside python-openssl + sudo apt-get install git python-dev python-setuptools python-virtualenv python-pip libssl-dev python-openssl libsqlite3-dev g++ openvpn pyside-tools python-pyside libffi-dev -To install the software from sources: - - $ apt-get install python-pip python-dev Working with virtualenv ----------------------- @@ -49,23 +44,16 @@ Working with virtualenv It is a tool to create isolated Python environments. -The basic problem being addressed is one of dependencies and versions, +> The basic problem being addressed is one of dependencies and versions, and indirectly permissions. Imagine you have an application that needs version 1 of LibFoo, but another application requires version 2. How can you use both these applications? If you install everything into -/usr/lib/python2.7/site-packages (or whatever your platform's standard +`/usr/lib/python2.7/site-packages` (or whatever your platform's standard location is), it's easy to end up in a situation where you unintentionally upgrade an application that shouldn't be upgraded. Read more about it in the [project documentation -page](http://pypi.python.org/pypi/virtualenv/). - -> **note** -> -> this section could be completed with useful options that can be passed -> to the virtualenv command (e.g., to make portable paths, -> site-packages, ...). We also should document how to use -> virtualenvwrapper. +page](http://www.virtualenv.org/en/latest/virtualenv.html). ### Create and activate your dev environment @@ -104,41 +92,3 @@ working environment, they will be installed avoiding the need for administrative permissions: $ pip install -r pkg/requirements.pip - -Copy script files ------------------ - -The openvpn invocation expects some files to be in place. If you have -not installed bitmask from a debian package, you must copy these files -manually by now: - - $ sudo mkdir -p /etc/leap - $ sudo cp pkg/linux/resolv-update /etc/leap - -Running openvpn without root privileges ---------------------------------------- - -In linux, we are using `policykit` to be able to run openvpn without -root privileges, and a policy file is needed to be installed for that to -be possible. The setup script tries to install the policy file when -installing bitmask system-wide, so if you have installed bitmask in your -global site-packages at least once it should have copied this file for -you. - -If you *only* are running bitmask from inside a virtualenv, you will -need to copy this file by hand: - - $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ - -### Missing Authentication agent - -If you are using linux and running a desktop other than unity or gnome, -you might get an error saying that you are not running the -authentication agent. For systems with gnome libraries installed you can -launch it like this: - - /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 & - -or if you are a kde user: - - /usr/lib/kde4/libexec/polkit-kde-authentication-agent-1 & -- cgit v1.2.3 From 0698a268c790e533430dadc398b0346dc6211619 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Fri, 14 Mar 2014 16:59:48 -0300 Subject: Add automagic helper script. --- docs/client/dev-environment.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) (limited to 'docs/client') diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md index dc82f0b..402db6f 100644 --- a/docs/client/dev-environment.md +++ b/docs/client/dev-environment.md @@ -4,7 +4,7 @@ Setting up a development environment ==================================== -This document covers how to get an enviroment ready to contribute code +This document covers how to get an environment ready to contribute code to Bitmask. Cloning the repo @@ -79,7 +79,7 @@ your virtualenv: $ virtualenv --site-packages . After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the -isntallation: +installation: $ export LEAP_VENV_SKIP_PYSIDE=1 @@ -92,3 +92,21 @@ working environment, they will be installed avoiding the need for administrative permissions: $ pip install -r pkg/requirements.pip + + +Using automagic helper script +----------------------------- + +You can use a helper script that will get you started with bitmask and all the related repos. +1) install system dependencies +2) download automagic script +3) run it :) + +Commands so you can copy/paste: + + mkdir bitmask && cd bitmask + wget https://raw.githubusercontent.com/leapcode/bitmask_client/develop/pkg/scripts/bootstrap_develop.sh + chmod +x bootstrap_develop.sh + ./bootstrap_develop.sh init # use help parameter for more information + +This script allows you to get started, update and run the bitmask app with all its repositories. -- cgit v1.2.3 From a64a663598737eeddb1184573b5c1e8fb4c87f02 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Fri, 14 Mar 2014 17:14:14 -0300 Subject: Update testing section. - Update #leap channel. - Remove unused instructions. - Point to Hacking section instead of duplicate the docs. --- docs/client/testers-howto.md | 95 ++++---------------------------------------- 1 file changed, 7 insertions(+), 88 deletions(-) (limited to 'docs/client') diff --git a/docs/client/testers-howto.md b/docs/client/testers-howto.md index 10a436d..e4cbcf3 100644 --- a/docs/client/testers-howto.md +++ b/docs/client/testers-howto.md @@ -75,16 +75,16 @@ Attach the logfile to your bug report. ### Need human interaction? -You can also find us in the `#leap-dev` channel on the [freenode +You can also find us in the `#leap` channel on the [freenode network](https://freenode.net). If you do not have a IRC client at hand, you can [enter the channel via -web](http://webchat.freenode.net/?nick=leaper....&channels=%23leap-dev&uio=d4). +web](http://webchat.freenode.net/?nick=leaper....&channels=%23leap&uio=d4). Fetching latest development code -------------------------------- Normally, testing the latest client bundles \ should -be enough. We are engaged in a two-week release cycle with minor +be enough. We are engaged in a three-week release cycle with minor releases that are as stable as possible. However, if you want to test that some issue has *really* been fixed @@ -95,86 +95,16 @@ script, keep reading for a way to painlessly fetch the latest development code. We have put together a script to allow rapid testing in different -platforms for the brave souls like you. It more or less does all the -steps covered in the Setting up a Work Enviroment \ -section, only that in a more compact way suitable (ahem) also for non -developers. +platforms for the brave souls like you. Check it out in the +*Setting up a Work Enviroment* section of the +[Hacking](client/dev-environment) page only that in a more compact +way suitable (ahem) also for non developers. > **note** > > At some point in the near future, we will be using standalone bundles > \ with the ability to self-update. -### Install dependencies - -First, install all the base dependencies plus git, virtualenv and -development files needed to compile several extensions: - - apt-get install openvpn git-core python-dev python-pyside python-setuptools python-virtualenv - -### Bootstrap script - -> **note** -> -> This will fetch the *develop* branch. If you want to test another -> branch, just change it in the line starting with *pip install...*. -> Alternatively, bug kali so she add an option branch to an improved -> script. - -> **note** -> -> This script could make use of the after\_install hook. Read -> - -Download and source the following script in the parent folder where you -want your testing build to be downloaded. For instance, to \`/tmp/: - -.. code-block:: bash - - cd /tmp - wget https://raw.github.com/leapcode/bitmask\_client/develop/pkg/scripts/bitmask\_bootstrap.sh - source bitmask\_bootstrap.sh - -Tada! If everything went well, you should be able to run bitmask by typing:: - - bitmask --debug - -Noticed that your prompt changed? That was \*virtualenv\*. Keep reading... - -Activating the virtualenv -\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^\^ -The above bootstrap script has fetched latest code inside a virtualenv, which is -an isolated, \*virtual\* python local environment that avoids messing with your -global paths. You will notice you are \*inside\* a virtualenv because you will see -a modified prompt reminding it to you (\*bitmask-testbuild\* in this case). - -Thus, if you forget to \*activate your virtualenv\*, bitmask will not run from the -local path, and it will be looking for something else in your global path. So, -\*\*you have to remember to activate your virtualenv\*\* each time that you open a -new shell and want to execute the code you are testing. You can do this by -typing:: - - \$ source bin/activate - -from the directory where you \*sourced\* the bootstrap script. - -Refer to :ref:Working with virtualenv \\` to learn more -about virtualenv. - -### Copying config files - -If you have never installed `bitmask` globally, **you need to copy some -files to its proper path before running it for the first time** (you -only need to do this once). This, unless the virtualenv-based -operations, will need root permissions. See -copy script files \ and -running openvpn without root privileges \ sections for more -info on this. In short: - - $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ - $ sudo mkdir -p /etc/leap - $ sudo cp pkg/linux/resolv-update /etc/leap - ### Local config files If you want to start fresh without config files, just move them. In @@ -182,17 +112,6 @@ linux: mv ~/.config/leap ~/.config/leap.old -### Pulling latest changes - -You should be able to cd into the downloaded repo and pull latest -changes: - - (bitmask-testbuild)$ cd src/bitmask - (bitmask-testbuild)$ git pull origin develop - -However, you are encouraged to run the whole bootstrapping process from -time to time to help us catching install and versioning bugs too. - ### Testing the packages When we have a release candidate for the supported platforms, we will -- cgit v1.2.3 From 66a92cfa48142475e43d20a59f22f36cd3a5e8f9 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Fri, 14 Mar 2014 17:59:14 -0300 Subject: Fix style and section name. --- docs/client/dev-environment.md | 7 ++++--- docs/client/testers-howto.md | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/client') diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md index 402db6f..780b8ad 100644 --- a/docs/client/dev-environment.md +++ b/docs/client/dev-environment.md @@ -98,9 +98,10 @@ Using automagic helper script ----------------------------- You can use a helper script that will get you started with bitmask and all the related repos. -1) install system dependencies -2) download automagic script -3) run it :) + +1. install system dependencies +2. download automagic script +3. run it :) Commands so you can copy/paste: diff --git a/docs/client/testers-howto.md b/docs/client/testers-howto.md index e4cbcf3..8311b95 100644 --- a/docs/client/testers-howto.md +++ b/docs/client/testers-howto.md @@ -96,7 +96,7 @@ development code. We have put together a script to allow rapid testing in different platforms for the brave souls like you. Check it out in the -*Setting up a Work Enviroment* section of the +*Using automagic helper script* section of the [Hacking](client/dev-environment) page only that in a more compact way suitable (ahem) also for non developers. -- cgit v1.2.3 From 6d81056b729d0b995f3e288a09dddf590f910de6 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Fri, 14 Mar 2014 18:08:43 -0300 Subject: Update supported OSs. --- docs/client/en.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/client') diff --git a/docs/client/en.md b/docs/client/en.md index 2768a55..4dd6953 100644 --- a/docs/client/en.md +++ b/docs/client/en.md @@ -41,12 +41,19 @@ If you want to contribute to the project, we wrote this for you. Supported OSs ------------- -Currently supported OSs (32 and 64 bits) are: +We currently support: -* Debian 7 (32bits lxde and 64 bits gnome3) -* Ubuntu 12.04 (LTS, unity) -* Ubuntu 13.10 (latest, unity) +### Through the bundle + +* Debian 7 +* Ubuntu 12.04 (LTS) +* Ubuntu 13.10 (latest) * Mac OSX >= 10.8 -* Windows 7 (32 bits only) -* Windows 8 (planned) +* Note: It *should* work in other Debian based distros + +### Through the debian package +* Ubuntu 13.04 (Raring Ringtail) +* Ubuntu 13.10 (Saucy Salamander) +* Debian 7.0 (Wheezy) +* Debian 8.0 (Jessie) -- cgit v1.2.3 From bdd5083487c3a4c54032ffc4627d8d7e9c588845 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Wed, 9 Apr 2014 11:46:10 -0300 Subject: Update instructions for developers. - Some of them were get from bitmask_client docs. This closes #4185. --- docs/client/dev-environment.md | 93 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 84 insertions(+), 9 deletions(-) (limited to 'docs/client') diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md index 780b8ad..eb78b3b 100644 --- a/docs/client/dev-environment.md +++ b/docs/client/dev-environment.md @@ -32,7 +32,7 @@ Bitmask depends on these libraries: In debian-based systems: - sudo apt-get install git python-dev python-setuptools python-virtualenv python-pip libssl-dev python-openssl libsqlite3-dev g++ openvpn pyside-tools python-pyside libffi-dev + $ sudo apt-get install git python-dev python-setuptools python-virtualenv python-pip libssl-dev python-openssl libsqlite3-dev g++ openvpn pyside-tools python-pyside libffi-dev Working with virtualenv @@ -57,8 +57,14 @@ page](http://www.virtualenv.org/en/latest/virtualenv.html). ### Create and activate your dev environment - $ virtualenv - $ source /bin/activate +You first create a virtualenv in any directory that you like: + + $ mkdir ~/Virtualenvs + $ virtualenv ~/Virtualenvs/bitmask + $ source ~/Virtualenvs/bitmask/bin/activate + (bitmask)$ + +Note the change in the prompt. ### Avoid compiling PySide inside a virtualenv @@ -72,11 +78,11 @@ the recommended way if you are running a debian-based system*): $ pkg/postmkvenv.sh A second option if that does not work for you would be to install PySide -globally and pass the `--site-packages` option when you are creating +globally and pass the `--system-site-packages` option when you are creating your virtualenv: $ apt-get install python-pyside - $ virtualenv --site-packages . + $ virtualenv --system-site-packages . After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the installation: @@ -93,6 +99,75 @@ administrative permissions: $ pip install -r pkg/requirements.pip +This step is not strictly needed, since the `setup.py develop` in the next +paragraph with also fetch the needed dependencies. But you need to know abou it: +when you or any person in the development team will be adding a new dependency, +you will have to repeat this command so that the new dependencies are installed +inside your virtualenv. + +Install Bitmask +--------------- + +Normally we would install the `leap.bitmask` package as any other package +inside the virtualenv. +But, instead, we will be using setuptools **development mode**. The difference +is that, instead of installing the package in a permanent location in your +regular installed packages path, it will create a link from the local +site-packages to your working directory. In this way, your changes will always +be in the installation path without need to install the package you are working +on.:: + + (bitmask)$ python2 setup.py develop + +After this step, your Bitmask launcher will be located at +`~/Virtualenvs/bitmask/bin/bitmask`, and it will be in the path as long as you +have sourced your virtualenv. + +Make resources +-------------- + +We also need to compile the resource files:: + + (bitmask)$ make resources + +You need to repeat this step each time you change a `.ui` file. + +Copy script files +----------------- + +The openvpn invocation expects some files to be in place. If you have not +installed `bitmask` from a debian package, you must copy these files manually +by now: + + $ sudo mkdir -p /etc/leap + $ sudo cp pkg/linux/resolv-update /etc/leap + + +Running openvpn without root privileges +--------------------------------------- + +In linux, we are using `policykit` to be able to run openvpn without root +privileges, and a policy file is needed to be installed for that to be +possible. +The setup script tries to install the policy file when installing bitmask +system-wide, so if you have installed bitmask in your global site-packages at +least once it should have copied this file for you. + +If you *only* are running bitmask from inside a virtualenv, you will need to +copy this file by hand: + + $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ + + +Running! +-------- + +If everything went well, you should be able to run your client by invoking +`bitmask`. If it does not get launched, or you just want to see more verbose +output, try the debug mode: + + (bitmask)$ bitmask --debug + Using automagic helper script ----------------------------- @@ -105,9 +180,9 @@ You can use a helper script that will get you started with bitmask and all the r Commands so you can copy/paste: - mkdir bitmask && cd bitmask - wget https://raw.githubusercontent.com/leapcode/bitmask_client/develop/pkg/scripts/bootstrap_develop.sh - chmod +x bootstrap_develop.sh - ./bootstrap_develop.sh init # use help parameter for more information + $ mkdir bitmask && cd bitmask + $ wget https://raw.githubusercontent.com/leapcode/bitmask_client/develop/pkg/scripts/bootstrap_develop.sh + $ chmod +x bootstrap_develop.sh + $ ./bootstrap_develop.sh init # use help parameter for more information This script allows you to get started, update and run the bitmask app with all its repositories. -- cgit v1.2.3