From b1de000fc637de3294ede250cefc9192fdcd0f43 Mon Sep 17 00:00:00 2001 From: NavaL Date: Mon, 8 Feb 2016 16:25:12 +0100 Subject: refactoring read me Issue #593 --- README.md | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index a9d6ede9..72df72a4 100644 --- a/README.md +++ b/README.md @@ -18,21 +18,20 @@ The Pixelated User Agent is the mail client of the Pixelated ecosystem. It is co * You can create a developer account at our [Dev Provider](https://dev.pixelated-project.org/). * If you want to run your own LEAP provider, see [pixelated-platform](https://github.com/pixelated-project/pixelated-platform). -### Requirements - - * [virtualbox](https://www.virtualbox.org/wiki/Downloads) - Virtualbox is a virtual machine provider platform. It will be used by Vagrant to create a virtual machine ready to run the Pixelated User Agent. - * [vagrant](https://www.vagrantup.com/downloads.html) - Vagrant is a tool that automates the setup of a virtual machine with the development environment in your computer. Inside the virtual machine's filesystem, this repository will be automatically mounted in the `/vagrant` folder. - -### Instructions -The easiest setup is the setup with vagrant, which we will go at greater length. There is a section on setup on the native OS as well. +## Installation Instructions +The easiest setup is the [setup with vagrant](#developer-setup-with-vagrant), which we will go in details below. There is a section on [setup on the native OS](#developer-setup-on-native-os) as well. For server setup, see [debian package](#debian-package) below. -#### Developer Setup With Vagrant +### Developer Setup With Vagrant Please ensure that: * You have an email user from your preferred leap provider ([How to](#registering-with-a-leap-provider)). - * Installed both vagrant and virtualbox or libvirt ([How to](#requirements)). + +##### Requirements + * [virtualbox](https://www.virtualbox.org/wiki/Downloads) - Virtualbox is a virtual machine provider platform. It will be used by Vagrant to create a virtual machine ready to run the Pixelated User Agent. + * [vagrant](https://www.vagrantup.com/downloads.html) - Vagrant is a tool that automates the setup of a virtual machine with the development environment in your computer. Inside the virtual machine's filesystem, this repository will be automatically mounted in the `/vagrant` folder. +##### Set up To setup the pixelated user agent inside a vagrant machine, please copy-paste the following command to a terminal: ```bash @@ -42,21 +41,23 @@ To setup the pixelated user agent inside a vagrant machine, please copy-paste th This could take a while depending on your internet connection. Once it is complete, you should be within the terminal of the vagrant box. +##### Running the user agent To run the pixelated user agent single user mode, please run the following: ```bash - (user-agent-venv)vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 -lc /vagrant/service/pixelated/certificates/dev.pixelated-project.org.ca.crt + (user-agent-venv)vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 ``` -You will then need to input your provider hostname, email username and password. Please follow the prompt. Please remove the `-lc` part of the command if your leap provider has a proper certificate setup. +You will then need to input your provider hostname, email username and password. Please follow the prompt. Once that is done, you can use by browsing to [http://localhost:3333](http://localhost:3333) To run the pixelated user agent multi user mode, please run the following: ```bash - (user-agent-venv)vagrant@jessie:/vagrant$ pixelated-user-agent --host 0.0.0.0 -lc /vagrant/service/pixelated/certificates/dev.pixelated-project.org.ca.crt --multi-user --provider='dev.pixelated-project.org' + (user-agent-venv)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. Please remove the `-lc` part of the command if your leap provider has a proper certificate setup. +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. - + +##### Running tests To run the backend test: ```bash @@ -78,21 +79,22 @@ To run the functional test: (user-agent-venv)vagrant@jessie:/vagrant/service$ ./go functional ``` -Continuous Integration: +##### Continuous Integration All commits to the pixelated user agent code trigger all tests to be run in [snap-ci](https://snap-ci.com/pixelated/pixelated-user-agent/branch/master). -Please note: -* 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. +##### Note +* 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 restart the server -* For most frontend changes, you will ust need to reload the browser. Some changes (in particular, those involving css or handlebars) you will need run: +* For most frontend changes, you will just need to reload the browser. Some changes (in particular, those involving css or handlebars) you will need run: ```bash (user-agent-venv)vagrant@jessie:/vagrant$ cd web-ui (user-agent-venv)vagrant@jessie:/vagrant/web-ui$ ./go build ``` -#### Developer Setup On Native OS + +### Developer Setup On Native OS You will need to install python, pip, npm and openssl. On mac, please use homebrew. On debian/ubuntu, please use apt or aptitude. You will then need to run: @@ -102,10 +104,10 @@ $ cd pixelated-user-agent/service $ ./go setup ``` -There have been reports of issues on setting up on native OS. Please follow instructions from the output of homebrew. You might need to install compass as a GEM as well. +There have been reports of issues on setting up on native OS. Please follow instructions from the output of homebrew. You might need to `gem install compass` as well. Please ping us on IRC ([#pixelated on irc.freenode.net](irc://irc.freenode.net/pixelated)), we will be available to help you from there. -Running the user agent, and the various tests is the same as in the [vagrant setup](#developer-setup-with-vagrant) above. +Running the user agent ([How to](#running-the-user-agent)), and the various tests ([How to](#running-tests)) are the same as in the vagrant setup above. ## Debian package -- cgit v1.2.3