development.rst 6.58 KB
Newer Older
Jamesie Pic's avatar
Jamesie Pic committed
1 2 3 4 5 6 7 8
Local development tutorial
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. warn:: I reverse-engineered this from the source code I inherited, I might
          not be doing the right way nor be able to defend all of technical
          decisions.

This tutorial drives through a local installation of the project for
9 10
development on Linux. It requires git, a fairly recent version of python2,
virtualenv and PostgreSQL.
Jamesie Pic's avatar
Jamesie Pic committed
11

12 13 14
Quickstart
==========

15 16 17 18 19 20
There is a quickstart script used and tested manually by some of the
developers. Feel free to try it, but don't worry if it doesn't work for you
then you can do each install step manually, which is recommended because well
that's how you will learn most.

Here's how to try it::
21

22
    $ git clone gitlab@git.laquadrature.net:memopol/memopol.git
23
    $ cd memopol
24 25
    $ source bin/quickstart.sh

26 27
If you want more control or if it doesn't work for you, then follow the steps
below or have a look at what the quickstart script does.
28

29 30 31 32 33 34
.. note::
  If you are using python 3 on your system, the quickstart script will install
  the virtualenv with this version. You'll need to remove the directory
  'memopol_env' and recreate it with the python version 2.7 in parameter
  'virtualenv -p /usr/bin/python2.7 memopol_env'

Jamesie Pic's avatar
Jamesie Pic committed
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
Make a virtual environment
==========================

For the sake of the tutorial, we'll do this in the temporary directory, but you
could do it anywhere::

    $ cd /tmp

Create a python virtual environment and activate it::

    $ virtualenv memopol_env
    Using real prefix '/usr'
    New python executable in memopol_env/bin/python2
    Also creating executable in memopol_env/bin/python
    Installing setuptools, pip, wheel...done.

    $ source memopol_env/bin/activate

Jamesie Pic's avatar
Jamesie Pic committed
53 54 55 56 57
Alternatively, use the tox command::

    $ tox -e py27
    $ source .tox/py27/bin/activate

Jamesie Pic's avatar
Jamesie Pic committed
58 59 60
Clone the repository
====================

61 62 63
The project is hosted on https://git.laquadrature.net/memopol/memopol

You can get the code with git ::
Jamesie Pic's avatar
Jamesie Pic committed
64

65 66 67 68 69 70 71 72
    $ git clone https://git.laquadrature.net/memopol/memopol
    Clonage dans 'memopol'...
    remote: Counting objects: 7972, done.
    remote: Compressing objects: 100% (2668/2668), done.
    remote: Total 7972 (delta 5203), reused 7830 (delta 5099)
    Réception d'objets: 100% (7972/7972), 4.88 MiB | 4.73 MiB/s, fait.
    Résolution des deltas: 100% (5203/5203), fait.
    Vérification de la connectivité... fait.
Jamesie Pic's avatar
Jamesie Pic committed
73

74
    $ cd memopol/
Jamesie Pic's avatar
Jamesie Pic committed
75 76 77

Create your own branch, ie::

lnclt's avatar
lnclt committed
78
    $ git checkout -b yourbranch
Jamesie Pic's avatar
Jamesie Pic committed
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
    Branch yourbranch set up to track remote branch pr from origin.
    Switched to a new branch 'yourbranch'

Install Python dependencies
===========================

Then, install the package for development::

    $ pip install -e .
    Obtaining file:///tmp/political_memory
    Collecting django (from political-memory==0.0.1)
      Using cached Django-1.9-py2.py3-none-any.whl

    [output snipped for readability]

    Installing collected packages: django, sqlparse, django-debug-toolbar, django-pdb, six, django-extensions, werkzeug, south, pygments, markdown, hamlpy, django-coffeescript, ijson, python-dateutil, pytz, political-memory
      Running setup.py develop for political-memory
    Successfully installed django-1.9 django-coffeescript-0.7.2 django-debug-toolbar-1.4 django-extensions-1.5.9 django-pdb-0.4.2 hamlpy-0.82.2 ijson-2.2 markdown-2.6.5 political-memory pygments-2.0.2 python-dateutil-2.4.2 pytz-2015.7 six-1.10.0 south-1.0.2 sqlparse-0.1.18 werkzeug-0.11.2

98
Install client dependencies
Jamesie Pic's avatar
Jamesie Pic committed
99 100
===========================

101
We'll also need to download client libraries::
Jamesie Pic's avatar
Jamesie Pic committed
102

lnclt's avatar
lnclt committed
103
    $ src/memopol/bin/install_client_deps.sh
104 105 106 107 108
    * Downloading jquery/jquery (2.1.4) from Github...
    * Downloading FortAwesome/Font-Awesome (v4.3.0) from Github...
    * Downloading lipis/flag-icon-css (0.7.1) from Github...
    * Downloading twbs/bootstrap (v3.3.5) from Github...
    * Done
