add initial development documentation
[debianmemberportfolio.git] / docs / devdocs.rst
1 Development of Debian Member Portfolio Service
2 ==============================================
3
4 The Debian Member Portfolio Service is implemented in `Python
5 <http://www.python.org>`_ using the `Pylons
6 <http://docs.pylonsproject.org/en/latest/docs/pylons.html>`_ web application
7 framework.
8
9 The following sections describe how to setup a local development environment
10 for the Debian Member Portfolio Service.
11
12 All instructions assume that you work on a Debian system. You should use Python
13 2.7 for development.
14
15 Setup of a local development
16 ----------------------------
17
18 To start working on the source code you need to have `git`_ installed::
19
20   sudo aptitude install git
21
22 .. _git: http://www.git-scm.com/
23
24 The canonical git repository for the Debian Member Portfolio Service is
25 available at http://debianstuff.dittberner.info/git/ddportfolioservice.git. To
26 get a clone of the source code you change to a directory of your choice and
27 invoke git clone::
28
29   cd ~/src
30   git clone http://debianstuff.dittberner.info/git/ddportfolioservice.git
31
32 You should use `virtualenv`_ to separate the development environment from your
33 system wide Python installation. You can install virtualenv using::
34
35   sudo aptitude install python-virtualenv
36
37 .. _virtualenv: https://pypi.python.org/pypi/virtualenv
38
39 When you have :command:`virtualenv` installed you should create a virtual
40 environment for Debian Member Portfolio Service development and install the
41 requirements using `pip <https://pypi.python.org/pypi/pip>`_::
42
43   mkdir ~/.virtualenvs
44   virtualenv --distribute ~/.virtualenvs/dmportfolio
45   . ~/.virtualenvs/dmportfolio/bin/activate
46   cd ~/src/ddportfolioservice
47   pip install -r squeezereq.pip
48
49 .. note::
50
51   The Debian Member Portfolio Service instance at http://portfolio.debian.net/
52   is running on a Debian Squeeze server, therefore :file:`squeezereq.pip`
53   contains dependency versions matching that Debian release.
54
55 The dependency download and installation into the virtual environment takes
56 some time.
57
58 After you have your virtual environment ready you need to setup the project for
59 development::
60
61   python setup.py develop
62
63 Debian Member Portfolio Service needs the JQuery JavaScript library to function
64 properly. The JQuery library is not included in the git clone and must be
65 copied into the subdirectory
66 :file:`ddportfolioservice/public/javascript/jquery`. On Debian systems you can
67 install the package libjs-jquery and place a symlink to the directory
68 :file:`/usr/share/javascript` into :file:`ddportfolioservice/public`: ::
69
70   sudo aptitude install libjs-jquery
71   ln -s /usr/share/javascript ddportfolioservice/public
72
73 Prepare for first startup
74 ~~~~~~~~~~~~~~~~~~~~~~~~~
75
76 The Debian Member Portfolio Service uses data from the Debian keyring to get
77 information regarding PGP keys and names related to email addresses. Before you
78 can run the service you need to fetch a copy of the keyring and prepare it for
79 use by the code.
80
81 .. note::
82
83   You need rsync and gnupg for these tasks::
84
85     sudo aptitude install rsync gnupg
86
87 When you have both installed you can run::
88
89   . ~/.virtualenvs/dmportfolio/bin/activate
90   ./synckeyrings.sh
91   python ddportfolioservice/model/keyringanalyzer.py
92
93 The first synchronizes the keyrings in :file:`$HOME/debian/keyring.debian.org`
94 with files on the `keyring.debian.org <http://keyring.debian.org>`_ host. And
95 the second generates a key/value database in
96 :file:`ddportfolioservice/model/keyringcache` that is used by the code.
97
98 Run a development server
99 ~~~~~~~~~~~~~~~~~~~~~~~~
100
101 Pylons uses PasteScript to run a development server. You can run a development
102 server using::
103
104   paster serve --reload development.ini
105
106 The output of this command should look like the following::
107
108   Starting subprocess with file monitor
109   Starting server in PID 31377.
110   serving on http://127.0.0.1:5000
111
112 You can now access your development server at the URL that is printed by the command.
113
114 If you want to stop the development server press :kbd:`Ctrl + C`.
115
116 Common development tasks
117 ------------------------
118
119 Add new URL
120 ~~~~~~~~~~~