development.rst 6.05 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
15
16
17
18
19
20
21
22
23
24
25
Quickstart
==========

You can skip the instructions below and just use the quickstart script. To do
so, first clone the repository, cd into the repository root and source the
quickstart script:

    $ git clone https://github.com/political-memory/political_memory.git
    $ cd political_memory
    $ source bin/quickstart.sh

If you want more control, you can follow the steps below or have a look at what
the quickstart script does.

Jamesie Pic's avatar
Jamesie Pic committed
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
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

Clone the repository
====================

You should fork the project on github and use the fork's clone url. For the
sake of the demo, we'll use the main repository URL::

    $ git clone https://github.com/political-memory/political_memory.git
    Cloning into 'political_memory'...
    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.

    $ cd political_memory/

Create your own branch, ie::

    $ git checkout -b yourbranch origin/pr
    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

83
Install client dependencies
Jamesie Pic's avatar
Jamesie Pic committed
84
85
===========================

86
We'll also need to download client libraries::
Jamesie Pic's avatar
Jamesie Pic committed
87

88
89
90
91
92
93
    $ bin/install_client_deps.sh
    * 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
94

Jamesie Pic's avatar
Quality    
Jamesie Pic committed
95
96
Activate ``DJANGO_DEBUG``
=========================
Jamesie Pic's avatar
Jamesie Pic committed
97

Jamesie Pic's avatar
Quality    
Jamesie Pic committed
98
99
100
``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
101

Jamesie Pic's avatar
Quality    
Jamesie Pic committed
102
    $ export DJANGO_DEBUG=True
Jamesie Pic's avatar
Jamesie Pic committed
103

104
105
Setup the database
==================
Jamesie Pic's avatar
Jamesie Pic committed
106

107
108
109
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
110

111
112
113
114
115
* ``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
116

117
118
119
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:
Jamesie Pic's avatar
Jamesie Pic committed
120

121
122
123
    $ 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
124

Jamesie Pic's avatar
Jamesie Pic committed
125
126
127
Database migrations
===================

128
129
130
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

    $ ./manage.py migrate
    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
===================

151
You can load a small data sample for quick setup:
Jamesie Pic's avatar
Jamesie Pic committed
152
153
154
155

    $ ./manage.py loaddata memopol/fixtures/small_sample.json

Or actual data (takes a while)::
Jamesie Pic's avatar
Jamesie Pic committed
156
157

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

159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
Run the development server
==========================

Run the development server::

    $ ./manage.py runserver

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