Jamesie Pic's avatar
Jamesie Pic committed
109

Jamesie Pic's avatar
Quality  
Jamesie Pic committed
110 111
Activate ``DJANGO_DEBUG``
=========================
Jamesie Pic's avatar
Jamesie Pic committed
112

Jamesie Pic's avatar
Quality  
Jamesie Pic committed
113 114 115
``DEBUG`` is disabled by default, the development server
won't run properly by default thnen, to enable it export
the ``DJANGO_DEBUG`` variable in the current shell::
Jamesie Pic's avatar
Jamesie Pic committed
116

Jamesie Pic's avatar
Quality  
Jamesie Pic committed
117
    $ export DJANGO_DEBUG=True
Jamesie Pic's avatar
Jamesie Pic committed
118

119 120
Setup the database
==================
Jamesie Pic's avatar
Jamesie Pic committed
121

122 123 124
Memopol requires PostgreSQL 9.1 or higher.  It used to run with SQLite, too, but
that is no longer the case.  Memopol uses the following environment variables
for database access:
Jamesie Pic's avatar
Jamesie Pic committed
125

126 127 128 129 130
* ``MEMOPOL_DB_NAME`` (defaults to 'memopol')
* ``MEMOPOL_DB_USER`` (defaults to 'memopol')
* ``MEMOPOL_DB_PASSWORD`` (defaults to 'memopol')
* ``MEMOPOL_DB_HOST`` (defaults to 'localhost')
* ``MEMOPOL_DB_PORT`` (defaults to '5432')
Jamesie Pic's avatar
Jamesie Pic committed
131

132 133
Make sure the corresponding user and database exist on your system; the user
will need the 'createdb' permission in order to be able to run tests.  To create
Nicolas Joyard's avatar
Nicolas Joyard committed
134
them, you may use the following commands::
Jamesie Pic's avatar
Jamesie Pic committed
135

136 137 138
    $ psql -c "create user memopol with password 'memopol';" -U postgres
    $ psql -c "alter role memopol with createdb;" -U postgres
    $ psql -c "create database memopol with owner memopol;" -U postgres
Jamesie Pic's avatar
Jamesie Pic committed
139

Jamesie Pic's avatar
Jamesie Pic committed
140 141 142
Database migrations
===================

143 144 145
Database migrations ensure the database schema is up to date with the project.
If you're not sure, you can run them anyway, they won't do any harm.  Use the
following command::
Jamesie Pic's avatar
Jamesie Pic committed
146

Jamesie Pic's avatar
Jamesie Pic committed
147
    $ memopol migrate
Jamesie Pic's avatar
Jamesie Pic committed
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
    Operations to perform:
      Synchronize unmigrated apps: django_filters, staticfiles, datetimewidget, autocomplete_light, messages, adminplus, compressor, humanize, django_extensions, constance, bootstrap3
      Apply all migrations: legislature, votes, database, admin, positions, sessions, representatives, auth, contenttypes, representatives_votes, taggit
    Synchronizing apps without migrations:
      Creating tables...
        Running deferred SQL...
      Installing custom SQL...
    Running migrations:
      Rendering model states... DONE
      Applying contenttypes.0001_initial... OK

    [output snipped for readability]

      Applying taggit.0002_auto_20150616_2121... OK

Provision with data
===================

166
You can load a small data sample for quick setup:
Jamesie Pic's avatar
Jamesie Pic committed
167

Jamesie Pic's avatar
Jamesie Pic committed
168
    $ memopol loaddata small_sample.json
Jamesie Pic's avatar
Jamesie Pic committed
169

170 171 172 173
If you launch memopol for the first time, you need to launch this command :

    $ memopol refresh_scores

Jamesie Pic's avatar
Jamesie Pic committed
174
Or actual data (takes a while)::
Jamesie Pic's avatar
Jamesie Pic committed
175 176

    $ bin/update_all
Jamesie Pic's avatar
Quality  
Jamesie Pic committed
177

178 179 180 181 182
Run the development server
==========================

Run the development server::

Jamesie Pic's avatar
Jamesie Pic committed
183
    $ memopol runserver
184 185 186 187 188 189 190 191 192 193 194 195

    Performing system checks...

    System check identified no issues (0 silenced).
    December 09, 2015 - 21:26:47
    Django version 1.8.7, using settings 'memopol.settings'
    Starting development server at http://127.0.0.1:8000/
    Quit the server with CONTROL-C.
    [09/Dec/2015 21:26:48] "GET / HTTP/1.1" 200 13294

The website is running on ``http://127.0.0.1:8000/``.

Jamesie Pic's avatar
Quality  
Jamesie Pic committed
196
Continue to :doc:`administration`.