Statistics
| Branch: | Tag: | Revision:

root / snf-app / docs / src / admin-guide.rst @ 252bb277

History | View | Annotate | Download (25.5 kB)

1
.. _snf-asterias-admin-guide:
2

    
3
===================
4
Administrator Guide
5
===================
6

    
7
This is the asterias administrator guide.
8

    
9
It contains instructions on how to download, install and configure
10
the synnefo components necessary to deploy the Compute Service. It also covers
11
maintenance issues, e.g., upgrades of existing deployments.
12

    
13
The guide assumes you are familiar with all aspects of downloading, installing
14
and configuring packages for the Linux distribution of your choice.
15

    
16
Overview
17
--------
18

    
19
This guide covers the following:
20

    
21
Architecture
22
    Node types needed for a complete deployment of asterias,
23
    and their roles. Throughout this guide, `node` refers to a physical machine
24
    in the deployment.
25
Installation
26
    The installation of services and synnefo software components for a working
27
    deployment of asterias, either from source packages or the provided
28
    packages for Debian Squeeze.
29
Configuration
30
    Configuration of the various software components comprising an asterias
31
    deployment.
32
Upgrades
33
Changelogs
34

    
35
.. todo:: describe prerequisites -- e.g., Debian
36
.. todo:: describe setup of nginx, flup, synnefo packages, etc.
37

    
38
Architecture
39
------------
40

    
41
Nodes in an asterias deployment belong in one of the following types.
42
For every type, we list the services that execute on corresponding nodes.
43

    
44
.. _DB_NODE:
45

    
46
DB
47
**
48

    
49
A node [or more than one nodes, if using an HA configuration], running a DB
50
engine supported by the Django ORM layer. The DB is the single source of
51
truth for the servicing of API requests by asterias.
52

    
53
*Services:* PostgreSQL / MySQL
54

    
55
.. _APISERVER_NODE:
56

    
57
APISERVER
58
*********
59
A node running the ``api`` application contained in
60
:ref:`snf-asterias-app <snf-asterias-app>`. Any number of
61
:ref:`APISERVER <APISERVER_NODE>` nodes
62
can be used, in a load-balancing configuration, without any
63
special consideration. Access to a common DB ensures consistency.
64

    
65
*Services:* Web server, vncauthproxy
66

    
67

    
68
.. _QUEUE_NODE:
69

    
70
QUEUE
71
*****
72
A node running the RabbitMQ software, which provides AMQP functionality. More
73
than one :ref:`QUEUE <QUEUE_NODE>` nodes may be deployed, in an HA
74
configuration. Such deployments require shared storage, provided e.g., by DRBD.
75

    
76
*Services:* RabbitMQ [rabbitmq-server]
77

    
78

    
79
.. _LOGIC_NODE:
80

    
81
LOGIC
82
*****
83

    
84
A node running the business logic of synnefo, in Django. It dequeues
85
messages from QUEUE nodes, and provides the context in which business logic
86
functions run. It uses Django ORM to connect to the common DB and update the
87
state of the system, based on notifications received from the rest of the
88
infrastructure, over AMQP.
89

    
90
*Services:* the synnefo logic dispatcher, ``snf-dispatcher``
91

    
92

    
93
.. _GANETI_NODES:
94
.. _GANETI_MASTER:
95
.. _GANETI_NODE:
96
  
97
GANETI-MASTER and GANETI-NODE
98
*****************************
99
A single GANETI-MASTER and a large number of GANETI-NODEs constitute the
100
Ganeti backend for synnefo, which undertakes all VM management functions.
101
Any APISERVER can issue commands to the GANETI-MASTER, over RAPI, to effect
102
changes in the state of the VMs. The GANETI-MASTER runs the Ganeti request
103
queue.
104

    
105
*Services:*
106
    * only on :ref:`GANETI-MASTER <GANETI_MASTER>`:
107
        * the synnefo Ganeti monitoring daemon, ``snf-ganeti-eventd``
108
        * the synnefo Ganeti hook, ``ganeti/snf-ganeti-hook.py``.
109
    * on every :ref:`GANETI-NODE <GANETI_NODE>`:
110
        * a deployment-specific KVM ifup script
