development.rst 7.74 KB
Newer Older
Jamesie Pic's avatar
Jamesie Pic committed
1 2 3 4
Local development tutorial
~~~~~~~~~~~~~~~~~~~~~~~~~~

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

8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
Setup the database
==================

Memopol requires PostgreSQL 9.1 or higher.  It used to run with SQLite, too, but
that is no longer the case. It is better to install and configure you're local
PostgreSQL server before starting to install Memopol.

On Debian
---------

To setup you're PostgreSQL database on a debian stable distribution, you can use
the package manager apt::

  $ apt install postgresql postgresql-server-dev-9.X

Then you need to create the 'memopol'  user and the 'memopol' database::

  # To have a root access on Postgres, you need to connect as user 'postgres'
  $ su - postgres
  $ psql -c "create user memopol with password 'memopol';"
  $ psql -c "alter role memopol with createdb;"
  $ psql -c "create database memopol with owner memopol;"
  $ exit

You're database is now setup for Memopol. You can now launch the 'quickstart.sh'
alexandre.jauneau's avatar
alexandre.jauneau committed
33
script to automatically install all the components or do it manually.
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48

In General
----------

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
them, you may use the following commands::

    $ 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


Automatic Install
=================
49

50 51 52 53 54 55
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::
56

57
    $ git clone gitlab@git.laquadrature.net:memopol/memopol.git
58
    $ cd memopol
59 60
    $ source bin/quickstart.sh

61 62 63 64
At this point, you should now run the development server and access to Memopol::

  $ memopol runserver

65 66
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.
67

68 69 70 71 72 73 74 75 76 77 78
Development helper
===================

You can run the script 'bin/dev.sh' to automaticaly setup some aliases. It works
only with Bash and Zsh.

The script build a custom file named '.memopol.alias' at the root of the project
containing all the aliases for memopol. All the path to the project are build
automatically. A single line is added to your '$HOME/.bashrc' or '$HOME/.zshrc'
to source the aliases.

alexandre.jauneau's avatar
alexandre.jauneau committed
79
After execute 'bin/dev.sh' you should close the current terminal and open
80 81 82 83
another one to have access to the aliases.

There is a quick list of available aliases::

alexandre.jauneau's avatar
alexandre.jauneau committed
84 85
  memopol-code : Go into the repository and activate virtualenv and
  set Django in debug mode
86 87 88 89 90 91 92 93 94 95 96
  memopol-launch : Run the development server echo
  memopol-update-all : Get all the production data
  memopol-refresh-scores : Refresh all scores

.. warning:: If you are using multiple setup of Memopol, it is not recommended to
  use this script.

If you need to change the location of the project, you should remove this line
from your .bashrc or .zshrc::

  source $PATH_TO_THE_PROJECT/.memopol.alias
97

Jamesie Pic's avatar
Jamesie Pic committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
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
116 117 118 119 120
Alternatively, use the tox command::

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

Jamesie Pic's avatar
Jamesie Pic committed
121 122 123
Clone the repository
====================

124 125 126
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
127

128 129 130 131 132 133 134 135
    $ 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
136

137
    $ cd memopol/
Jamesie Pic's avatar
Jamesie Pic committed
138 139 140

Create your own branch, ie::

lnclt's avatar
lnclt committed
141
    $ git checkout -b yourbranch
Jamesie Pic's avatar
Jamesie Pic committed
142 143 144 145 146 147 148 149 150
    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 .
151 152
    Obtaining file:///tmp/memopol
    Collecting django (from memopol==0.0.1)
Jamesie Pic's avatar
Jamesie Pic committed
153 154 155 156
      Using cached Django-1.9-py2.py3-none-any.whl

    [output snipped for readability]

157 158 159
    Installing collected packages: django, sqlparse, django-debug-toolbar, django-pdb, six, django-extensions, werkzeug, south, pygments, markdown, hamlpy, django-coffeescript, ijson, python-dateutil, pytz, memopol
      Running setup.py develop for memopol
    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 memopol 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
Jamesie Pic's avatar
Jamesie Pic committed
160

161
Install client dependencies
Jamesie Pic's avatar
Jamesie Pic committed
162 163
===========================

164
We'll also need to download client libraries::
Jamesie Pic's avatar
Jamesie Pic committed
165

lnclt's avatar
lnclt committed
166
    $ src/memopol/bin/install_client_deps.sh
167 168 169 170 171
    * 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
172

Jamesie Pic's avatar
Jamesie Pic committed
173 174
Activate ``DJANGO_DEBUG``
=========================
Jamesie Pic's avatar
Jamesie Pic committed
175

Jamesie Pic's avatar
Jamesie Pic committed
176
``DEBUG`` is disabled by default, the development server
alexandre.jauneau's avatar
alexandre.jauneau committed
177
won't run properly by default then, to enable it export
Jamesie Pic's avatar
Jamesie Pic committed
178
the ``DJANGO_DEBUG`` variable in the current shell::
Jamesie Pic's avatar
Jamesie Pic committed
179

Jamesie Pic's avatar
Jamesie Pic committed
180
    $ export DJANGO_DEBUG=True
Jamesie Pic's avatar
Jamesie Pic committed
181

Jamesie Pic's avatar
Jamesie Pic committed
182

Jamesie Pic's avatar
Jamesie Pic committed
183 184 185
Database migrations
===================

186 187 188
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
189

Jamesie Pic's avatar
Jamesie Pic committed
190
    $ memopol migrate
Jamesie Pic's avatar
Jamesie Pic committed
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208
    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
===================

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

Jamesie Pic's avatar
Jamesie Pic committed
211
    $ memopol loaddata small_sample.json
Jamesie Pic's avatar
Jamesie Pic committed
212

213 214 215 216
If you launch memopol for the first time, you need to launch this command :

    $ memopol refresh_scores

Jamesie Pic's avatar
Jamesie Pic committed
217
Or actual data (takes a while)::
Jamesie Pic's avatar
Jamesie Pic committed
218 219

    $ bin/update_all
Jamesie Pic's avatar
Jamesie Pic committed
220

221 222 223 224 225
Run the development server
==========================

Run the development server::

Jamesie Pic's avatar
Jamesie Pic committed
226
    $ memopol runserver
227 228 229 230 231 232 233 234 235 236 237 238

    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
Jamesie Pic committed
239
Continue to :doc:`administration`.