Download as
Browse Code »

Commit cd257248b8014443bd4b879c911f9133198169f5

Authored by Sergio Oliveira
1 parent 5df9e498
Exists in master and in 39 other branches 1.12.x, add_requests_as_dep, celery_service, change-passwd-signal, check-port, colab-signals, colab-vcard, colab_search, colab_tag, colab_tag_merge, community_association, detach_super_archives, fix-dashboard, fix-message-preview, fix_app_label, fix_cache_count_spb, fix_header, fixed_gitlab_import, go_to_profile_panel, header_footer, layout-fix, mobile_user_scalable, move_out_plugins, paginate-threads, profile_integration, refactor-data-import, remove-gitlab-plugin, removing_namespace, search_block, search_filters, spb-release/3.0, split_screen, stable, startplugin, timestamp_plugins, translation_review, user_regex, validate-passwd, workin_whoosh_temp

Update README.rst 

Updating README (the vagrant way)
Showing 1 changed file with 86 additions and 72 deletions   Show diff stats
@@ -9,112 +9,126 @@ Colab, a Software for Communities @@ -9,112 +9,126 @@ Colab, a Software for Communities
9 ================================= 9 =================================
10 10
11 11
12 -Installation  
13 -============ 12 +Installation (Development Environment)
  13 +==========================================
14 14
15 -Installation instructions for Ubuntu 10.04  
16 -------------------------------------------- 15 +Here we'll cover how to setup a development environment using a Vagrant
  16 +virtual machine.
17 17
18 -* Install Apache2 with WSGI support: 18 +Before getting started you should install the following softwares:
19 19
20 - * apt-get install apache2 libapache2-mod-wsgi 20 +* Vagrant (tested with version 1.2.7)
21 21
22 -* Install dependencies to compile psycopg2: 22 +* Virtualbox (version >= 4.0)
23 23
24 - * apt-get build-dep python-psycopg2 24 +* fabric (tested with version 1.7.0)
25 25
26 -* Install Python PIP and update it:  
27 -  
28 - * apt-get install python-pip  
29 - * pip install -U pip 26 +* Git
30 27
31 -* Install python virtualenv:  
32 -  
33 - * pip install virtualenv  
34 28
35 -* Create a virtualenv for the deploy  
36 -  
37 - * mkdir /usr/local/django/  
38 - * virtualenv /usr/local/django/colab/ 29 +Getting started with the Virtual Machine
  30 +------------------------------------------
39 31
40 -* Download the colab src code: 32 +First you will need to clone the repository:
41 33
42 - * hg clone https://bitbucket.org/seocam/atu-colab /usr/local/src/colab/ 34 +.. code-block::
43 35
44 -* Install the django site: 36 + git clone git@github.com:interlegis/colab.git
45 37
46 - * pip install /usr/local/src/colab -E /usr/local/django/colab/  
47 38
48 -* Configure your database settings in /usr/local/django/colab/lib/python2.6/site-packages/settings_local.py  
49 -  
50 -* Enable the colab site on apache and reload it: 39 +*NOTE:*
  40 +
  41 + Here we are assuming you have ssh permissions to clone the repo using ssh. If not
  42 + fork it and clone your own fork (or use https instead of ssh).
  43 +
  44 +
  45 +Enter in the repository you've just cloned.
  46 +To start working all you need is to turn the virtual machine on with the command:
  47 +
  48 +.. code-block::
51 49
52 - * ln -s /usr/local/django/colab/apache-site/colab /etc/apache2/sites-available  
53 - * a2ensite colab  
54 - * service apache2 restart 50 + vagrant up
  51 +
  52 +
  53 +*NOTE:*
  54 +
  55 + BE PATIENT!
  56 +
  57 + This will take a while. The `vagrant up` will download a full vm (virtualbox)
  58 + running a Ubuntu 12.04 64bits. After the vm is up and running the command
  59 + will also configure it (using puppet) and that will also take a bit.
55 60
56 61
57 -Configuring server to send emails  
58 ----------------------------------- 62 +Running Colab
  63 +--------------
