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

b/snf-app/docs/src/admin-guide.rst
1
.. _snf-compute-admin-guide:
1
.. _snf-asterias-admin-guide:
2 2

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

  
6
This is the snf-compute administrator guide.
7
This is the asterias administrator guide.
7 8

  
8 9
It contains instructions on how to download, install and configure
9 10
the synnefo components necessary to deploy the Compute Service. It also covers
......
16 17
--------
17 18

  
18 19
This guide covers the following:
19
Compute architecture
20
    Node types needed for a complete deployment of snf-compute,
20

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

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

  
42 44
.. _DB_NODE:
......
46 48

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

  
51
_Services:_ PostgreSQL / MySQL
53
*Services:* PostgreSQL / MySQL
52 54

  
53 55
.. _APISERVER_NODE:
54 56

  
55 57
APISERVER
56 58
*********
57
A node running the implementation of the OpenStack API, in Django. Any number
58
of APISERVERs can be used, in a load-balancing configuration, without any
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
59 63
special consideration. Access to a common DB ensures consistency.
60
_Services:_ Web server, vncauthproxy
64

  
65
*Services:* Web server, vncauthproxy
61 66

  
62 67

  
63 68
.. _QUEUE_NODE:
......
65 70
QUEUE
66 71
*****
67 72
A node running the RabbitMQ software, which provides AMQP functionality. More
68
than one QUEUE nodes may be deployed, in an HA configuration. Such
69
deployments require shared storage, provided e.g., by DRBD.
70
_Services:_ RabbitMQ [rabbitmq-server]
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]
71 77

  
72 78

  
73 79
.. _LOGIC_NODE:
......
80 86
functions run. It uses Django ORM to connect to the common DB and update the
81 87
state of the system, based on notifications received from the rest of the
82 88
infrastructure, over AMQP.
83
_Services:_ the synnefo logic dispatcher, ``snf-dispatcher``
89

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

  
85 92

  
86 93
.. _GANETI_NODES:
......
95 102
changes in the state of the VMs. The GANETI-MASTER runs the Ganeti request
96 103
queue.
97 104

  
98
_Services:_
105
*Services:*
99 106
    * only on :ref:`GANETI-MASTER <GANETI_MASTER>`:
100 107
        * the synnefo Ganeti monitoring daemon, ``snf-ganeti-eventd``
101 108
        * the synnefo Ganeti hook, ``ganeti/snf-ganeti-hook.py``.
......
108 115
WEBAPP
109 116
******
110 117
A WEBAPP node runs the web application provided by the synnefo component
111
:ref:`snf-app <snf-app>`.
118
:ref:`snf-asterias-app <snf-asterias-app>`.
112 119

  
113 120
Installation
114 121
------------
115 122

  
116
Depending on the type of the node, you need to install the following synnefo
117
components:
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.
118 364

  
119 365
Nodes of type :ref:`APISERVER <APISERVER_NODE>`
120 366
    Components
121 367
    :ref:`snf-common <snf-common>`,
122 368
    :ref:`snf-webproject <snf-webproject>`,
123
    :ref:`snf-app <snf-app>`
369
    :ref:`snf-asterias-app <snf-asterias-app>`
124 370
Nodes of type :ref:`GANETI-MASTER <GANETI_MASTER>` and :ref:`GANETI-NODE <GANETI_NODE>`
125 371
    Components
126 372
    :ref:`snf-common <snf-common>`,
127 373
    :ref:`snf-ganeti-tools <snf-ganeti-tools>`
128
Nodes of type :ref:`LOGIC <LOGIC>`
374
Nodes of type :ref:`LOGIC <LOGIC_NODE>`
129 375
    Components
130 376
    :ref:`snf-common <snf-common>`,
131 377
    :ref:`snf-webproject <snf-webproject>`,
132
    :ref:`snf-app <snf-app>`.
378
    :ref:`snf-asterias-app <snf-asterias-app>`.
133 379

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

  
136 382
Configuration
137 383
-------------
138 384

  
139
The Compute Service uses :ref:`snf-common <snf-common>` for settings.
140

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

  
142 387
Web admin
143 388
`````````
......
158 403
on :ref:`LOGIC <LOGIC_NODE>` nodes.
159 404

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

  
164 409
The default configuration should work directly without any modifications.
......
181 426
Static files
182 427
************
183 428

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

  
236 481
snf-burnin
237 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.

Also available in: Unified diff