1
2
3
4
5
6
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
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
************
Hacking MaaS
************
Coding style
============
MaaS follows the `Launchpad Python Style Guide`_, except where it gets
Launchpad specific, and where it talks about `method naming`_. MaaS
instead adopts `PEP-8`_ naming in all cases, so method names should
usually use the ``lowercase_with_underscores`` form.
.. _Launchpad Python Style Guide:
https://dev.launchpad.net/PythonStyleGuide
.. _method naming:
https://dev.launchpad.net/PythonStyleGuide#Naming
.. _PEP-8:
http://www.python.org/dev/peps/pep-0008/
Prerequisites
=============
You will need to manually install Postgres 9.1, RabbitMQ, python-dev and make::
$ sudo apt-get install postgresql-9.1 rabbitmq-server python-dev make
Also, you might want to install Bazaar (bzr) to grab the source code directly
from Launchpad::
$ sudo apt-get install bzr
This is the list of runtime dependencies that you'll need to install::
$ sudo apt-get install python-django python-django-piston \
python-django-south python-twisted python-txamqp python-amqplib \
python-formencode python-oauth python-oops python-oops-datedir-repo \
python-twisted python-oops-wsgi python-oops-twisted \
python-psycopg2 python-yaml
Additionally, you need to install the following python libraries
for development convenience::
$ sudo apt-get install python-sphinx python-lxml
If you intend to run the test suite, you also need xvfb and firefox::
$ sudo apt-get install xvfb firefox
All other development dependencies are pulled automatically from `PyPI`_
when buildout runs.
.. _PyPI:
http://pypi.python.org/
First time using buildout?
==========================
Buildout is used to develop MaaS. Buildout, if configured so, can
cache downloaded files and built eggs. If you've not already done
something similar, the following snippet will massively improve build
times::
[buildout]
download-cache = /home/<your-user-name>/.buildout/cache
eggs-directory = /home/<your-user-name>/.buildout/eggs
Put this in ``~/.buildout/default.cfg`` and create the ``cache``
directory::
$ mkdir /home/<your-user-name>/.buildout/cache
The ``eggs`` directory will be created automatically.
Getting the latest version of the code
======================================
You can grab the code manually from Launchpad but Bazaar makes it easy to fetch
the last version of the code. Go into the directory where you want the code
to reside and run::
$ bzr branch lp:maas maas && cd maas
Development MaaS server setup
=============================
Access to the database is configured in ``src/maas/development.py``.
The ``Makefile`` or the test suite sets up a development database
cluster inside your branch. It lives in the ``db`` directory, which
gets created on demand. You'll want to shut it down before deleting a
branch; see below.
First, set up the project. This fetches all the required dependencies
and sets up some useful commands in ``bin/``::
$ make
Create the database cluster and initialize the development database::
$ make syncdb
Optionally, populate your database with the sample data::
$ make sampledata
Install Cobbler, and import at least one distro and profile::
$ sudo apt-get install apache2 cobbler
$ sudo cobbler-ubuntu-import precise-i386 # For example.
Add yourself as a user in Cobbler. For convenience, give yourself the
password ``test``::
$ sudo htdigest /etc/cobbler/users.digest Cobbler $USER
Alternatively, if you're not interested in the Provisioning Server or
Cobbler, set ``PSERV_URL`` to ``None`` in one of ``maas``'s settings
files (typically ``src/maas/demo.py``), and a fake Provisioning Server
will be used instead.
Run the development webserver::
$ make run
Point your browser to http://localhost:8000/
If you've populated your instance with the sample data, you can login as a
simple user using the test account (username: 'test', password: 'test') or the
admin account (username: 'admin', password: 'test').
To shut down the database cluster and clean up all other generated files in
your branch::
$ make distclean
Adding new dependencies
=======================
Since MaaS is distributed mainly as Ubuntu package, all runtime dependencies
should be packaged and we should develop with the packaged version if
possible. You'll need to add the dependency to the
``allowed-eggs-from-site-packages`` option in the ``buildout.cfg`` file. You
also need to add it to setup.py (And don't forget to add the version to
``versions.cfg`` as we run with ``allowed-picked-version`` set to false.)
If it is a development-only dependency (i.e. only needed for the test suite, or
for developers' convenience), simply running ``buildout`` like this will make
the necessary updates to ``versions.cfg``::
$ ./bin/buildout -v buildout:allow-picked-versions=true
Adding new source files
=======================
When creating a new source file, a Python module or test for example,
always start with the appropriate template from the ``templates``
directory.
Documentation
=============
Use `reST`_ with the `convention for headings as used in the Python
documentation`_.
.. _reST: http://sphinx.pocoo.org/rest.html
.. _convention for headings as used in the Python documentation:
http://sphinx.pocoo.org/rest.html#sections
|