111
        * properly configured :ref:`NFDHCPD <nfdhcpd-setup>`
112

    
113
.. _WEBAPP_NODE:
114

    
115
WEBAPP
116
******
117
A WEBAPP node runs the web application provided by the synnefo component
118
:ref:`snf-asterias-app <snf-asterias-app>`.
119

    
120
Installation
121
------------
122

    
123
Installation of asterias is a two step process:
124

    
125
1. install the external services (prerequisites) on which asterias depends
126
2. install the synnefo software components associated with asterias
127

    
128
Prerequisites
129
*************
130
.. _ganeti-setup:
131

    
132
1. Ganeti installation
133
``````````````````````
134
Synnefo requires a working Ganeti installation at the backend. Installation
135
of Ganeti is not covered by this document, please refer to
136
`ganeti documentation <http://docs.ganeti.org/ganeti/current/html>`_ for all the 
137
gory details. A successful Ganeti installation concludes with a working 
138
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs <GANETI_NODES>`.
139

    
140
2. Database
141
```````````
142

    
143
SQLite
144
~~~~~~
145
Most self-respecting systems have ``sqlite`` installed by default.
146

    
147
MySQL
148
~~~~~
149
MySQL must be installed first:
150

    
151
.. code-block:: console
152

    
153
    $ sudo apt-get install libmysqlclient-dev
154

    
155
if you are using MacPorts:
156

    
157
.. code-block:: console
158

    
159
    $ sudo port install mysql5
160

    
161
.. note::
162

    
163
    On MacOSX with Mysql install from MacPorts the above command will
164
    fail complaining that it cannot find the mysql_config command. Do
165
    the following and restart the installation:
166

    
167
    .. code-block:: console
168

    
169
       $ echo "mysql_config = /opt/local/bin/mysql_config5" >> ./build/MySQL-python/site.cfg
170

    
171
Configure a MySQL db/account for the Django project:
172

    
173
.. code-block:: console
174

    
175
    $ mysql -u root -p;
176

    
177
.. code-block:: mysql
178

    
179
    CREATE DATABASE <database name>;
180
    SHOW DATABASES;
181
    GRANT ALL ON <database name>.* TO <db username> IDENTIFIED BY '<db password>';
182

    
183
.. warning::
184
        MySQL *must* be set in ``READ-COMMITED`` mode, e.g. by setting:
185

    
186
   .. code-block:: ini
187
   
188
      transaction-isolation = READ-COMMITTED
189
               
190
   in the ``[mysqld]`` section of :file:`/etc/mysql/my.cnf`.
191

    
192
   Alternatively, make sure the following code fragment stays enabled
193
   in :file:`/etc/synnefo/10-database.conf` file:
194
       
195
   .. code-block:: python
196
   
197
       if DATABASES['default']['ENGINE'].endswith('mysql'):
198
           DATABASES['default']['OPTIONS'] = {
199
                   'init_command': 'SET storage_engine=INNODB; ' +
200
                       'SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED',
201
           }
202
   
203
PostgreSQL
204
~~~~~~~~~~
205

    
206
You need to install the PostgreSQL binaries, e.g., for Debian:
207

    
208
.. code-block:: console
209
	     
210
    $ sudo apt-get install postgresql-8.4 libpq-dev
211

    
212
or ir you are using MacPorts:
213

    
214
.. code-block:: console
215

    
216
    $ sudo port install postgresql84
217

    
218
To configure a postgres db/account for synnefo,
219

    
220
*  Become the postgres user, connect to PostgreSQL:
221

    
222
.. code-block:: console
223

    
224
       $ sudo su - postgres
225
       $ psql
226
	
227
* Run the following commands:
228

    
229
.. code-block:: sql
230

    
231
	   DROP DATABASE <database name>;
232
	   DROP USER <db username>;
233
	   CREATE USER <db username> WITH PASSWORD '<db password>';
234
	   CREATE DATABASE <database name>;
235
	   GRANT ALL PRIVILEGES ON DATABASE <database name> TO <db username>;
236
	   ALTER DATABASE <database name> OWNER TO <db username>;
237
	   ALTER USER <db username> CREATEDB;
238
       
