1c2fae2f6e34e82c5b93b0ed1df1156a9fd7f219
[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 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.
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 ## Try it!
17
18 If you are curious,  have a look at the pixelated web client, it as simple as clicking *[here!](https://try.pixelated-project.org:8080/)*
19
20 ## Getting started
21
22 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).
23
24 ## Installing Pixelated
25
26 To run your own instance of Pixelated, follow these instructions: https://github.com/pixelated/puppet-pixelated#manual-installation
27
28 ## Development
29
30 You like the idea and you want to run it locally, then before you have to install the following packages:
31
32 * [Vagrant](https://www.vagrantup.com/downloads.html), Vagrant is a tool that automates the setup of a virtual machine with the development environment
33 * A vagrant [compatible provider](https://www.vagrantup.com/docs/providers/), e.g. [Virtual Box](https://www.virtualbox.org/wiki/Downloads).
34
35 ### Option 1: Pixelated User Agent without LEAP provider
36
37 1) Clone the repo and start the virtual machine (downloads 600MB, you may want get a coffee or tea in the meantime):
38
39 ```
40 $ git clone https://github.com/pixelated/pixelated-user-agent.git
41 $ cd pixelated-user-agent
42 $ vagrant up
43 ```
44
45 2) Log into the VM:
46
47 ```
48 $ vagrant ssh
49 $ cd /vagrant
50 ```
51
52 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.
53
54 4) If you created a developer account follow the step 4a to run the user agent, otherwise go to step 4b:
55
56 4a) Connect to the provider using your credentials. If the user agent starts up successfully, you will not see any other output.
57
58 ```
59 $ pixelated-user-agent --host 0.0.0.0
60
61 Which provider do you want to connect to:
62 dev.pixelated-project.org
63
64 What’s your username registered on the provider:
65 username (the one you created in previous step)
66
67 Type your password:
68 ******** (the one you created in previous step)
69 ```
70
71 **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)).
72
73 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.
74
75 Please navigate to the project root in your vagrant box with: `$ cd /vagrant`
76
77 Then you can connect to `try.pixelated-project.org` ...
78
79 * as Alice via: `$ pixelated-user-agent --host 0.0.0.0 -c try.alice.ini`
80 * as Bob via: `$ pixelated-user-agent --host 0.0.0.0 -c try.bob.ini`
81
82 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).
83
84 6) If you like console output, you can also run the tests to see if everything went according to plan.
85
86 ```bash
87   vagrant@jessie:~ $ cd /vagrant
88 ```
89
90 To run the tests:
91
92 ```bash
93   vagrant@jessie:/vagrant $ make test
94 ```
95
96 To run the functional tests:
97
98 ```bash
99   vagrant@jessie:/vagrant $ make functional_tests
100 ```
101
102 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!
103
104 ## How do I see the result of my changes?
105
106 For all **Python changes**, you will need to kill (Ctrl-C) the server and run `$ pixelated-user-agent --host 0.0.0.0` again.
107
108 For most **JavaScript** or **HTML changes**, you will just need to reload the browser.
109
110 For most **CSS or Handlebars templates changes**, you will also need to run: `$ cd /vagrant/web-ui && ./go build`
111
112 ## Option 2: Pixelated User Agent + Leap Platform
113
114 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):
115
116 ```bash
117  curl https://raw.githubusercontent.com/pixelated/puppet-pixelated/master/vagrant_platform.sh | sh
118 ```
119
120  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/).
121
122  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.
123
124 ## Running tests
125
126 [Here](https://github.com/pixelated/pixelated-user-agent/wiki/Running-Tests) you will find informations about how to run Pixelated tests.
127
128 ### Running tests on your local machine
129 If you want to run the tests in your host machine outside of vagrant:
130
131 ```
132 $ pip install virtualenv
133 $ cd <root/of/pixelated-user-agent>
134 $ make test
135 ```
136
137 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.
138 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).
139 See also, installations on native OS [below](#developer-setup-on-native-os).
140
141
142 ## 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?
143
144 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.
145
146 # Further Notes
147
148 ## Multi User Mode
149
150 To run the pixelated user agent multi user mode, please run the following:
151 ```bash
152  vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 --multi-user --provider=dev.pixelated-project.org
153 ```
154
155 You will need to change `dev.pixelated-project.org` to the hostname of the leap provider that you will be using.
156 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.
157
158 ## Config file with credentials
159
160 The config file has to be in `ini` format, see for example
161 `try.alice.ini` or `try.bob.ini` in the root directory, or this one:
162
163 *credentials.ini*
164 ```
165 [pixelated]
166 leap_server_name=dev.pixelated-project.org
167 leap_username=<your_username>
168 leap_password=<your_password>
169 ```
170 To use it start the user agent like this:
171 `$ pixelated-user-agent --host 0.0.0.0 --config credentials.ini`
172
173 You can also include the host in the config file, as shown in the example files given above.
174
175 ## Self-signed provider certs
176
177 You might also need to add your LEAP provider ssl certificate to pixelated manually for now, with the following steps:
178
179 The easiest way to get this is downloading if from https://your.provider.org/ca.crt.
180 Rename the certificate based on your provider domain name like this `your.leapprovider.org.crt` and put it into `services/pixelated/certificates/`.
181
182 ## Misc
183 * You can access the guest OS shell via the command `vagrant ssh` run within the `pixelated-user-agent/` folder in the host OS.
184 * `/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.
185 * 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.
186 * CTRL + \ will stop the server.
187 * For all backend changes, you will need to stop and restart the server again (Step 5 above).
188 * 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:
189 ```bash
190   vagrant@jessie:/vagrant$ make install_js
191 ```
192
193 ## Developer Setup On Native OS
194
195 Please ensure that you have an email user from your preferred leap provider (Step 3).
196 Details for developer installations [on OSX](#on-osx) and [Debian distributions](#on-debian-distributions) are explained below.
197 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.
198
199 ### On OSX
200
201 First, you will need to install the [GPG tools](https://gpgtools.org/) for Mac.
202 Then, run the following sequence of commands:
203 ```bash
204 $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/osx_setup.sh | sh
205 $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
206 ```
207
208 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.
209
210 Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
211
212 ### On Debian distributions
213
214 This is the setup for developers. Please run the following commands:
215
216 ```bash
217 $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/debian_setup.sh | bash
218 $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
219 ```
220
221 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.
222
223 Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
224
225 ## Debian package
226
227 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:
228
229 ```shell
230
231 echo "deb [arch=amd64] http://packages.pixelated-project.org/debian jessie-snapshots main" > /etc/apt/sources.list.d/pixelated.list
232
233 apt-key adv --keyserver pool.sks-keyservers.net --recv-key 287A1542472DC0E3
234
235 apt-get update
236
237 apt-get install pixelated-user-agent
238 ```
239
240 for multi-user mode, change the last line above to
241 ```shell
242 apt-get install pixelated-server
243 ```
244
245 ## Docker
246
247 For people who want to run the user agent on docker container can use the Dockerfile.
248
249 ## How to translate the user interface
250
251 See: [Translating Pixelated](https://github.com/pixelated/pixelated-user-agent/wiki/Translating-Pixelated)
252
253