59 64
60 -* Install postfix and mailutils: 65 +Now that you have a vm running we have two options to run Colab:
  66 +
  67 +* Django development server (runserver)
61 68
62 - * apt-get install mailutils postfix 69 +* Gunicorn + supervisor + Nginx
63 70
64 -* Update the file /etc/aliases adding users that should receive root's messages and run the update command:  
65 71
66 - * newaliases 72 +Django development server (runserver)
  73 +++++++++++++++++++++++++++++++++++++++
67 74
  75 +This option is advised for developers working in new features for Colab.
  76 +The code used to run Colab will be the same code placed on your machine,
  77 +that means that if you change the code in your own computer the code on
  78 +the vm will also change.
68 79
69 -Cron job to import emails  
70 ---------------------------- 80 +Make sure you have a ``local_settings.py`` file placed in your repository. It
  81 +should be located in ``src/colab/``.
71 82
72 -* Install sshfs:  
73 -  
74 - * apt-get install sshfs autofs  
75 -  
76 -* Create SSH keys. You should use a password but this tutorial won't cover it (if you use you will need to install and configure keychain process to be able to proceed): 83 +To get started you can copy the example file as follow:
77 84
78 - * ssh-keygen  
79 -  
80 -* Copy the content of your key (/root/.ssh/id_rsa.pub) to the file /root/.ssh/authorized_keys on the mailinglist server. 85 +.. code-block::
81 86
82 -* Append the following content to /etc/auto.master file: 87 + cp src/colab/local_settings-dev.py src/colab/local_settings.py
83 88
84 - * /usr/local/django/colab/mnt /usr/local/django/colab/autofs/listas --timeout=600,--ghost  
85 89
86 -* Restart autofs: 90 +Now we are ready to run:
87 91
88 - * service autofs restart  
89 -  
90 -* Link cron script into /etc/cron.d/ folder: 92 +.. code-block::
91 93
92 - * ln -s /usr/local/django/colab/cron.d/colab_import_emails /etc/cron.d/ 94 + fab runserver
93 95
94 -* From now on the emails should be imported every minute  
95 96
  97 +*Note*
96 98
97 -Cron job to reindex Solr  
98 -------------------------- 99 + As this is the first time you run this command it will install all
  100 + requirements from ``requirements.txt`` into a virtualenv. To update
  101 + those requirements you should run ``fab runserver:update``.
99 102
100 -* Install wget:  
101 -  
102 - * apt-get install wget  
103 -  
104 -* Link cron script into /etc/cron.d/ folder:  
105 -  
106 - * ln -s /usr/local/django/colab/cron.d/colab_solr_reindex /etc/cron.d/  
107 -  
108 -* From now on delta reindex should run every 10 minutes and full reindex once a day.  
109 103
  104 +The ``fab runserver`` command will open the django builtin development
  105 +server on the port 7000 but due to vagrant magic you will be able to
  106 +access it on ``http://localhost:8000/``.
  107 +
  108 +
  109 +Gunicorn + supervisor + Nginx
  110 +++++++++++++++++++++++++++++++
  111 +
  112 +This option will run Colab in a way very similar to the production
  113 +environment. This should be used to test puppet manifests and also
  114 +the configuration of each one of the services running.
110 115
111 -Updating an installed version  
112 ------------------------------- 116 +First of all we need to clone the repo and configure your ``local_settings.py``.
  117 +That is done by calling the command:
113 118
114 -* Update the source code: 119 +.. code-block::
  120 +
  121 + fab install:path/to/your/local_settings.py
  122 +
  123 +
  124 +Now you need to deploy the code using the command:
  125 +
  126 +.. code-block::
  127 +
  128 + fab deploy
115 129
116 - * cd /usr/local/src/colab/  
117 - * hg pull  
118 - * hg up  
119 - * pip install /usr/local/src/colab/ -E /usr/local/django/colab/ -U  
120 - * service apache2 restart 130 +
  131 +For the next deploy you can just run ``fab deploy`` and in case your
  132 +``requirements.txt`` changes ``fab deploy:update``.
  133 +
  134 +The deployed code will be accessible on ``http://localhost:8080``.