239
.. note:: 
240
   The last line enables the newly created user to create own databases. This
241
   is needed for Django to create and drop the ``test_synnefo`` database for
242
   unit testing.
243

    
244
3. RabbitMQ 
245
```````````
246

    
247
RabbitMQ is used as a generic message broker for asterias. It should be
248
installed on two seperate :ref:`QUEUE <QUEUE_NODE>` nodes in a high availability
249
configuration as described here:
250

    
251
    http://www.rabbitmq.com/pacemaker.html
252

    
253
After installation, create a user and set its permissions:
254

    
255
.. code-block:: console
256

    
257
    $ rabbitmqctl add_user <username> <password>
258
    $ rabbitmqctl set_permissions -p / <username>  "^.*" ".*" ".*"
259

    
260
The values set for the user and password must be mirrored in the
261
``RABBIT_*`` variables in your settings, as managed by
262
:ref:`snf-common <snf-common>`.
263

    
264
.. todo:: Document an active-active configuration based on the latest version
265
   of RabbitMQ.
266

    
267
4. vncauthproxy
268
```````````````
269

    
270
To support OOB console access to the VMs over VNC, the vncauthproxy
271
daemon must be running on every :ref:`APISERVER <APISERVER_NODE>` node.
272

    
273
.. note:: The Debian package for vncauthproxy undertakes all configuration
274
   automatically.
275

    
276
Download and install the latest vncauthproxy from its own repository,
277
at `https://code.grnet.gr/git/vncauthproxy`, or a specific commit:
278

    
279
.. code-block:: console
280

    
281
    $ bin/pip install -e git+https://code.grnet.gr/git/vncauthproxy@INSERT_COMMIT_HERE#egg=vncauthproxy
282

    
283
Create ``/var/log/vncauthproxy`` and set its permissions appropriately.
284

    
285
Alternatively, build and install Debian packages.
286

    
287
.. code-block:: console
288

    
289
    $ git checkout debian
290
    $ dpkg-buildpackage -b -uc -us
291
    # dpkg -i ../vncauthproxy_1.0-1_all.deb
292

    
293
.. warning::
294
    **Failure to build the package on the Mac.**
295

    
296
    ``libevent``, a requirement for gevent which in turn is a requirement for
297
    vncauthproxy is not included in `MacOSX` by default and installing it with
298
    MacPorts does not lead to a version that can be found by the gevent
299
    build process. A quick workaround is to execute the following commands::
300

    
301
        $ cd $SYNNEFO
302
        $ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy
303
        <the above fails>
304
        $ cd build/gevent
305
        $ sudo python setup.py -I/opt/local/include -L/opt/local/lib build
306
        $ cd $SYNNEFO
307
        $ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy
