From e53e113dcde3e3686095c3661307efccc5c7e64e Mon Sep 17 00:00:00 2001 From: elijah Date: Wed, 18 Feb 2015 23:44:14 -0800 Subject: initial conversation from leap_doc and leap_website --- pages/docs/client/bundle-testing.md | 101 ++++++++++++++++++ pages/docs/client/dev-environment.md | 200 +++++++++++++++++++++++++++++++++++ pages/docs/client/en.md | 57 ++++++++++ pages/docs/client/known-issues.md | 64 +++++++++++ pages/docs/client/testers-howto.md | 131 +++++++++++++++++++++++ pages/docs/client/user-install.md | 30 ++++++ pages/docs/client/user-running.md | 42 ++++++++ 7 files changed, 625 insertions(+) create mode 100644 pages/docs/client/bundle-testing.md create mode 100644 pages/docs/client/dev-environment.md create mode 100644 pages/docs/client/en.md create mode 100644 pages/docs/client/known-issues.md create mode 100644 pages/docs/client/testers-howto.md create mode 100644 pages/docs/client/user-install.md create mode 100644 pages/docs/client/user-running.md (limited to 'pages/docs/client') diff --git a/pages/docs/client/bundle-testing.md b/pages/docs/client/bundle-testing.md new file mode 100644 index 0000000..24890b0 --- /dev/null +++ b/pages/docs/client/bundle-testing.md @@ -0,0 +1,101 @@ +@nav_title = "Bundle QA" +@title = "Guidelines for bundle QA" + +Recommended setup +----------------- + +VirtualBox (or similar) with virtual machines installed for supported OSs + +For each system that you are going to test, you should do: + +- Install the VM +- Restart the VM and check that the process is finished. +- Turn it off and make a snapshot named 'fresh install' or similar. + +The OS should be installed with the default settings and no extra packages. However, you can choose your language, username, timezone, etc + + +Test process +------------ + +- roll back the virtual machine to its *fresh install* state, to make sure that you're testing against a reproducible environment. +- download the bundle, verify signature (if apply), extract and run the app +- test the application (see next section) + + +Tests to do +----------- + +- **check if the version number is the same as the current bundle version** + - 'Help->About Bitmask' + - `./bitmask --version` +- **correct installation of files to 'better protect privacy'** + - `/etc/leap/resolv-update` + - `/usr/share/polkit-1/actions/net.openvpn.gui.leap.policy` + + You should check that they get copied when the user says 'yes' and they don't get copied if the user says 'no'. +- **installation of tun/tap in Windows and MAC** + TODO: explain more here + +- **account creation** + + Recommended username template: test_bundleversion_os_arch, that way you avoid conflicts between test iterations. + e.g.: 'test_036_debian7_64', 'test_036_win7_32', etc + + If you need to create extra users in order to test a bug or whatever, you can use 'test_036_ubuntu1204_32a', 'test_036_ubuntu1204_32b', etc + + In case of being a lot of users testing a version you may want to use your username instead of test, e.g.: 'johndoe_036_ubuntu1204_32'. +- **eip connection** + + You can check if the vpn is working entering to the site: http://wtfismyip.com + + or using the console: + `shell> wget -qO- wtfismyip.com/json` +- **Soledad key generation** +- **Thunderbird configuration manually and using add-on** +- **Send and receive mail** + + You need to test communication between inside and outside users, e.g.: someuser@bitmask.net and otheruser@gmail.com + + A good thing to do is to subscribe to a mailing list that have a lot of activity. + +- **Check if the account data is correctly synced.** + + After the account creation, have everything working and the app closed: + - remove the configuration files created by the app (`~/.config/leap` in linux) + - log in with your recently created credentials and check that everything is working and your mails are there too. + + +Problems report +--------------- + +You should to create an issue with the followinw information: + +- OS, version, architecture, desktop environment (if relevant). +- bitmask.log file located in the root folder of the uncompressed bundle +- steps to reproduce + +If you find a problem, try to reproduce and take note of the steps needed to get the same error. + +Also, in some cases, a failure appears but if you run again is not there anymore (e.g.: some initialization issue), please report that too. + +For more details look at [Reporting bugs](client/testers-howto) section. + + +Utils +----- + +Download, extract and run helper script for linux: + + shell> ./download-extract-run-bitmask.sh + +Script contents: + + #!/bin/bash + HOST="https://dl.bitmask.net/client/linux/" + VERSION="0.3.7" + # FOLDER="Bitmask-linux32-${VERSION}" + FOLDER="Bitmask-linux64-${VERSION}" + FILE="${FOLDER}.tar.bz2" + + wget ${HOST}${FILE} && tar xjf ${FILE} && cd ${FOLDER} && ./bitmask diff --git a/pages/docs/client/dev-environment.md b/pages/docs/client/dev-environment.md new file mode 100644 index 0000000..b41e7af --- /dev/null +++ b/pages/docs/client/dev-environment.md @@ -0,0 +1,200 @@ +@nav_title = 'Hacking' +@title = 'Setting up a development environment' + +Quick start +=========== + +This document will guide you to get an environment ready to contribute code to +Bitmask. + +Using an automagic script +========================= + +You can use a helper script that will get you started with bitmask and all the +related repos. + +1. download automagic script +2. 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 help # check out the options :) + $ ./bootstrap_develop.sh deps # requires sudo + $ ./bootstrap_develop.sh init ro + $ ./bootstrap_develop.sh helpers # requires sudo + $ ./bootstrap_develop.sh run + +This script allows you to get started, update and run the bitmask app with all +its repositories. + +Note: the `deps` option is meant to be used in a Debian based Linux distro. + + +Doing the work manually +======================= + +Clone the repo +-------------- + +> **note** +> +> Stable releases are in *master* branch. Development code lives in +> *develop* branch. + + git clone https://leap.se/git/bitmask_client + git checkout develop + +Install Dependencies +-------------------- + +Bitmask depends on these libraries: + +- python 2.6 or 2.7 +- qt4 libraries +- openssl +- [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html) + +### Install dependencies in a Debian based distro + +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 + + +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://www.virtualenv.org/en/latest/virtualenv.html). + +### Create and activate your dev environment + +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 + +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 `--system-site-packages` option when you are creating +your virtualenv: + + $ apt-get install python-pyside + $ virtualenv --system-site-packages . + +After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the +installation: + + $ 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 + +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 --always-unzip + +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. + +Note: the `--always-unzip` option prevents some dependencies to be installed in +a zip/egg, which causes some issues with libraries like 'scrypt' that needs to +access to the files directly from the filesystem. + +Compile Qt resources +-------------------- + +We also need to compile the resource files: + + (bitmask)$ make + +Note: you need to repeat this step each time you change a `.ui` file. + +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/se.leap.bitmask.policy /usr/share/polkit-1/actions/ + +Installing the bitmask EIP helper +--------------------------------- + +In linux, we have a `openvpn` and `firewall` helper that is needed to run EIP. +You need to manually copy it from `bitmask_client/pkg/linux/bitmask-root`. +Use the following command to do so: + + $ sudo cp bitmask_client/pkg/linux/bitmask-root /usr/sbin/ + + +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 diff --git a/pages/docs/client/en.md b/pages/docs/client/en.md new file mode 100644 index 0000000..15c55bf --- /dev/null +++ b/pages/docs/client/en.md @@ -0,0 +1,57 @@ +@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 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. + +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) + + + + + +Supported OSs +------------- + +We currently support: + +### Through the bundle + +* Debian 7 +* Ubuntu 12.04 (LTS) +* Ubuntu 14.04 (LTS) +* Ubuntu 14.10 (latest) +* Mac OSX >= 10.8 (coming very soon) +* Note: It *should* work in other Debian based distros + +### Through the debian package + +* Ubuntu 14.04 (Trusty Tahr) +* Ubuntu 14.10 (Utopic Unicorn) coming very soon +* Debian 7.0 (Wheezy) +* Debian 8.0 (Jessie) diff --git a/pages/docs/client/known-issues.md b/pages/docs/client/known-issues.md new file mode 100644 index 0000000..e1507d7 --- /dev/null +++ b/pages/docs/client/known-issues.md @@ -0,0 +1,64 @@ +@title = 'Bitmask known issues' +@nav_title = 'Known issues' +@summary = 'Known issues in Bitmask.' +@toc = true + +Here you can find documentation about known issues and potential work-arounds +in the current Leap Platform release. + +No polkit agent available +------------------------- + +To run Bitmask and the services correctly you need to have a running polkit +agent. If you don't have one you will get an error and won't be able to start +Bitmask. + +The currently recognized polkit agents are: + +| process name | Who uses it? | +|---------------------------------------|-----------------------------------| +| `polkit-gnome-authentication-agent-1` | Gnome | +| `polkit-kde-authentication-agent-1` | KDE | +| `polkit-mate-authentication-agent-1` | Mate | +| `lxpolkit` | LXDE | +| `gnome-shell` | Gnome shell | +| `fingerprint-polkit-agent` | the `fingerprint-gui` package | + + +If you have a different polkit agent running that it's not in theat list, +please report a bug so we can include in our checks. + +You can get the list of running processes that match polkit with the following +command: `ps aux | grep -i polkit`. +Here is an example on my KDE desktop: + + ➜ ps aux | grep polkit + root 1392 0.0 0.0 298972 6120 ? Sl Sep22 0:02 /usr/lib/policykit-1/polkitd --no-debug + user 1702 0.0 0.0 12972 920 pts/16 S+ 16:42 0:00 grep polkit + user 3259 0.0 0.4 559764 38464 ? Sl Sep22 0:05 /usr/lib/kde4/libexec/polkit-kde-authentication-agent-1 + + +Other Issues +------------ + +- You may get the error: "Unable to connect: Problem with provider" in + situations when the problem is the network instead of the provider. + See: https://leap.se/code/issues/4023 + +Mail issues +----------- + +Note that email is not stable yet so this list may not be accurate. + +- If you have received a big ammount of mails (tested with more than 400), you + may experience that Thunderbird won't respond. + +That problem does not happen if you have the client open and Thunderbird +loading mails while are reaching your inbox. + + +- Opening the same account from more than one box at the same time will + possibly break your account. + +- Managing a huge ammount of mails (e.g.: moving mails to a folder) will block + the UI (see https://leap.se/code/issues/4837) diff --git a/pages/docs/client/testers-howto.md b/pages/docs/client/testers-howto.md new file mode 100644 index 0000000..9e6ff7d --- /dev/null +++ b/pages/docs/client/testers-howto.md @@ -0,0 +1,131 @@ +@nav_title = "Testing" +@title = "Howto for Testers" + +This document covers a how-to guide to: + +1. Where and how report bugs for Bitmask \, and +2. Quickly fetching latest development code \. + +Let's go! + +Reporting bugs +-------------- + +Report all the bugs you can find to us! If something is not quite +working yet, we really want to know. Reporting a bug to us is the best +way to get it fixed quickly, and get our unconditional gratitude. + +It is quick, easy, and probably the best way to contribute to Bitmask +development, other than submitting patches. + +> **Reporting better bugs** +> +> New to bug reporting? Here you have a [great document about this noble +> art](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html). + +### Where to report bugs + +We use the [Bitmask Bug +Tracker](https://leap.se/code/projects/eip-client), although you can +also use [Github +issues](https://github.com/leapcode/bitmask_client/issues). But we +reaaaally prefer if you sign up in the former to send your bugs our way. + +### What to include in your bug report + +- The symptoms of the bug itself: what went wrong? What items appear + broken, or do not work as expected? Maybe an UI element that appears + to freeze? +- The Bitmask version you are running. You can get it by doing bitmask + --version, or you can go to Help -\> About Bitmask menu. +- The installation method you used: bundle? from source code? debian + package? +- Your platform version and other details: Ubuntu 12.04? Debian + unstable? Windows 8? OSX 10.8.4? If relevant, your desktop system + also (gnome, kde...) +- When does the bug appear? What actions trigger it? Does it always + happen, or is it sporadic? +- The exact error message, if any. +- Attachments of the log files, if possible (see section below). + +Also, try not to mix several issues in your bug report. If you are +finding several problems, it's better to issue a separate bug report for +each one of them. + +### Attaching log files + +If you can spend a little time getting them, please add some logs to the +bug report. They are **really** useful when it comes to debug a problem. +To do it: + +Launch Bitmask in debug mode. Logs are way more verbose that way: + + bitmask --debug + +Get your hand on the logs. You can achieve that either by clicking on +the "Show log" button, and saving to file, or directly by specifying the +path to the logfile in the command line invocation: + + bitmask --debug --logfile /tmp/bitmask.log + +Attach the logfile to your bug report. + +### Need human interaction? + +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&uio=d4). + +Fetching latest development code +-------------------------------- + +Normally, testing the latest client bundles \ should +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 +before the next release is out (if you are testing a new provider, for +instance), you are encouraged to try out the latest in the development +branch. If you do not know how to do that, or you prefer an automated +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. Check it out in 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. + +> **note** +> +> At some point in the near future, we will be using standalone bundles +> \ with the ability to self-update. + +### Local config files + +If you want to start fresh without config files, just move them. In +linux: + + mv ~/.config/leap ~/.config/leap.old + +### Testing the packages + +When we have a release candidate for the supported platforms, 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 bitmask 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 bitmask + +for running Bitmask with the spanish locales. diff --git a/pages/docs/client/user-install.md b/pages/docs/client/user-install.md new file mode 100644 index 0000000..173a9c5 --- /dev/null +++ b/pages/docs/client/user-install.md @@ -0,0 +1,30 @@ +@nav_title = 'Installing' +@title = 'Installing Bitmask' + +For download links and installation instructions go to https://dl.bitmask.net/ + +Distribute & Pip +---------------- + +**Note** + +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 + +Show me the code! +----------------- + +For the brave souls that can find their way through python packages, you can +get the code from LEAP public git repository : + + $ git clone https://leap.se/git/bitmask_client + +Or from the github mirror : + + $ git clone https://github.com/leapcode/bitmask_client.git + +For more information go to the [Hacking](client/dev-environment) section :) + diff --git a/pages/docs/client/user-running.md b/pages/docs/client/user-running.md new file mode 100644 index 0000000..2fda469 --- /dev/null +++ b/pages/docs/client/user-running.md @@ -0,0 +1,42 @@ +@nav_title = 'Running' +@title = 'Running Bitmask' + +This document covers how to launch Bitmask. Also know as, where the +magic happens. + +Launching Bitmask +----------------- + +After a successful installation, there should be a launcher called +bitmask somewhere in your path: + + % bitmask + +The first time you launch it, it should launch the first run wizard that +will guide you through the mostly automatic configuration of the LEAP +Services. + +> **note** +> +> You will need to enter a valid test provider running the LEAP +> Platform. You can use the LEAP test service, ** + +Debug mode +---------- + +If you are happy having lots of output in your terminal, you will like +to know that you can run bitmask in debug mode: + + $ bitmask --debug + +If you ask for it, you can also have all that debug info in a beautiful +file ready to be attached to your bug reports: + + $ bitmask --debug --logfile /tmp/leap.log + +I want all the options! +----------------------- + +To see all the available command line options: + + $ bitmask --help -- cgit v1.2.3