From 2165506db4a8041d17965875554b0effcfa0d866 Mon Sep 17 00:00:00 2001 From: NavaL Date: Mon, 8 Feb 2016 16:03:46 +0100 Subject: Updated read me Issue #593 --- README.md | 96 ++++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 67 insertions(+), 29 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d4be57eb..a9d6ede9 100644 --- a/README.md +++ b/README.md @@ -24,50 +24,88 @@ The Pixelated User Agent is the mail client of the Pixelated ecosystem. It is co * [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. +For server setup, see [debian package](#debian-package) below. -Clone the repository: - git clone https://github.com/pixelated-project/pixelated-user-agent.git - cd pixelated-user-agent +#### 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)). + +To setup the pixelated user agent inside a vagrant machine, please copy-paste the following command to a terminal: -From the project root folder, set up the vagrant machine: - - vagrant up - -After this is done, you can log into the machine and view project root folder with: +```bash + curl https://raw.githubusercontent.com/pixelated/pixelated-user-agent/master/vagrant_setup.sh | sh +``` - vagrant ssh - cd /vagrant +This could take a while depending on your internet connection. +Once it is complete, you should be within the terminal of the vagrant box. -Then run the setup: +To run the pixelated user agent single user mode, please run the following: - cd /vagrant/service - ./go setup +```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 +``` +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. +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' +``` +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. +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. + +To run the backend test: + +```bash + (user-agent-venv)vagrant@jessie:/vagrant$ cd service + (user-agent-venv)vagrant@jessie:/vagrant/service$ ./go test +``` -From here on you can run the tests for the UI by going to the **web-ui** folder or for the REST API by going to the **service** folder: +To run the frontend test: - cd /vagrant/web-ui - ./go test +```bash + (user-agent-venv)vagrant@jessie:/vagrant$ cd web-ui + (user-agent-venv)vagrant@jessie:/vagrant/web-ui$ ./go test +``` - cd /vagrant/service - ./go test +To run the functional test: -To run the user agent: +```bash + (user-agent-venv)vagrant@jessie:/vagrant$ cd service + (user-agent-venv)vagrant@jessie:/vagrant/service$ ./go functional +``` +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. +* 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: +```bash + (user-agent-venv)vagrant@jessie:/vagrant$ cd web-ui + (user-agent-venv)vagrant@jessie:/vagrant/web-ui$ ./go build ``` -$ pixelated-user-agent --host 0.0.0.0 -lc /vagrant/service/pixelated/certificates/dev.pixelated-project.org.ca.crt -> 2015-01-23 11:18:07+0100 [-] Log opened. -> 2015-01-23 11:18:07+0100 [-] Which provider do you want to connect to: -dev.pixelated-project.org -> 2015-01-23 11:18:52+0100 [-] What's your username registered on the provider: -username -> Type your password: -******************* +#### 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: + +```bash +$ git clone https://github.com/pixelated/pixelated-user-agent.git +$ cd pixelated-user-agent/service +$ ./go setup ``` -As soon as the user agent starts you will be asked for username, password and the [provider you registered with](https://github.com/pixelated-project/pixelated-user-agent/blob/master/README.md#registering-with-a-provider). +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. +Please ping us on IRC ([#pixelated on irc.freenode.net](irc://irc.freenode.net/pixelated)), we will be available to help you from there. -Now you can see it running on [http://localhost:3333](http://localhost:3333) +Running the user agent, and the various tests is the same as in the [vagrant setup](#developer-setup-with-vagrant) above. ## Debian package -- cgit v1.2.3