308

    
309
.. todo:: Mention vncauthproxy bug, snf-vncauthproxy, inability to install using pip
310
.. todo:: kpap: fix installation commands
311

    
312
.. _nfdhcpd-setup:
313

    
314
5. NFDHCPD
315
``````````
316

    
317
Setup Synnefo-specific networking on the Ganeti backend.
318
This part is deployment-specific and must be customized based on the
319
specific needs of the system administrators.
320

    
321
A reference installation will use a Synnefo-specific KVM ifup script,
322
NFDHCPD and pre-provisioned Linux bridges to support public and private
323
network functionality. For this:
324

    
325
Grab NFDHCPD from its own repository (https://code.grnet.gr/git/nfdhcpd),
326
install it, modify ``/etc/nfdhcpd/nfdhcpd.conf`` to reflect your network
327
configuration.
328

    
329
Install a custom KVM ifup script for use by Ganeti, as
330
``/etc/ganeti/kvm-vif-bridge``, on GANETI-NODEs. A sample implementation is
331
provided under ``/contrib/ganeti-hooks``. Set ``NFDHCPD_STATE_DIR`` to point
332
to NFDHCPD's state directory, usually ``/var/lib/nfdhcpd``.
333

    
334
.. todo:: soc: document NFDHCPD installation, settle on KVM ifup script
335

    
336
.. _rabbitmq-setup:
337

    
338
6. snf-image
339
````````````
340

    
341
Install the :ref:`snf-image <snf-image>` Ganeti OS provider for image
342
deployment.
343

    
344
For :ref:`asterias <snf-asterias>` to be able to launch VMs from specified
345
Images, you need the snf-image OS Provider installed on *all* Ganeti nodes.
346

    
347
Please see `https://code.grnet.gr/projects/snf-image/wiki`_
348
for installation instructions and documentation on the design
349
and implementation of snf-image.
350

    
351
Please see `https://code.grnet.gr/projects/snf-image/files`
352
for the latest packages.
353

    
354
Images should be stored under extdump format in a directory
355
of your choice, configurable as ``IMAGE_DIR`` in 
356
:file:`/etc/default/snf-image`.
357

    
358
synnefo components
359
******************
360

    
361
You need to install the following synnefo components on each node,
362
depending on its type. Please see the page of each synnefo software
363
component for specific installation instructions, where applicable.
364

    
365
Nodes of type :ref:`APISERVER <APISERVER_NODE>`
366
    Components
367
    :ref:`snf-common <snf-common>`,
368
    :ref:`snf-webproject <snf-webproject>`,
369
    :ref:`snf-asterias-app <snf-asterias-app>`
370
Nodes of type :ref:`GANETI-MASTER <GANETI_MASTER>` and :ref:`GANETI-NODE <GANETI_NODE>`
371
    Components
372
    :ref:`snf-common <snf-common>`,
373
    :ref:`snf-ganeti-tools <snf-ganeti-tools>`
374
Nodes of type :ref:`LOGIC <LOGIC_NODE>`
375
    Components
376
    :ref:`snf-common <snf-common>`,
377
    :ref:`snf-webproject <snf-webproject>`,
378
    :ref:`snf-asterias-app <snf-asterias-app>`.
379

    
380
.. todo:: describe prerequisites -- e.g., Debian
381

    
382
Configuration
383
-------------
384

    
385
asterias uses :ref:`snf-common <snf-common>` for settings.
386

    
387
Web admin
388
`````````
389
synnefo web administration interface. Allows administrator users to manage the
390
synnefo application via web interface.
391

    
392
Web application
393
```````````````
394
Web interface which allows users to create/configure/manage their virtual
395
machines.
396

    
397
.. _dispatcher-deploy:
398

    
399
Dispatcher
400
----------
401

    
402
The logic dispatcher is part of the synnefo Django project and must run
403
on :ref:`LOGIC <LOGIC_NODE>` nodes.
404

    
405
The dispatcher retrieves messages from the queue and calls the appropriate
406
handler function as defined in the queue configuration in :file:`/etc/synnefo/*.conf`
407
files.
408

    
409
The default configuration should work directly without any modifications.
410

    
411
For the time being The dispatcher must be run by hand::
412

    
413
  $ snf-dispatcher
414

    
415
The dispatcher should run in at least 2 instances to ensure high
416
(actually, increased) availability.
417

    
418

    
419
.. _webapp-deploy:
420

    
421
Web application deployment
422
--------------------------
423

    
424
.. _static-files:
425

    
426
Static files
427
************
428

    
429
* Choose an appropriate path (e.g. :file:`/var/lib/synnefo/static/`) from which
430
  your web server will serve all static files (js/css) required by the synnefo
431
  web frontend to run.
432
* Change the ``MEDIA_ROOT`` value in your settings to point to that directory.
433
* Run the following command::
434

    
435
    $ snf-manage link_static
436

    
437
  the command will create symlinks of the appropriate static files inside the
438
  chosen directory.
439

    
440
.. todo:: describe an ``snf-manage copy_static`` command.
441

    
442
Using Apache
443
************
444

    
445
.. todo:: document apache configuration
446

    
447
Using nginx
448
***********
449

    
450
This section describes a sample nginx configuration which uses FastCGI
451
to relay requests to synnefo. Use a distribution-specific mechanism
452
(e.g., APT) to install nginx, then activate the following nginx configuration
453
file by placing it under ``/etc/nginx/sites-available`` and symlinking
454
under ``/etc/nginx/sites-enabled``:
455

    
456
.. literalinclude:: ../_static/synnefo.nginx.conf
457

    
458
`download <../_static/synnefo.nginx.conf>`_
459

    
460
then run the FastCGI server to receive incoming requests from nginx.
461
This requires installation of package flup, e.g. with::
462
    # apt-get install flup
463
    $ snf-manage runfcgi host=127.0.0.1 port=8015
464

    
465

    
466
Console scripts
467
---------------
468

    
469
snf-manage
470
**************
471

    
472
snf-dispatcher
473
******************
474

    
475
snf-admin
476
*************
477

    
478
snf-cloud
479
*************
480

    
481
snf-burnin
482
**************
483

    
484

    
485

    
486
.. _installation:
487

    
488

    
489
.. _database-setup:
490

    
491

    
492

    
493
Installing depedencies
494
**********************
495

    
496
Synnefo is written in Python 2.6 requires the some additional python packages 
497
to run properly.
498

    
499
The easiest method for installation of the Django project is to setup a
500
working environment through virtualenv. Alternatively, you can use your
501
system's package manager to install the dependencies (e.g. Macports has them
502
all).
503

    
504
You can install these packages either using `pip` python package manager::
505
    
