root / snf-webproject / docs / index.rst @ 5a0dde9e
History | View | Annotate | Download (10.9 kB)
1 |
.. _snf-webproject: |
---|---|
2 |
|
3 |
Component snf-webproject |
4 |
======================== |
5 |
|
6 |
Synnefo component :ref:`snf-webproject <snf-webproject>` defines a Django |
7 |
project in which the various other Synnefo components |
8 |
(:ref:`snf-cyclades-app <snf-cyclades-app>`, |
9 |
:ref:`snf-pithos-app <snf-pithos-app>`, etc.) may run. |
10 |
|
11 |
It provides a standard mechanism for every Synnefo software component to modify |
12 |
the list of Django apps to be executed inside the project (``INSTALLED_APPS``), |
13 |
modify the list of middleware classes (``MIDDLEWARE_CLASSES``) and add its own |
14 |
URL patterns. |
15 |
|
16 |
In other words, wraps a Django project which extends itself (URLs, |
17 |
default_settings, installed_apps, middleware_classes) based on the Synnefo |
18 |
components/packages installed on the system. |
19 |
|
20 |
The extending mechanism is based on the python setuptools `entry_points`. So if |
21 |
an application (Synnefo component) wants to plug additional configuration to |
22 |
the Django project, it should define within its setup.py file the 'synnefo' |
23 |
appropriate entry_points. |
24 |
|
25 |
For usage example please take a look how snf-cyclades-app package defines its entry |
26 |
points in: |
27 |
|
28 |
- snf-cyclades-app/setup.py |
29 |
- snf-cyclades-app/app_settings/__init__.py |
30 |
|
31 |
.. todo:: Document snf-webproject facilities for developers |
32 |
|
33 |
Package installation |
34 |
-------------------- |
35 |
|
36 |
.. todo:: kpap: verify instructions for installation from source. |
37 |
|
38 |
Use ``pip`` to install the latest version of the package from source, |
39 |
or request a specific version as ``snf-webproject==x.y.z``. |
40 |
|
41 |
.. code-block:: console |
42 |
|
43 |
pip install snf-webproject -f https://www.synnefo.org/packages/pypi |
44 |
|
45 |
On Debian Squeeze, install the ``snf-webproject`` Debian package. |
46 |
|
47 |
Package configuration |
48 |
--------------------- |
49 |
|
50 |
Database |
51 |
******** |
52 |
|
53 |
You need to create a database for use by the Django project, |
54 |
then configure your custom :ref:`snf-common <snf-common>` settings, |
55 |
according to your choice of DB. |
56 |
|
57 |
DB creation |
58 |
``````````` |
59 |
|
60 |
SQLite |
61 |
~~~~~~ |
62 |
Most self-respecting systems have ``sqlite`` installed by default. |
63 |
|
64 |
|
65 |
MySQL |
66 |
~~~~~ |
67 |
MySQL must be installed first: |
68 |
|
69 |
.. code-block:: console |
70 |
|
71 |
# apt-get install libmysqlclient-dev |
72 |
|
73 |
if you are using MacPorts: |
74 |
|
75 |
.. code-block:: console |
76 |
|
77 |
$ sudo port install mysql5 |
78 |
|
79 |
.. note:: |
80 |
|
81 |
On MacOSX with Mysql install from MacPorts the above command will |
82 |
fail complaining that it cannot find the mysql_config command. Do |
83 |
the following and restart the installation: |
84 |
|
85 |
.. code-block:: console |
86 |
|
87 |
$ echo "mysql_config = /opt/local/bin/mysql_config5" >> ./build/MySQL-python/site.cfg |
88 |
|
89 |
Configure a MySQL db/account for the Django project: |
90 |
|
91 |
.. code-block:: console |
92 |
|
93 |
$ mysql -u root -p; |
94 |
|
95 |
.. code-block:: mysql |
96 |
|
97 |
CREATE DATABASE <database name>; |
98 |
SHOW DATABASES; |
99 |
GRANT ALL ON <database name>.* TO <db username> IDENTIFIED BY '<db password>'; |
100 |
|
101 |
.. warning:: |
102 |
MySQL *must* be set in ``READ-COMMITED`` mode, e.g. by setting: |
103 |
|
104 |
.. code-block:: ini |
105 |
|
106 |
transaction-isolation = READ-COMMITTED |
107 |
|
108 |
in the ``[mysqld]`` section of :file:`/etc/mysql/my.cnf`. |
109 |
|
110 |
Alternatively, make sure the following code fragment stays enabled |
111 |
in your custom settings, e.g., in :file:`/etc/synnefo/10-database.conf`: |
112 |
|
113 |
.. code-block:: python |
114 |
|
115 |
if DATABASES['default']['ENGINE'].endswith('mysql'): |
116 |
DATABASES['default']['OPTIONS'] = { |
117 |
'init_command': 'SET storage_engine=INNODB; ' + |
118 |
'SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED', |
119 |
} |
120 |
|
121 |
PostgreSQL |
122 |
~~~~~~~~~~ |
123 |
|
124 |
You need to install the PostgreSQL binaries, e.g., for Debian: |
125 |
|
126 |
.. code-block:: console |
127 |
|
128 |
# apt-get install postgresql-8.4 libpq-dev |
129 |
|
130 |
or ir you are using MacPorts: |
131 |
|
132 |
.. code-block:: console |
133 |
|
134 |
$ sudo port install postgresql84 |
135 |
|
136 |
To configure a postgres db/account for synnefo, |
137 |
|
138 |
* Become the postgres user, connect to PostgreSQL: |
139 |
|
140 |
.. code-block:: console |
141 |
|
142 |
$ sudo su - postgres |
143 |
$ psql |
144 |
|
145 |
* Run the following commands: |
146 |
|
147 |
.. code-block:: sql |
148 |
|
149 |
DROP DATABASE <database name>; |
150 |
DROP USER <db username>; |
151 |
CREATE USER <db username> WITH PASSWORD '<db password>'; |
152 |
CREATE DATABASE <database name>; |
153 |
GRANT ALL PRIVILEGES ON DATABASE <database name> TO <db username>; |
154 |
ALTER DATABASE <database name> OWNER TO <db username>; |
155 |
ALTER USER <db username> CREATEDB; |
156 |
|
157 |
.. note:: |
158 |
The last line enables the newly created user to create own databases. This |
159 |
is needed for Django to create and drop the ``test_synnefo`` database for |
160 |
unit testing. |
161 |
|
162 |
DB driver |
163 |
````````` |
164 |
|
165 |
Depending on your DB of choice, install one of the following: |
166 |
|
167 |
========= ======================= =================== ========== |
168 |
Database PyPi package name Debian package name version |
169 |
========= ======================= =================== ========== |
170 |
mysql MySQL-python python-mysql 1.2.3 |
171 |
postgres psycopg2 python-psycopg2 2.4 |
172 |
========= ======================= =================== ========== |
173 |
|
174 |
.. note:: |
175 |
The python sqlite driver is available by default with Python so no |
176 |
additional configuration is required. Also, most self-respecting systems |
177 |
have the sqlite library installed by default. |
178 |
|
179 |
DB settings |
180 |
``````````` |
181 |
|
182 |
Add the following to your custom :ref:`snf-common <snf-common>`, depending on |
183 |
your choice of DB: |
184 |
|
185 |
SQLite |
186 |
~~~~~~ |
187 |
.. code-block:: python |
188 |
|
189 |
DATABASES = { |
190 |
'default': { |
191 |
'ENGINE': 'django.db.backends.sqlite3', |
192 |
'NAME': '/path/to/synnefo.db' |
193 |
} |
194 |
} |
195 |
|
196 |
.. warning:: ``NAME`` must be an absolute path to the sqlite3 database file |
197 |
|
198 |
|
199 |
MySQL |
200 |
~~~~~ |
201 |
|
202 |
.. code-block:: python |
203 |
|
204 |
DATABASES = { |
205 |
'default': { |
206 |
'ENGINE': 'django.db.backends.mysql', |
207 |
'NAME': 'synnefo', |
208 |
'USER': 'USERNAME', |
209 |
'PASSWORD': 'PASSWORD', |
210 |
'HOST': 'HOST', |
211 |
'PORT': 'PORT', |
212 |
'OPTIONS': { |
213 |
'init_command': 'SET storage_engine=INNODB', |
214 |
} |
215 |
} |
216 |
} |
217 |
|
218 |
PostgreSQL |
219 |
~~~~~~~~~~ |
220 |
|
221 |
.. code-block:: python |
222 |
|
223 |
DATABASES = { |
224 |
'default': { |
225 |
'ENGINE': 'django.db.backends.postgresql_psycopg2', |
226 |
'NAME': 'DATABASE', |
227 |
'USER': 'USERNAME', |
228 |
'PASSWORD': 'PASSWORD', |
229 |
'HOST': 'HOST', |
230 |
'PORT': 'PORT', |
231 |
} |
232 |
} |
233 |
|
234 |
Try it out. The following command will attempt to connect to the DB and |
235 |
print out DDL statements. It should not fail. |
236 |
|
237 |
.. code-block:: console |
238 |
|
239 |
$ snf-manage sql db |
240 |
|
241 |
Web server |
242 |
********** |
243 |
|
244 |
You need to configure your webserver to serve static files and relay |
245 |
requests to :ref:`snf-webproject <snf-webproject>`. |
246 |
|
247 |
|
248 |
.. static_files:: |
249 |
Static files |
250 |
```````````` |
251 |
|
252 |
:ref:`snf-webproject <snf-webproject>` provides a helper mechanism to avoid tedious |
253 |
tasks involving the collection and deployment of installed applications static |
254 |
files (js/css/images etc.). The mechanism tries to mimic the ``staticfiles`` |
255 |
application included in ``Django>=1.3`` but its far less robust and adequate |
256 |
regarding its capabilities. When ``Django>=1.3`` become available as a package |
257 |
for the stable release of ``Debian``, the current mechanism will get wiped off |
258 |
to be replaced by the ``staticfiles`` contrib application. |
259 |
|
260 |
The current mechanism provides a tool to collect the static files of the synnefo |
261 |
components installed and enabled in your system and an automatic way of serving |
262 |
those files directly from your django project. Be concerned that the latter is |
263 |
for debugging pupropses only since serving static files from your django project |
264 |
is considered as a bad practice. |
265 |
|
266 |
Each django based synnefo component informs webproject mechanism for the static |
267 |
files it contains using the ``synnefo.web_static`` entry point which should point |
268 |
to a dict containing a map of a python module and a namespace for the url under |
269 |
which the files will be served from. As an example of use we can see how |
270 |
snf-cyclades-app informs webproject for the static files of ui and admin applications. |
271 |
|
272 |
in ``setup.py``:: |
273 |
|
274 |
... |
275 |
entry_points = { |
276 |
... |
277 |
'synnefo': [ |
278 |
... |
279 |
'web_static = synnefo.app_settings:synnefo_static_files', |
280 |
... |
281 |
] |
282 |
}, |
283 |
... |
284 |
|
285 |
and inside ``synnefo/app_settings/__init__.py``:: |
286 |
|
287 |
synnefo_static_files = { |
288 |
'synnefo.ui': 'ui', |
289 |
'synnefo.admin': 'admin', |
290 |
} |
291 |
|
292 |
|
293 |
Collecting static files |
294 |
^^^^^^^^^^^^^^^^^^^^^^^ |
295 |
|
296 |
* Choose an appropriate path (e.g. :file:`/var/lib/synnefo/static/`) from which |
297 |
your web server will serve all static files (js/css) required by the synnefo |
298 |
web frontend to run. |
299 |
* Change the ``MEDIA_ROOT`` value in your settings (see :ref:`snf-common |
300 |
<snf-common>`) to point to that directory. |
301 |
* Create symlinks to the static files of all synnefo webapp components |
302 |
inside the chosen directory, by running: |
303 |
|
304 |
.. code-block:: console |
305 |
|
306 |
$ snf-manage link_static |
307 |
|
308 |
|
309 |
Serving static files |
310 |
^^^^^^^^^^^^^^^^^^^^ |
311 |
|
312 |
By default will serve the static files if ``DEBUG`` setting is set to True. |
313 |
You can override this behaviour by explicitly setting the |
314 |
``WEBPROJECT_SERVE_STATIC`` to True or False in your settings files. |
315 |
|
316 |
|
317 |
Apache |
318 |
`````` |
319 |
|
320 |
.. todo:: document Apache configuration |
321 |
|
322 |
nginx |
323 |
````` |
324 |
This section describes a sample nginx configuration which uses FastCGI |
325 |
to relay requests to synnefo. |
326 |
|
327 |
First, use a distribution-specific mechanism (e.g., APT) to install nginx: |
328 |
|
329 |
.. code-block:: console |
330 |
|
331 |
# apt-get install nginx |
332 |
|
333 |
Then activate the following nginx configuration file by placing it under |
334 |
:file:`/etc/nginx/sites-available` and symlinking under |
335 |
:file:`/etc/nginx/sites-enabled`: |
336 |
|
337 |
.. literalinclude:: ../_static/synnefo.nginx.conf |
338 |
|
339 |
.. todo:: fix the location of the configuration file |
340 |
|
341 |
`download <../_static/synnefo.nginx.conf>`_ |
342 |
|
343 |
Once nginx is configured, run the FastCGI server to receive incoming requests |
344 |
from nginx. This requires installation of package ``flup``: |
345 |
|
346 |
.. code-block:: console |
347 |
|
348 |
# apt-get install flup |
349 |
$ snf-manage runfcgi host=127.0.0.1 port=8015 |
350 |
|
351 |
|
352 |
For developers |
353 |
-------------- |
354 |
|
355 |
Available entry points |
356 |
^^^^^^^^^^^^^^^^^^^^^^ |
357 |
|
358 |
web_apps |
359 |
```````` |
360 |
Extends INSTALLED_APPS django project setting. |
361 |
|
362 |
Example:: |
363 |
|
364 |
# myapp/synnefo_settings.py |
365 |
# synnefo_settings and variable name is arbitary |
366 |
my_app_web_apps = ['myapp', 'south', 'django.contrib.sessions'] |
367 |
|
368 |
# another more complex configuration where we need our app to be placed |
369 |
# before django.contrib.admin app because it overrides some of the admin |
370 |
# templates used by admin app views |
371 |
my_app_web_apps = [{'before':'django.contrib.admin', 'insert':'myapp'}, 'south'] |
372 |
|
373 |
# setup.py |
374 |
entry_points = { |
375 |
'synnefo': ['web_apps = myapp.synnefo_settings:my_app_web_apps'] |
376 |
} |
377 |
|
378 |
|
379 |
web_middleware |
380 |
`````````````` |
381 |
Extends MIDDLEWARE_CLASSES django setting. |
382 |
|
383 |
|
384 |
web_static |
385 |
`````````` |
386 |
Extends STATIC_FILES setting (see `static_files`_). |
387 |
|
388 |
|
389 |
web_context_processors |
390 |
`````````````````````` |
391 |
Extends TEMPLATE_CONTEXT_PROCESSORS django setting. |
392 |
|
393 |
|
394 |
loggers |
395 |
``````` |
396 |
Extends `snf-common`_ LOGGING_SETUP['loggers'] setting. |
397 |
|
398 |
|
399 |
urls |
400 |
```` |
401 |
Extends django project urls. Accepts a urlpatterns variable. The urls defined |
402 |
in this variable will be used to extend the django project urls. |