summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md158
1 files changed, 65 insertions, 93 deletions
diff --git a/README.md b/README.md
index c06ea16a..ceece16d 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Pixelated User Agent
[![Coverage Status](https://coveralls.io/repos/pixelated/pixelated-user-agent/badge.svg?branch=master)](https://coveralls.io/r/pixelated/pixelated-user-agent?branch=master)
[![Stories in Doing](https://badge.waffle.io/pixelated/pixelated-user-agent.svg?label=doing&title=Doing)](http://waffle.io/pixelated/pixelated-user-agent)
-The Pixelated User Agent is the mail client of the Pixelated ecosystem. It is composed of two parts, a web interface written in JavaScript ([FlightJS](https://flightjs.github.io/)) and a Python API that interacts with a LEAP Provider, the e-mail platform that Pixelated is built on.
+The Pixelated User Agent is the email client of the Pixelated ecosystem. It is composed of two parts, a web interface written in JavaScript ([FlightJS](https://flightjs.github.io/) and [React](https://facebook.github.io/react/)) and a Python API that interacts with a [LEAP Provider](https://leap.se/), the email platform that Pixelated is built on.
Here's a [podcast](https://soundcloud.com/thoughtworks/pixelated-why-secure-communication-is-essential) that explains the project.
@@ -39,12 +39,15 @@ $ vagrant up
```
2) Log into the VM:
+* You can access the guest OS shell via the command `vagrant ssh` run within the `pixelated-user-agent/` folder in the host OS.
+* /vagrant/ in the guest OS is mapped to the pixelated-user-agent/ folder in the host OS. File changes on either side will reflect in the other.
```
$ vagrant ssh
$ cd /vagrant
```
+
3) Register with a LEAP provider. You can create a developer account at our [Dev Provider](https://dev.pixelated-project.org/) (Please contact us at team@pixelated-project.org for an invite code) or you can use sample configurations.
4) If you created a developer account follow the step 4a to run the user agent, otherwise go to step 4b:
@@ -75,7 +78,11 @@ Then you can connect to `try.pixelated-project.org` ...
* as Alice via: `$ pixelated-user-agent --host 0.0.0.0 -c try.alice.ini`
* as Bob via: `$ pixelated-user-agent --host 0.0.0.0 -c try.bob.ini`
-5) Go to [localhost:3333](http://localhost:3333/). You should see a loading screen for a few seconds, then your inbox. If it sticks on the loading screen, check your terminal for errors, then [get help](https://pixelated-project.org/faq/#contact-the-project).
+5) Go to [localhost:3333](http://localhost:3333/). You should see a loading screen for a few seconds, then your inbox.
+
+First time email sync could be slow, please be patient. This could be the case if you have a lot of emails already and it is the first time you setup the user agent on your machine.
+
+If it sticks on the loading screen, check your terminal for errors, then [get help](https://pixelated-project.org/faq/#contact-the-project).
6) If you like console output, you can also run the tests to see if everything went according to plan.
@@ -103,7 +110,7 @@ For all **Python changes**, you will need to kill (Ctrl-C) the server and run `$
For most **JavaScript** or **HTML changes**, you will just need to reload the browser.
-For most **CSS or Handlebars templates changes**, you will also need to run: `$ cd /vagrant/web-ui && ./go build`
+For most **CSS or Handlebars templates changes**, you will also need to run: `$ cd /vagrant && make install_js`
## Option 2: Pixelated User Agent + Leap Platform
@@ -117,133 +124,98 @@ You can install the Pixelated User Agent and the Leap Platform at once, just by
NOTE: Be aware that you will not be able to send mails outside, but you can test sending mails internally from one user to another.
-## Running tests
+ ## Developer Setup On Native OS
-[Here](https://github.com/pixelated/pixelated-user-agent/wiki/Running-Tests) you will find informations about how to run Pixelated tests.
+ Please ensure that you have an email user from your preferred leap provider (Step 3).
+ Details for developer installations [on OSX](#on-osx) and [Debian distributions](#on-debian-distributions) are explained below.
-### Running tests on your local machine
-If you want to run the tests in your host machine outside of vagrant:
-```
-$ pip install virtualenv
-$ cd <root/of/pixelated-user-agent>
-$ make test
-```
+ ### On OSX
-If you want to run the tests in your IDE on your host machine outside of vagrant, there's a bug in a LEAP library that can't handle symlinks to your local GPG installation.
-To fix it, add the path to your GPG binary to your $PATH so that it is found before the symlink in `/usr/local/bin` (or similar).
-See also, installations on native OS [below](#developer-setup-on-native-os).
+ First, you will need to install the [GPG tools](https://gpgtools.org/) for Mac.
+ Then, run the following sequence of commands:
+ ```bash
+ $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/osx_setup.sh | sh
+ $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
+ ```
+ Please note that you will have to activate the virtualenv anytime you work on a different terminal. This is done by simply running `$ source ~/.virtualenv/user-agent-venv/bin/activate` first.
-## I think I might be able to hack together a quick-and-dirty lo-fi solution for the issue I’m working with… what do I do?
+ Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
-Do it the easy way first, and submit a pull request as a “work in progress” as soon as you have a quick-and-dirty solution (or even an unfinished solution) — that means you can get feedback from the other developers about whether you’re heading in the right direction sooner rather than later. Include “WIP” (work in progress) in the description of your pull request and ask for review, or feedback on anything specific.
+ ### On Debian distributions
-# Further Notes
+ This is the setup for developers. Please run the following commands:
-## Multi User Mode
+ ```bash
+ $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/debian_setup.sh | bash
+ $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
+ ```
-To run the pixelated user agent multi user mode, please run the following:
-```bash
- vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 --multi-user --provider=dev.pixelated-project.org
-```
-
-You will need to change `dev.pixelated-project.org` to the hostname of the leap provider that you will be using.
-Once that is done, you can use by browsing to [http://localhost:3333](http://localhost:3333), where you will be prompted for your email username and password.
-
-## Config file with credentials
-
-The config file has to be in `ini` format, see for example
-`try.alice.ini` or `try.bob.ini` in the root directory, or this one:
-
-*credentials.ini*
-```
-[pixelated]
-leap_server_name=dev.pixelated-project.org
-leap_username=<your_username>
-leap_password=<your_password>
-```
-To use it start the user agent like this:
-`$ pixelated-user-agent --host 0.0.0.0 --config credentials.ini`
+ Please note that you will have to activate the virtualenv anytime you work on a different terminal. This is done by simply running `$ source ~/.virtualenv/user-agent-venv/bin/activate` first.
-You can also include the host in the config file, as shown in the example files given above.
+ Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
-## Self-signed provider certs
+ ## Debian package
-You might also need to add your LEAP provider ssl certificate to pixelated manually for now, with the following steps:
+ For people that just want to try the user agent, we have debian packages available in our [repository](http://packages.pixelated-project.org/debian/). To use it, you have to add it to your sources list:
-The easiest way to get this is downloading if from https://your.provider.org/ca.crt.
-Rename the certificate based on your provider domain name like this `your.leapprovider.org.crt` and put it into `services/pixelated/certificates/`.
+ ```shell
-## Misc
-* You can access the guest OS shell via the command `vagrant ssh` run within the `pixelated-user-agent/` folder in the host OS.
-* `/vagrant/` in the guest OS is mapped to the `pixelated-user-agent/` folder in the host OS. File changes on either side will reflect in the other.
-* First time email sync could be slow, please be patient. This could be the case if you have a lot of emails already and it is the first time you setup the user agent on your machine.
-* CTRL + \ will stop the server.
-* For all backend changes, you will need to stop and restart the server again (Step 5 above).
-* For most frontend changes, you will just need to reload the browser. Some changes (in particular, those involving css or handlebars) you will need to run:
-```bash
- vagrant@jessie:/vagrant$ make install_js
-```
+ echo "deb [arch=amd64] http://packages.pixelated-project.org/debian jessie-snapshots main" > /etc/apt/sources.list.d/pixelated.list
-## Developer Setup On Native OS
+ apt-key adv --keyserver pool.sks-keyservers.net --recv-key 287A1542472DC0E3
-Please ensure that you have an email user from your preferred leap provider (Step 3).
-Details for developer installations [on OSX](#on-osx) and [Debian distributions](#on-debian-distributions) are explained below.
-In case of any issues, please ping us on IRC ([#pixelated on irc.freenode.net](irc://irc.freenode.net/pixelated)), we will be available to help you from there.
+ apt-get update
-### On OSX
+ apt-get install pixelated-user-agent
+ ```
-First, you will need to install the [GPG tools](https://gpgtools.org/) for Mac.
-Then, run the following sequence of commands:
-```bash
-$ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/osx_setup.sh | sh
-$ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
-```
+ for multi-user mode, change the last line above to
+ ```shell
+ apt-get install pixelated-server
+ ```
-Please note that you will have to activate the virtualenv anytime you work on a different terminal. This is done by simply running `$ source ~/.virtualenv/user-agent-venv/bin/activate` first.
+## Running tests
-Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
+[Here](https://github.com/pixelated/pixelated-user-agent/wiki/Running-Tests) you will find informations about how to run Pixelated tests.
-### On Debian distributions
+# Further Notes
-This is the setup for developers. Please run the following commands:
+## Multi User Mode
+To run the pixelated user agent multi user mode, please run the following:
```bash
-$ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/debian_setup.sh | bash
-$ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
+ vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 --multi-user --provider=dev.pixelated-project.org
```
-Please note that you will have to activate the virtualenv anytime you work on a different terminal. This is done by simply running `$ source ~/.virtualenv/user-agent-venv/bin/activate` first.
-
-Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
-
-## Debian package
-
-For people that just want to try the user agent, we have debian packages available in our [repository](http://packages.pixelated-project.org/debian/). To use it, you have to add it to your sources list:
-
-```shell
-
-echo "deb [arch=amd64] http://packages.pixelated-project.org/debian jessie-snapshots main" > /etc/apt/sources.list.d/pixelated.list
+You will need to change `dev.pixelated-project.org` to the hostname of the leap provider that you will be using.
+Once that is done, you can use by browsing to [http://localhost:3333](http://localhost:3333), where you will be prompted for your email username and password.
-apt-key adv --keyserver pool.sks-keyservers.net --recv-key 287A1542472DC0E3
+## Config file with credentials
-apt-get update
+Create a config file with `ini` format in the root directory, see the example:
-apt-get install pixelated-user-agent
+*credentials.ini*
```
-
-for multi-user mode, change the last line above to
-```shell
-apt-get install pixelated-server
+[pixelated]
+HOST=0.0.0.0
+PORT=8080
+leap_server_name=<your_provider>
+leap_username=<your_username>
+leap_password=<your_password>
```
+Host and port is optional.
+
+To use it, start the user agent like this:
+`$ pixelated-user-agent --host 0.0.0.0 --config credentials.ini`
-## Docker
-For people who want to run the user agent on docker container can use the Dockerfile.
## How to translate the user interface
See: [Translating Pixelated](https://github.com/pixelated/pixelated-user-agent/wiki/Translating-Pixelated)
+## More informations
+Read the [wiki pages](https://github.com/pixelated/pixelated-user-agent/wiki)