506
    $ pip install <pypi-package-name>==<version>
507

    
508
or using the requirements.pip file that exists in Synnefo package repository::
509

    
510
    $ pip install -r requirements.pip
511

    
512
or Debian's `apt-get`::
513

    
514
    $ apt-get install <debian-package-name>
515

    
516

    
517
Required packages
518
`````````````````
519

    
520
.. todo::
521
    Confirm debian package names
522

    
523
=======================     ===================         ==========
524
PyPi package name           Debian package name         version   
525
=======================     ===================         ==========
526
django                      python-django               1.2.4      
527
simplejson                  python-simplejson           2.1.3
528
pycurl                      python-pycurl               7.19.0
529
python-dateutil             python-dateutil             1.4.1
530
IPy                         python-ipy                  0.75
531
south                       python-django-south         0.7.1
532
amqplib                     python-amqplib              0.6.1
533
lockfile                    python-lockfile             0.8
534
python-daemon               python-daemon               1.5.5
535
python-prctl                python-prctl                1.3.0
536
=======================     ===================         ==========
537

    
538
.. note::
539
    On Snow Leopard and linux (64-bit), you have to set the following
540
    environment variable for pip to compile the dependencies correctly::
541

    
542
        $ export ARCHFLAGS="-arch x86_64"
543

    
544
.. note::
545
    On Ubuntu/Debian, a few more packages must be installed before installing the
546
    prerequisite Python libraries::
547

    
548
        $ sudo aptitude install libcurl3-gnutls libcurl3-gnutls-dev uuid-dev
549

    
550
.. note::
551
    Depending on the permissions of your system’s Python, you might need to be the 
552
    root user to install those packages system-wide
553

    
554

    
555
Database driver
556
```````````````
557

    
558
Depending on the database software you choose to use one of the following:
559

    
560
=========     =======================     ===================         ==========
561
Database      PyPi package name           Debian package name         version   
562
=========     =======================     ===================         ==========
563
mysql         MySQL-python                python-mysql                1.2.3
564
postgres      psycopg2                    python-psycopg2             2.4  
565
=========     =======================     ===================         ==========
566

    
567
.. note::
568
    The python sqlite driver is available by default with Python so no
569
    additional configuration is required. Also, most self-respecting systems
570
    have the sqlite library installed by default.
