Statistics
| Branch: | Tag: | Revision:

root / snf-webproject / docs / index.rst @ 34e79416

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://www.synnefo.org/packages/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.