2bb481d9c092977d23e474bb30d051e6730caf16
[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 If you want to run and test it locally, then before you have to install the following dependencies:
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: Run Pixelated User Agent against an existing LEAP provider
32
33 1) If you don't have access to an existing LEAP provider, you can create an account at [Bitmask mail demo provider](https://mail.bitmask.net/).
34
35 2) Clone the Pixelated User Agent repo and start the virtual machine (downloads 600MB, you may want get a coffee or tea in the meantime):
36
37 ```
38 $ git clone https://github.com/pixelated/pixelated-user-agent.git
39 $ cd pixelated-user-agent
40 $ vagrant up
41 ```
42
43 3) Log into the VM:
44 * You can access the guest OS shell via the command `vagrant ssh` run within the `pixelated-user-agent/` folder in the host OS.
45 * /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.
46
47 ```
48 $ vagrant ssh
49 $ cd /vagrant
50 ```
51
52 4) Start the pixelated user agent:
53
54 ```
55 $ pixelated-user-agent --host 0.0.0.0 --multi-user --provider=mail.bitmask.net
56 ```
57
58 5) Go to [localhost:3333](http://localhost:3333/) on your browser. You should see the login screen, where you can put your username and password created on step 1. Once you login, you'll see your inbox.
59
60 First time email sync could be slow, please be patient. This could be the case if you have a lot of emails and it is the first time you setup the user agent on your machine.
61
62 #### How do I see the result of my changes?
63
64 For all **Python changes**, you will need to kill (Ctrl-C) the server and start the pixelated user agent again.
65
66 For most **JavaScript** or **HTML changes**, you will just need to reload the browser.
67
68 For most **CSS or Handlebars templates changes**, you will also need to run: `$ cd /vagrant && make install_js`
69
70 ### Option 2: Pixelated User Agent + Leap Platform
71
72 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):
73
74 ```bash
75  curl https://raw.githubusercontent.com/pixelated/puppet-pixelated/master/vagrant_platform.sh | sh
76 ```
77
78  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/).
79
80  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.
81
82  ## Developer Setup On Native OS
83
84  Please ensure that you have an email user from your preferred leap provider (Step 3).
85  Details for developer installations [on OSX](#on-osx) and [Debian distributions](#on-debian-distributions) are explained below.
86
87
88  ### On OSX
89
90  First, you will need to install the [GPG tools](https://gpgtools.org/) for Mac.
91  Then, run the following sequence of commands:
92  ```bash
93  $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/osx_setup.sh | sh
94  $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
95  ```
96
97  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.
98
99  Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
100
101  ### On Debian distributions
102
103  This is the setup for developers. Please run the following commands:
104
105  ```bash
106  $ curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/debian_setup.sh | bash
107  $ cd pixelated-user-agent && source ~/.virtualenv/user-agent-venv/bin/activate
108  ```
109
110  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.
111
112  Running the user agent and the various tests are the same as in the vagrant setup in step 4) and 6) above.
113
114  ## Debian package
115
116  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:
117
118  ```shell
119
120  echo "deb [arch=amd64] http://packages.pixelated-project.org/debian jessie-snapshots main" > /etc/apt/sources.list.d/pixelated.list
121
122  apt-key adv --keyserver pool.sks-keyservers.net --recv-key 287A1542472DC0E3
123
124  apt-get update
125
126  apt-get install pixelated-user-agent
127  ```
128
129  for multi-user mode, change the last line above to
130  ```shell
131  apt-get install pixelated-server
132  ```
133
134 ## Running tests
135
136 [Here](https://github.com/pixelated/pixelated-user-agent/wiki/Running-Tests) you will find informations about how to run Pixelated tests.
137
138 # Further Notes
139
140 ## Multi User Mode
141
142 To run the pixelated user agent multi user mode, please run the following:
143 ```bash
144  vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 --multi-user --provider=dev.pixelated-project.org
145 ```
146
147 You will need to change `dev.pixelated-project.org` to the hostname of the leap provider that you will be using.
148 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.
149
150 ## Config file with credentials
151
152 Create a config file with `ini` format in the root directory, see the example:
153
154 *credentials.ini*
155 ```
156 [pixelated]
157 HOST=0.0.0.0
158 PORT=8080
159 leap_server_name=<your_provider>
160 leap_username=<your_username>
161 leap_password=<your_password>
162 ```
163 Host and port is optional.
164
165 To use it, start the user agent like this:
166 `$ pixelated-user-agent --host 0.0.0.0 --config credentials.ini`
167
168
169
170 ## How to translate the user interface
171
172 See: [Translating Pixelated](https://github.com/pixelated/pixelated-user-agent/wiki/Translating-Pixelated)
173
174 ## More informations
175
176 Read the [wiki pages](https://github.com/pixelated/pixelated-user-agent/wiki)