571

    
572

    
573
Extra depedencies
574
`````````````````
575

    
576
Synnefo provides some optional features that require specific python packages to
577
be installed.
578

    
579
**Invitations and SSH Keys generation**
580

    
581
=======================     ===================         ==========
582
PyPi package name           Debian package name         version   
583
=======================     ===================         ==========
584
pycrypto                    python-crypto               2.1.0      
585
=======================     ===================         ==========
586

    
587

    
588

    
589
Installing Synnefo package
590
--------------------------
591

    
592
Using ``pip``::
593

    
594
    $ pip install https://code.grnet.gr/projects/synnefo/synnefo-<version>.tar.gz --no-deps
595

    
596
by checking out git repository::
597

    
598
    $ git clone https://code.grnet.gr/git/synnefo synnefo-repo
599
    $ cd synnefo-repo
600
    $ python setup.py install
601

    
602
this should be enough for synnefo to get installed in your system-wide or
603
``virtualenv`` python installation and the following commands should be 
604
available from the command line::
605

    
606
    $ snf-manage
607
    $ snf-dispatcher
608
    $ snf-admin
609

    
610
Notice that Synnefo installation does not handle the creation of
611
``/etc/synnefo/`` directory which is the place where custom configuration 
612
files are loaded from. You are encouraged to create this directory and place a 
613
file named ``settings.conf`` with the following contents:
614

    
615
.. _sample-settings:
616
.. literalinclude:: ../_static/sample_settings.conf
617
    :language: python
618

    
619
`download <../_static/sample_settings.conf>`_
620

    
621
this is just to get you started on how to configure your Synnefo installation.
622
From this point you can continue your read to the `Initial configuration`_ section 
623
in this document which contains quickstart instructions for some of the initial
624
configuration required for Synnefo to get up and running.
625

    
626
For additional instructions about Synnefo settings files and what the available 
627
settings are, you can refer to the :ref:`configuration <configuration>` guide.
628

    
629

    
630
Initial configuration
631
---------------------
632

    
633
Synnefo comes with most of the required settings predefined with values that 
634
would cover many of the most common installation scenarios. However some basic
635
settings must be set be set before running Synnefo for the first time.
636

    
637
:ref:`sample settings file <sample-settings>`
638

    
639

    
640
Database
641
********
642

    
643
Change ``DATABASES`` setting based on your :ref:`database setup <database-setup>` 
644
and :ref:`initialize/update your database structure <database-initialization>`
645

    
646
.. seealso::
647
    :ref:`database-configuration` /
648
    :ref:`database-initialization`
649

    
650

    
651
Queue
652
*****
653

    
654
Change ``RABBIT_*`` settings to match your :ref:`RabbitMQ setup <rabbitmq-setup>`.
655

    
656

    
657
Backend
658
*******
659

    
660
Set ``GANETI_NODES``, ``GANETI_MASTER_IP``, ``GANETI_CLUSTER_INFO`` based on your :ref:`Ganeti
661
installation <ganeti-setup>` and change BACKEND_PREFIX_ID using an custom `prefix
662
id`.
663

    
664

    
665
Web application
666
***************
667

    
668
See the extended :ref:`deployment guide <webapp-deploy>` for instructions on how to
669
setup the Synnefo web application.
670

    
671
.. _database-setup:
672

    
673
Installing depedencies
674
**********************
675

    
676
Synnefo is written in Python 2.6 requires the some additional python packages 
677
to run properly.
678

    
679
The easiest method for installation of the Django project is to setup a
680
working environment through virtualenv. Alternatively, you can use your
681
system's package manager to install the dependencies (e.g. Macports has them
682
all).
683

    
684
You can install these packages either using `pip` python package manager::
685
    
686
    $ pip install <pypi-package-name>==<version>
687

    
688
or using the requirements.pip file that exists in Synnefo package repository::
689

    
690
    $ pip install -r requirements.pip
691

    
692
or Debian's `apt-get`::
693

    
694
    $ apt-get install <debian-package-name>
695

    
696

    
697
Required packages
698
`````````````````
699

    
700
.. todo::
701
    Confirm debian package names
702

    
703
=======================     ===================         ==========
704
PyPi package name           Debian package name         version   
705
=======================     ===================         ==========
706
django                      python-django               1.2.4      
707
simplejson                  python-simplejson           2.1.3
708
pycurl                      python-pycurl               7.19.0
709
python-dateutil             python-dateutil             1.4.1
710
IPy                         python-ipy                  0.75
711
south                       python-django-south         0.7.1
712
amqplib                     python-amqplib              0.6.1
713
lockfile                    python-lockfile             0.8
714
python-daemon               python-daemon               1.5.5
715
python-prctl                python-prctl                1.3.0
716
=======================     ===================         ==========
717

    
718
.. note::
719
    On Snow Leopard and linux (64-bit), you have to set the following
720
    environment variable for pip to compile the dependencies correctly::
721

    
722
        $ export ARCHFLAGS="-arch x86_64"
723

    
724
.. note::
725
    On Ubuntu/Debian, a few more packages must be installed before installing the
