initial conversation from leap_doc and leap_website

7 files changed, 625 insertions, 0 deletions

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)
+
+
+<!--
+* [Running latest code](client/bleeding-edge)
+* [Getting started with development](client/dev-guide)
+* [Configuration](client/configuration)
+* [Client API](client/client-api) -->
+
+
+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 \<reporting\_bugs\>, and
+2.  Quickly fetching latest development code \<fetchinglatest\>.
+
+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 \<standalone-bundle\> 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
+> \<standalone-bundle\> 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, *<https://bitmask.net>*
+
+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