Updating readme
[pixelated-user-agent.git] / README.md
1 Pixelated User Agent
2 ====================
3
4 [![CircleCI](https://circleci.com/gh/pixelated/pixelated-user-agent.svg?style=svg)](https://circleci.com/gh/pixelated/pixelated-user-agent)
5 [![Coverage Status](https://coveralls.io/repos/pixelated/pixelated-user-agent/badge.svg?branch=master)](https://coveralls.io/r/pixelated/pixelated-user-agent?branch=master)
6 [![Stories in Doing](https://badge.waffle.io/pixelated/pixelated-user-agent.svg?label=doing&title=Doing)](http://waffle.io/pixelated/pixelated-user-agent)
7
8 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.
9
10 Here's a [podcast](https://soundcloud.com/thoughtworks/pixelated-why-secure-communication-is-essential) that explains the project.
11
12 **Pixelated is still in early development state!**
13
14 ![High level architecture User Agent](https://raw.githubusercontent.com/pixelated/website/master/assets/images/pixelated-user-agent.png)
15
16 ## Getting started
17
18 You are most welcome to contribute to the pixelated user agent code base. Please have a look at the [contributions how to](https://github.com/pixelated/pixelated-user-agent/blob/master/CONTRIBUTING.md).
19
20 ## Installing Pixelated
21
22 To run your own instance of Pixelated, follow these instructions: https://github.com/pixelated/puppet-pixelated#manual-installation
23
24 ## Development
25
26 You like the idea and you want to run it locally, then before you have to install the following packages:
27
28 * [Vagrant](https://www.vagrantup.com/downloads.html), Vagrant is a tool that automates the setup of a virtual machine with the development environment
29 * A vagrant [compatible provider](https://www.vagrantup.com/docs/providers/), e.g. [Virtual Box](https://www.virtualbox.org/wiki/Downloads).
30
31 ### Option 1: Pixelated User Agent without LEAP provider
32
33 1) Clone the repo and start the virtual machine (downloads 600MB, you may want get a coffee or tea in the meantime):
34
35 ```
36 $ git clone https://github.com/pixelated/pixelated-user-agent.git
37 $ cd pixelated-user-agent
38 $ vagrant up
39 ```
40
41 2) Log into the VM:
42 * You can access the guest OS shell via the command `vagrant ssh` run within the `pixelated-user-agent/` folder in the host OS.
43 * /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.
44
45 ```
46 $ vagrant ssh
47 $ cd /vagrant
48 ```
49
50
51 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.
52
53 4) If you created a developer account follow the step 4a to run the user agent, otherwise go to step 4b:
54
55 4a) Connect to the provider using your credentials. If the user agent starts up successfully, you will not see any other output.
56
57 ```
58 $ pixelated-user-agent --host 0.0.0.0
59
60 Which provider do you want to connect to:
61 dev.pixelated-project.org
62
63 What’s your username registered on the provider:
64 username (the one you created in previous step)
65
66 Type your password:
67 ******** (the one you created in previous step)
68 ```
69
70 **Note**: For more convenience during development, you can also create a config file with your credentials (see [**Further Notes**](https://github.com/pixelated/pixelated-user-agent/blob/master/README.md#further-notes)).
71
72 4b) If you don't have a `dev.pixelated-project.org` account or just want to connect to our `try.pixelated-project.org` environment, we have some sample configurations for you.
73
74 Please navigate to the project root in your vagrant box with: `$ cd /vagrant`
75
76 Then you can connect to `try.pixelated-project.org` ...
77
78 * as Alice via: `$ pixelated-user-agent --host 0.0.0.0 -c try.alice.ini`
79 * as Bob via: `$ pixelated-user-agent --host 0.0.0.0 -c try.bob.ini`
80
81 5) Go to [localhost:3333](http://localhost:3333/). You should see a loading screen for a few seconds, then your inbox.
82
83 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.
84
85 If it sticks on the loading screen, check your terminal for errors, then [get help](https://pixelated-project.org/faq/#contact-the-project).
86
87 6) If you like console output, you can also run the tests to see if everything went according to plan.
88
89 ```bash
90   vagrant@jessie:~ $ cd /vagrant
91 ```
92
93 To run the tests:
94
95 ```bash
96   vagrant@jessie:/vagrant $ make test
97 ```
98
99 To run the functional tests:
100
101 ```bash
102   vagrant@jessie:/vagrant $ make functional_tests
103 ```
104
105 7) You're all set! We've prepared [a couple of issues labeled "Volunteer Task"](https://github.com/pixelated/pixelated-user-agent/labels/Volunteer%20task) that are a good place to dive into the project. Happy Hacking!
106
107 ## How do I see the result of my changes?
108
109 For all **Python changes**, you will need to kill (Ctrl-C) the server and run `$ pixelated-user-agent --host 0.0.0.0` again.
110
111 For most **JavaScript** or **HTML changes**, you will just need to reload the browser.
112
113 For most **CSS or Handlebars templates changes**, you will also need to run: `$ cd /vagrant && make install_js`
114
115 ## Option 2: Pixelated User Agent + Leap Platform
116
117 You can install the Pixelated User Agent and the Leap Platform at once, just by running the following command on your console (this may take a while, please be patient):
118
119 ```bash
120  curl https://raw.githubusercontent.com/pixelated/puppet-pixelated/master/vagrant_platform.sh | sh
121 ```
122
123  Once installed, you can create accounts by visiting the LEAP Webapp at [localhost:4443/signup](https://localhost:4443/signup) and see Pixelated in action at [localhost:8080](https://localhost:8080/).
124
125  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.
126
127  ## Developer Setup On Native OS
128
129  Please ensure that you have an email user from your preferred leap provider (Step 3).
130  Details for developer installations [on OSX](#on-osx) and [Debian distributions](#on-debian-distributions) are explained below.
131
132
133  ### On OSX
134
135  First, you will need to install the [GPG tools](https://gpgtools.org/) for Mac.
136  Then, run the following sequence of commands:
137  ```bash
138  $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/osx_setup.sh | sh
139  $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
140  ```
141
142  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.
143
144  Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
145
146  ### On Debian distributions
147
148  This is the setup for developers. Please run the following commands:
149
150  ```bash
151  $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/debian_setup.sh | bash
152  $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
153  ```
154
155  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.
156
157  Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
158
159  ## Debian package
160
161  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:
162
163  ```shell
164
165  echo "deb [arch=amd64] http://packages.pixelated-project.org/debian jessie-snapshots main" > /etc/apt/sources.list.d/pixelated.list
166
167  apt-key adv --keyserver pool.sks-keyservers.net --recv-key 287A1542472DC0E3
168
169  apt-get update
170
171  apt-get install pixelated-user-agent
172  ```
173
174  for multi-user mode, change the last line above to
175  ```shell
176  apt-get install pixelated-server
177  ```
178
179 ## Running tests
180
181 [Here](https://github.com/pixelated/pixelated-user-agent/wiki/Running-Tests) you will find informations about how to run Pixelated tests.
182
183 # Further Notes
184
185 ## Multi User Mode
186
187 To run the pixelated user agent multi user mode, please run the following:
188 ```bash
189  vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 --multi-user --provider=dev.pixelated-project.org
190 ```
191
192 You will need to change `dev.pixelated-project.org` to the hostname of the leap provider that you will be using.
193 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.
194
195 ## Config file with credentials
196
197 Create a config file with `ini` format in the root directory, see the example:
198
199 *credentials.ini*
200 ```
201 [pixelated]
202 HOST=0.0.0.0
203 PORT=8080
204 leap_server_name=<your_provider>
205 leap_username=<your_username>
206 leap_password=<your_password>
207 ```
208 Host and port is optional.
209
210 To use it, start the user agent like this:
211 `$ pixelated-user-agent --host 0.0.0.0 --config credentials.ini`
212
213
214
215 ## How to translate the user interface
216
217 See: [Translating Pixelated](https://github.com/pixelated/pixelated-user-agent/wiki/Translating-Pixelated)
218
219 ## More informations
220
221 Read the [wiki pages](https://github.com/pixelated/pixelated-user-agent/wiki)