726
    prerequisite Python libraries::
727

    
728
        $ sudo aptitude install libcurl3-gnutls libcurl3-gnutls-dev uuid-dev
729

    
730
.. note::
731
    Depending on the permissions of your system’s Python, you might need to be the 
732
    root user to install those packages system-wide
733

    
734

    
735
Database driver
736
```````````````
737

    
738
Depending on the database software you choose to use one of the following:
739

    
740
=========     =======================     ===================         ==========
741
Database      PyPi package name           Debian package name         version   
742
=========     =======================     ===================         ==========
743
mysql         MySQL-python                python-mysql                1.2.3
744
postgres      psycopg2                    python-psycopg2             2.4  
745
=========     =======================     ===================         ==========
746

    
747
.. note::
748
    The python sqlite driver is available by default with Python so no
749
    additional configuration is required. Also, most self-respecting systems
750
    have the sqlite library installed by default.
751

    
752

    
753
Extra depedencies
754
`````````````````
755

    
756
Synnefo provides some optional features that require specific python packages to
757
be installed.
758

    
759
**Invitations and SSH Keys generation**
760

    
761
=======================     ===================         ==========
762
PyPi package name           Debian package name         version   
763
=======================     ===================         ==========
764
pycrypto                    python-crypto               2.1.0      
765
=======================     ===================         ==========
766

    
767

    
768

    
769
Installing Synnefo package
770
--------------------------
771

    
772
Using ``pip``::
773

    
774
    $ pip install https://code.grnet.gr/projects/synnefo/synnefo-<version>.tar.gz --no-deps
775

    
776
by checking out git repository::
777

    
778
    $ git clone https://code.grnet.gr/git/synnefo synnefo-repo
779
    $ cd synnefo-repo
780
    $ python setup.py install
781

    
782
this should be enough for synnefo to get installed in your system-wide or
783
``virtualenv`` python installation and the following commands should be 
784
available from the command line::
785

    
786
    $ snf-manage
787
    $ snf-dispatcher
788
    $ snf-admin
789

    
790
Notice that Synnefo installation does not handle the creation of
791
``/etc/synnefo/`` directory which is the place where custom configuration 
792
files are loaded from. You are encouraged to create this directory and place a 
793
file named ``settings.conf`` with the following contents:
794

    
795
.. _sample-settings:
796
.. literalinclude:: ../_static/sample_settings.conf
797
    :language: python
798

    
799
`download <../_static/sample_settings.conf>`_
800

    
801
this is just to get you started on how to configure your Synnefo installation.
802
From this point you can continue your read to the `Initial configuration`_ section 
803
in this document which contains quickstart instructions for some of the initial
804
configuration required for Synnefo to get up and running.
805

    
806
For additional instructions about Synnefo settings files and what the available 
807
settings are, you can refer to the :ref:`configuration <configuration>` guide.
808

    
809

    
810
Initial configuration
811
---------------------
812

    
813
Synnefo comes with most of the required settings predefined with values that 
814
would cover many of the most common installation scenarios. However some basic
815
settings must be set be set before running Synnefo for the first time.
816

    
817
:ref:`sample settings file <sample-settings>`
818

    
819

    
820
Database
821
********
822

    
823
Change ``DATABASES`` setting based on your :ref:`database setup <database-setup>` 
824
and :ref:`initialize/update your database structure <database-initialization>`
825

    
826
.. seealso::
827
    :ref:`database-configuration` /
828
    :ref:`database-initialization`
829

    
830

    
831
Queue
832
*****
833

    
834
Change ``RABBIT_*`` settings to match your :ref:`RabbitMQ setup <rabbitmq-setup>`.
835

    
836

    
837
Backend
838
*******
839

    
840
Set ``GANETI_NODES``, ``GANETI_MASTER_IP``, ``GANETI_CLUSTER_INFO`` based on your :ref:`Ganeti
841
installation <ganeti-setup>` and change BACKEND_PREFIX_ID using an custom `prefix
842
id`.
843

    
844

    
845
Web application
846
***************
847

    
848
See the extended :ref:`deployment guide <webapp-deploy>` for instructions on how to
849
setup the Synnefo web application.