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