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
README.rst
  Diff comments   View file @cd25724
... ... @@ -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``.
... ...