From 652879ef39b5a94fba50f8c78524e71e040e8b5b Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Wed, 25 Sep 2013 12:28:21 -0400 Subject: update client docs This are the most important pages in the bitmask documentation. I have converted .rst files using pandoc, since the .rst does not seem to be supported like the README says. I have added @nav_title and @title headers. --- docs/client/bleeding-edge.md | 104 -------------------- docs/client/client-index.rst | 95 ------------------ docs/client/dev-environment.md | 144 +++++++++++++++++++++++++++ docs/client/dev-guide.md | 107 -------------------- docs/client/en.md | 36 ++++++- docs/client/packaging.md | 25 ----- docs/client/testers-howto.md | 215 +++++++++++++++++++++++++++++++++++++++++ docs/client/user-guide.md | 56 ----------- docs/client/user-install.md | 110 +++++++++++++++++++++ docs/client/user-running.md | 45 +++++++++ 10 files changed, 546 insertions(+), 391 deletions(-) delete mode 100644 docs/client/bleeding-edge.md delete mode 100644 docs/client/client-index.rst create mode 100644 docs/client/dev-environment.md delete mode 100644 docs/client/dev-guide.md delete mode 100644 docs/client/packaging.md create mode 100644 docs/client/testers-howto.md delete mode 100644 docs/client/user-guide.md create mode 100644 docs/client/user-install.md create mode 100644 docs/client/user-running.md (limited to 'docs/client') diff --git a/docs/client/bleeding-edge.md b/docs/client/bleeding-edge.md deleted file mode 100644 index 6a926f1..0000000 --- a/docs/client/bleeding-edge.md +++ /dev/null @@ -1,104 +0,0 @@ -@title = "HOWTO for running latest develop branch" -@nav_title = "Running Latest" - -This document covers a how-to guide to: - -1. Quickly fetching latest development code, and -2. Reporting bugs. - -Let's go! - -Fetching latest development code -========================================= - -To allow rapid testing in different platforms, we have put together a quick script that is able to fetch latest development code. It more or less does all the steps covered in the [Setting up a Work Enviroment](client/dev-guide) section, only that in a more compact way suitable (ahem) also for non developers. - -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-qt4 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 a decent script. - -> note: This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/ - -Download and source the following script in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/`: - - - cd /tmp - wget https://raw.github.com/leapcode/bitmask_client/develop/pkg/scripts/bitmask_bootstrap.sh - source leap_client_bootstrap.sh - -Tada! If everything went well, you should be able to run the client by typing: - - bin/leap-client - -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 (*leap-client-testbuild* in this case). - -Thus, if you forget to *activate your virtualenv*, the client 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 [Working with virtualenv](client/dev-guide) to learn more about virtualenv. - -Copying config files ----------------------------- - -If you have never installed the `leap-client` 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](client/dev-guide) and [running openvpn without root privileges](client/dev-guide) 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 linux: - - mv ~/.config/leap ~/.config/leap.old - -Pulling latest changes ------------------------------- - -You should be able to cd into the downloaded repo and pull latest changes: - - (leap-client-testbuild)$ cd src/leap-client - (leap-client-testbuild)$ git pull origin develop - -However, as a tester you are encouraged to run the whole bootstrap process from time to time to help us catching install and versioniing bugs too. - -Testing the packages -------------------------------- - -When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned! - -Testing the status of translations -================================================== - -We need translators! You can go to [transifex](https://www.transifex.com/projects/p/bitmask/), get an account and start contributing. - -If you want to check the current status of the client localization in a language other than the one set in your machine, you can do it with a simple trick (under linux). For instance, do: - - $ lang=es_ES leap-client - -for running LEAP Client with the spanish locales. - -Reporting bugs -======================= - -We use the [LEAP Client Bug Tracker](https://leap.se/code/projects/eip-client), although you can also use [Github issues](https://github.com/leapcode/bitmask_client/issues). - -> There is a great text on the art of bug reporting, that can be found at http://www.chiark.greenend.org.uk/~sgtatham/bugs.html diff --git a/docs/client/client-index.rst b/docs/client/client-index.rst deleted file mode 100644 index d0b0ff2..0000000 --- a/docs/client/client-index.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. Bitmask documentation master file, created by - sphinx-quickstart on Sun Jul 22 18:32:05 2012. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Bitmask -===================================== - -Release v \ |version|. (`Impatient? jump to the` :ref:`Installation ` `section!`) - -.. if you change this paragraph, change it in user/intro too -**Bitmask** is the multiplatform desktop client for the services offered by :ref:`the LEAP Platform `. -It is written in python using `PySide`_ and :ref:`licensed under the GPL3 `. -Currently we distribute pre-compiled bundles for Linux and OSX, with Windows -bundles following soon. - -.. _`PySide`: http://qt-project.org/wiki/PySide - -User Guide ----------- - -.. toctree:: - :maxdepth: 2 - - user/intro - user/install - user/running - -Tester Guide ------------- - -This part of the documentation details how to fetch the last development version and how to report bugs. - -.. toctree:: - :maxdepth: 1 - - testers/howto - -Hackers Guide ---------------- - -If you want to contribute to the project, we wrote this for you. - -.. toctree:: - :maxdepth: 1 - - dev/environment - dev/tests - dev/workflow - dev/resources - dev/internationalization - -.. dev/internals - dev/authors - dev/todo - -Packager Guide ---------------- - -Docs related to the process of building and releasing a version of the client. - -.. toctree:: - :maxdepth: 1 - - pkg/debian - pkg/osx - pkg/win - - -Directories and Files ---------------------- - -Different directories and files used for the configuration of the client. - -.. toctree:: - :maxdepth: 1 - - config/files - - -API Documentation ------------------ - -If you are looking for a reference to specific classes or functions, you are likely to find it here. - -.. I should investigate a bit more how to skip some things, and how to give nice format - to the docstrings. - Maybe we should not have sphinx-apidocs building everything, but a minimal index of our own. - -.. toctree:: - :maxdepth: 2 - - api/leap - - diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md new file mode 100644 index 0000000..c788251 --- /dev/null +++ b/docs/client/dev-environment.md @@ -0,0 +1,144 @@ +@nav_title = 'Hacking' +@title = 'Setting up a development environment' + +Setting up a development environment +==================================== + +This document covers how to get an enviroment ready to contribute code +to Bitmask. + +Cloning the repo +---------------- + +> **note** +> +> Stable releases are in *master* branch. Development code lives in +> *develop* branch. + + git clone git://leap.se/bitmask_client + git checkout develop + +Base 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) + +### Debian + +In debian-based systems: + + $ apt-get install openvpn python-pyside python-openssl + +To install the software from sources: + + $ apt-get install python-pip python-dev + +Working with virtualenv +----------------------- + +### Intro + +*Virtualenv* is the *Virtual Python Environment builder*. + +It is a tool to create isolated Python environments. + +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 +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. + +### Create and activate your dev environment + + $ virtualenv + $ source /bin/activate + +### Avoid compiling PySide inside a virtualenv + +If you attempt to install PySide inside a virtualenv as part of the rest +of the dependencies using pip, basically it will take ages to compile. + +As a workaround, you can run the following script after creating your +virtualenv. It will symlink to your global PySide installation (*this is +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 +your virtualenv: + + $ apt-get install python-pyside + $ virtualenv --site-packages . + +After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the +isntallation: + + $ export LEAP_VENV_SKIP_PYSIDE=1 + +And now you are ready to proceed with the next section. + +### Install python dependencies + +You can install python dependencies with `pip`. If you do it inside your +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 & diff --git a/docs/client/dev-guide.md b/docs/client/dev-guide.md deleted file mode 100644 index fb7f0ba..0000000 --- a/docs/client/dev-guide.md +++ /dev/null @@ -1,107 +0,0 @@ -@nav_title = 'Development Guide' -@title = 'Setting up a development environment' - -This document covers how to get an enviroment ready to contribute code to the LEAP Client. - -Cloning the repo -========================== - -> Stable releases will be in *master* branch (nothing there yet, move on!). Development code lives in *develop* branch. - - git clone https://leap.se/git/bitmask_client - -Base Dependencies -========================= - -Leap client depends on these libraries: - -* `python 2.6 or 2.7` -* `qt4` libraries (see below for how to install under virtualenv) -* `openssl` -* [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html) - -Debian -------------- - -In debian-based systems: - - $ apt-get install openvpn python-qt4 python-crypto python-openssl - -To install the software from sources: - - $ apt-get install python-pip python-dev - -Working with virtualenv -=================================== - -Intro -------------------- - -*Virtualenv* is the *Virtual Python Environment builder*. - -It is a tool to create isolated Python environments. - -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 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/). - -Create and activate your dev environment -------------------------------------------------- - - $ virtualenv - $ source /bin/activate - -Install python dependencies ------------------------------------------ - -You can install python dependencies with pip. If you do it inside your working environment, they will be installed avoiding the need for administrative permissions: - - $ pip install -r pkg/requirements.pip - -Troubleshooting PyQt install inside a virtualenv ---------------------------------------------------------------- - -If you attempt to install PyQt inside a virtualenv using pip, it will fail because PyQt4 does not use the standard setup.py mechanism. - -As a workaround, you can run the following script after creating your virtualenv. It will symlink to your global PyQt installation (*this is 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 PyQt globally and pass the `--site-packages` option when you are creating your virtualenv: - - $ apt-get install python-qt4 - $ virtualenv --site-packages . - -Or, if you prefer, you can also `download the official PyQt tarball http://www.riverbankcomputing.com/software/pyqt/download and execute `configure.py` in the root folder of their distribution, which generates a `Makefile`: - - $ python configure.py - $ make && make install - -> this section could be completed with useful options that can be passed to the virtualenv command (e.g., to make portable paths, site-packages, ...). - - -Copy script files -========================== - -The openvpn invocation expects some files to be in place. If you have not installed `leap-client` from a debian package, you must copy these files manually: - - $ 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 the client system-wide, so if you have installed the client in your global site-packages at least once it should have copied this file for you. - -If you *only* are running the client 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 running a desktop other than gnome or unity, you might get an error saying that you are not running the authentication agent. You can launch it like this: - - /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 & diff --git a/docs/client/en.md b/docs/client/en.md index accd7ad..3bfe3f1 100644 --- a/docs/client/en.md +++ b/docs/client/en.md @@ -1,12 +1,40 @@ +@nav_title = "Bitmask" @title = 'Bitmask' @summary = "The Internet Encryption Toolkit: Encrypted Internet Proxy and Encrypted Mail" -**Bitmask** is the multiplatform desktop client for the services offered by the [the LEAP Platform](platform). It is written in python using PySide and licensed under the GPL3. Currently we distribute pre-compiled bundles for Linux and OSX, with Windows bundles following soon. +Bitmask +======= -You can find the complete up-to-date documentation [at the python package documentation site.](http://pythonhosted.org/leap.bitmask "Bitmask documentation") +**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. + +You can find the complete up-to-date documentation [at the python package documentation +site.](http://pythonhosted.org/leap.bitmask "Bitmask documentation") + +We include below some sections of the user guide and the development documentation so +you can get started. + +User Guide +---------- +* [Installing Bitmask](client/user-install) +* [Running Bitmask](client/user-running) + +Tester Guide +------------ + +This part of the documentation details how to fetch the last development +version and how to report bugs. + +* [Howto for testers](client/testers-howto) + +Hackers Guide +------------- + +If you want to contribute to the project, we wrote this for you. + +* [Setting up a development environment](client/dev-environment) -* [Bitmask Documentation index](client/client-index) -* [User guide](client/user-guide)