development.rst 6.22 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
development on Linux. It requires git, a fairly recent version of python2 and
Jamesie Pic's avatar
Jamesie Pic committed
10 11
virtualenv.

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 https://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

Jamesie Pic's avatar
Jamesie Pic committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
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
47 48 49 50 51
Alternatively, use the tox command::

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

Jamesie Pic's avatar
Jamesie Pic committed
52 53 54
Clone the repository
====================

55
You should fork the project on git laquadrature.net and use the fork's clone url. For the
Jamesie Pic's avatar
Jamesie Pic committed
56 57
sake of the demo, we'll use the main repository URL::

58
    $ git clone https://git.laquadrature.net/memopol/memopol.git
59
    Cloning into 'memopol'...
Jamesie Pic's avatar
Jamesie Pic committed
60 61 62 63 64 65 66
    remote: Counting objects: 2516, done.
    remote: Compressing objects: 100% (109/109), done.
    remote: Total 2516 (delta 44), reused 0 (delta 0), pack-reused 2402
    Receiving objects: 100% (2516/2516), 4.40 MiB | 79.00 KiB/s, done.
    Resolving deltas: 100% (1103/1103), done.
    Checking connectivity... done.

67
    $ cd memopol/
Jamesie Pic's avatar
Jamesie Pic committed
68 69 70

Create your own branch, ie::

lnclt's avatar
lnclt committed
71
    $ git checkout -b yourbranch
Jamesie Pic's avatar
Jamesie Pic committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
    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

91
Install client dependencies
Jamesie Pic's avatar
Jamesie Pic committed
92 93
===========================

94
We'll also need to download client libraries::
Jamesie Pic's avatar
Jamesie Pic committed
95

lnclt's avatar
lnclt committed
96
    $ src/memopol/bin/install_client_deps.sh
97 98 99 100 101
    * 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
102

Jamesie Pic's avatar
Quality  
Jamesie Pic committed
103 104
Activate ``DJANGO_DEBUG``
=========================
Jamesie Pic's avatar
Jamesie Pic committed
105

Jamesie Pic's avatar
Quality  
Jamesie Pic committed
106 107 108
``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
109

Jamesie Pic's avatar
Quality  
Jamesie Pic committed
110
    $ export DJANGO_DEBUG=True
Jamesie Pic's avatar
Jamesie Pic committed
111

112 113
Setup the database
==================
Jamesie Pic's avatar
Jamesie Pic committed
114

115 116 117
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
118

119 120 121 122 123
* ``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
124

125 126
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
127
them, you may use the following commands::
Jamesie Pic's avatar
Jamesie Pic committed
128

129 130 131
    $ 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
132

Jamesie Pic's avatar
Jamesie Pic committed
133 134 135
Database migrations
===================

136 137 138
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
139

Jamesie Pic's avatar
Jamesie Pic committed
140
    $ memopol migrate
Jamesie Pic's avatar
Jamesie Pic committed
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
    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
===================

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

Jamesie Pic's avatar
Jamesie Pic committed
161
    $ memopol loaddata small_sample.json
Jamesie Pic's avatar
Jamesie Pic committed
162 163

Or actual data (takes a while)::
Jamesie Pic's avatar
Jamesie Pic committed
164 165

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

167 168 169 170 171
Run the development server
==========================

Run the development server::

Jamesie Pic's avatar
Jamesie Pic committed
172
    $ memopol runserver
173 174 175 176 177 178 179 180 181 182 183 184

    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
185
Continue to :doc:`administration`.