root / snf-app / docs / src / install.rst @ df285bb3
History | View | Annotate | Download (14.3 kB)
1 |
.. _installation: |
---|---|
2 |
|
3 |
Installation |
4 |
============ |
5 |
|
6 |
This document describes the basic steps to obtain a basic, working Synnefo |
7 |
deployment. |
8 |
|
9 |
The Synnefo package needs to be installed on nodes of type :ref:`APISERVER_NODE`, |
10 |
:ref:`LOGIC_NODE` and :ref:`WEBAPP_NODE` nodes with properly configured |
11 |
:ref:`settings <configuration>`. |
12 |
|
13 |
This guide also covers in some detail instructions on how to set up additional |
14 |
additional software required by Synnefo to run properly. |
15 |
|
16 |
|
17 |
Prerequisites |
18 |
------------- |
19 |
|
20 |
|
21 |
.. _ganeti-setup: |
22 |
|
23 |
Ganeti installation |
24 |
******************* |
25 |
Synnefo requires a working Ganeti installation at the backend. Installation |
26 |
of Ganeti is not covered by this document, please refer to |
27 |
`ganeti documentation <http://docs.ganeti.org/ganeti/current/html>`_ for all the |
28 |
gory details. A successful Ganeti installation concludes with a working |
29 |
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs <GANETI_NODES>`. |
30 |
|
31 |
|
32 |
Ganeti monitoring daemon |
33 |
```````````````````````` |
34 |
The Ganeti monitoring daemon must run on GANETI-MASTER. |
35 |
The monitoring daemon is configured through ``/etc/synnefo/ganeti.conf``. |
36 |
An example is provided under ``snf-ganeti-tools/``. |
37 |
|
38 |
If run from the repository directory, make sure to have snf-ganeti-tools/ |
39 |
in the ``PYTHONPATH``. |
40 |
You may also build Debian packages directly from the repository:: |
41 |
|
42 |
$ cd snf-ganeti-tools |
43 |
$ dpkg-buildpackage -b -uc -us |
44 |
$ dpkg -i ../snf-ganeti-tools-*deb |
45 |
|
46 |
.. todo:: |
47 |
how to handle master migration. |
48 |
|
49 |
|
50 |
Synnefo Ganeti hook |
51 |
``````````````````` |
52 |
The generic Synnefo Ganeti hook wrapper resides in the snf-ganeti-tools/ |
53 |
directory of the Synnefo repository. |
54 |
|
55 |
The hook needs to be enabled for phases `post-{add,modify,reboot,start,stop}` |
56 |
by *symlinking* in ``/etc/ganeti/hooks/instance-{add,modify,reboot,start,stop}-post.d`` |
57 |
on GANETI-MASTER, e.g. :: |
58 |
|
59 |
root@ganeti-master:/etc/ganeti/hooks/instance-start-post.d# ls -l |
60 |
lrwxrwxrwx 1 root root 45 May 3 13:45 00-snf-ganeti-hook -> /home/devel/synnefo/snf-ganeti-hook/snf-ganeti-hook.py |
61 |
|
62 |
.. note:: |
63 |
The link name may only contain "upper and lower case, digits, |
64 |
underscores and hyphens. In other words, the regexp ^[a-zA-Z0-9\_-]+$." |
65 |
|
66 |
.. seealso:: |
67 |
`Ganeti customisation using hooks <http://docs.ganeti.org/ganeti/master/html/hooks.html?highlight=hooks#naming>`_ |
68 |
|
69 |
If run from the repository directory, make sure to have `snf-ganeti-tools/` |
70 |
in the ``PYTHONPATH``. |
71 |
|
72 |
Alternative, build Debian packages which take care of building, installing |
73 |
and activating the Ganeti hook automatically, see step. 9. |
74 |
|
75 |
|
76 |
vncauthproxy |
77 |
************ |
78 |
To support OOB console access to the VMs over VNC, the vncauthproxy |
79 |
daemon must be running on every node of type APISERVER. |
80 |
|
81 |
Download and install vncauthproxy from its own repository, |
82 |
at `https://code.grnet.gr/git/vncauthproxy` (known good commit: tag v1.0). |
83 |
|
84 |
Download and install a specific repository commit:: |
85 |
|
86 |
$ bin/pip install -e git+https://code.grnet.gr/git/vncauthproxy@INSERT_COMMIT_HERE#egg=vncauthproxy |
87 |
|
88 |
Create ``/var/log/vncauthproxy`` and set its permissions appropriately. |
89 |
|
90 |
Alternatively, you can build Debian packages. To do so, |
91 |
checkout the "debian" branch of the vncauthproxy repository |
92 |
(known good commit: tag debian/v1.0):: |
93 |
|
94 |
$ git checkout debian |
95 |
|
96 |
Then build debian package, and install as root:: |
97 |
|
98 |
$ dpkg-buildpackage -b -uc -us |
99 |
$ dpkg -i ../vncauthproxy_1.0-1_all.deb |
100 |
|
101 |
.. warning:: |
102 |
**Failure to build the package on the Mac.** |
103 |
|
104 |
``libevent``, a requirement for gevent which in turn is a requirement for |
105 |
vncauthproxy is not included in `MacOSX` by default and installing it with |
106 |
MacPorts does not lead to a version that can be found by the gevent |
107 |
build process. A quick workaround is to execute the following commands:: |
108 |
|
109 |
cd $SYNNEFO |
110 |
sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy |
111 |
<the above fails> |
112 |
cd build/gevent |
113 |
sudo python setup.py -I/opt/local/include -L/opt/local/lib build |
114 |
cd $SYNNEFO |
115 |
sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy |
116 |
|
117 |
|
118 |
.. _nfdhcpd-setup: |
119 |
|
120 |
NFDHCPD installation |
121 |
******************** |
122 |
Setup Synnefo-specific networking on the Ganeti backend. |
123 |
This part is deployment-specific and must be customized based on the |
124 |
specific needs of the system administrators. |
125 |
|
126 |
A reference installation will use a Synnefo-specific KVM ifup script, |
127 |
NFDHCPD and pre-provisioned Linux bridges to support public and private |
128 |
network functionality. For this: |
129 |
|
130 |
Grab NFDHCPD from its own repository (https://code.grnet.gr/git/nfdhcpd), |
131 |
install it, modify /etc/nfdhcpd/nfdhcpd.conf to reflect your network |
132 |
configuration. |
133 |
|
134 |
Install a custom KVM ifup script for use by Ganeti, as |
135 |
``/etc/ganeti/kvm-vif-bridge``, on GANETI-NODEs. A sample implementation is |
136 |
provided under ``/contrib/ganeti-hooks``. Set ``NFDHCPD_STATE_DIR`` to point |
137 |
to NFDHCPD's state directory, usually ``/var/lib/nfdhcpd``. |
138 |
|
139 |
|
140 |
.. _rabbitmq-setup: |
141 |
|
142 |
RabbitMQ installation |
143 |
********************* |
144 |
RabbitMQ is used as a generic message broker for the system. It should be |
145 |
installed on two seperate QUEUE nodes (VMs should be enough for the moment) |
146 |
in a high availability configuration as described here: |
147 |
|
148 |
http://www.rabbitmq.com/pacemaker.html |
149 |
|
150 |
After installation, create a user and set its permissions:: |
151 |
|
152 |
$ rabbitmqctl add_user <username> <password> |
153 |
$ rabbitmqctl set_permissions -p / <username> "^.*" ".*" ".*" |
154 |
|
155 |
The values set for the user and password must be mirrored in the |
156 |
`RABBIT_*` variables in your :ref:`settings <configuration>`. |
157 |
|
158 |
|
159 |
snf-image installation |
160 |
********************** |
161 |
Installation of the `snf-image` `Ganeti OS provider` for image deployment. |
162 |
|
163 |
For Synnefo to be able to launch VMs from specified Images, you need |
164 |
the snf-image OS Provider installed on *all* Ganeti nodes. |
165 |
|
166 |
Please see `https://code.grnet.gr/projects/snf-image/wiki` |
167 |
for installation instructions and documentation on the design |
168 |
and implementation of snf-image. |
169 |
|
170 |
Please see `https://code.grnet.gr/projects/snf-image/files` |
171 |
for the latest packages. |
172 |
|
173 |
Images should be stored under extdump format in a directory |
174 |
of your choice, configurable as ``IMAGE_DIR`` in ``/etc/default/snf-image``. |
175 |
|
176 |
|
177 |
.. _database-setup: |
178 |
|
179 |
Database installation |
180 |
********************* |
181 |
|
182 |
SQLite |
183 |
`````` |
184 |
Most self-respecting systems have the sqlite library installed by default. |
185 |
|
186 |
MySQL |
187 |
````` |
188 |
MySQL must be installed first:: |
189 |
|
190 |
$ sudo apt-get install libmysqlclient-dev |
191 |
|
192 |
if you are using MacPorts:: |
193 |
|
194 |
$ sudo port install mysql5 |
195 |
|
196 |
.. note:: |
197 |
On MacOSX with Mysql install from MacPorts the above command will |
198 |
fail complaining that it cannot find the mysql_config command. Do |
199 |
the following and restart the installation:: |
200 |
|
201 |
$ echo "mysql_config = /opt/local/bin/mysql_config5" >> ./build/MySQL-python/site.cfg |
202 |
|
203 |
Configure a MySQL db/account for synnefo:: |
204 |
|
205 |
$ mysql -u root -p; |
206 |
|
207 |
mysql> create database <database name>; |
208 |
mysql> show databases; |
209 |
mysql> GRANT ALL on <database name>.* TO <db username> IDENTIFIED BY '<db password>'; |
210 |
|
211 |
.. warning:: |
212 |
MySQL *must* be set in READ-COMMITED mode, e.g. by setting:: |
213 |
|
214 |
transaction-isolation = READ-COMMITTED |
215 |
|
216 |
in the [mysqld] section of /etc/mysql/my.cnf. |
217 |
|
218 |
Alternatively, make sure the following code fragment stays enabled |
219 |
in /etc/synnefo/10-database.conf file: |
220 |
|
221 |
.. code-block:: python |
222 |
|
223 |
if DATABASES['default']['ENGINE'].endswith('mysql'): |
224 |
DATABASES['default']['OPTIONS'] = { |
225 |
'init_command': 'SET storage_engine=INNODB; ' + |
226 |
'SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED', |
227 |
} |
228 |
|
229 |
PostgreSQL |
230 |
`````````` |
231 |
You need to install the PostgreSQL binaries:: |
232 |
|
233 |
$ sudo apt-get install postgresql-8.4 libpq-dev |
234 |
|
235 |
or ir you are using MacPorts:: |
236 |
|
237 |
$ sudo port install postgresql84 |
238 |
|
239 |
To configure a postgres db/account for synnefo, |
240 |
|
241 |
* Become the postgres user, connect to PostgreSQL:: |
242 |
|
243 |
$ sudo su - postgres |
244 |
$ psql |
245 |
|
246 |
* Run the following commands:: |
247 |
|
248 |
DROP DATABASE <database name>; |
249 |
DROP USER <db username>; |
250 |
CREATE USER <db username> WITH PASSWORD '<db password>'; |
251 |
CREATE DATABASE <database name>; |
252 |
GRANT ALL PRIVILEGES ON DATABASE <database name> TO <db username>; |
253 |
ALTER DATABASE <database name> OWNER TO <db username>; |
254 |
ALTER USER <db username> CREATEDB; |
255 |
|
256 |
.. note:: |
257 |
The last line enables the newly created user to create own databases. This |
258 |
is needed for Django to create and drop the test_synnefo database for unit |
259 |
testing. |
260 |
|
261 |
|
262 |
|
263 |
Installing depedencies |
264 |
********************** |
265 |
|
266 |
Synnefo is written in Python 2.6 requires the some additional python packages |
267 |
to run properly. |
268 |
|
269 |
The easiest method for installation of the Django project is to setup a |
270 |
working environment through virtualenv. Alternatively, you can use your |
271 |
system's package manager to install the dependencies (e.g. Macports has them |
272 |
all). |
273 |
|
274 |
You can install these packages either using `pip` python package manager:: |
275 |
|
276 |
$ pip install <pypi-package-name>==<version> |
277 |
|
278 |
or using the requirements.pip file that exists in Synnefo package repository:: |
279 |
|
280 |
$ pip install -r requirements.pip |
281 |
|
282 |
or Debian's `apt-get`:: |
283 |
|
284 |
$ apt-get install <debian-package-name> |
285 |
|
286 |
|
287 |
Required packages |
288 |
````````````````` |
289 |
|
290 |
.. todo:: |
291 |
Confirm debian package names |
292 |
|
293 |
======================= =================== ========== |
294 |
PyPi package name Debian package name version |
295 |
======================= =================== ========== |
296 |
django python-django 1.2.4 |
297 |
simplejson python-simplejson 2.1.3 |
298 |
pycurl python-pycurl 7.19.0 |
299 |
python-dateutil python-dateutil 1.4.1 |
300 |
IPy python-ipy 0.75 |
301 |
south python-django-south 0.7.1 |
302 |
amqplib python-amqplib 0.6.1 |
303 |
lockfile python-lockfile 0.8 |
304 |
python-daemon python-daemon 1.5.5 |
305 |
python-prctl python-prctl 1.3.0 |
306 |
======================= =================== ========== |
307 |
|
308 |
.. note:: |
309 |
On Snow Leopard and linux (64-bit), you have to set the following |
310 |
environment variable for pip to compile the dependencies correctly:: |
311 |
|
312 |
$ export ARCHFLAGS="-arch x86_64" |
313 |
|
314 |
.. note:: |
315 |
On Ubuntu/Debian, a few more packages must be installed before installing the |
316 |
prerequisite Python libraries:: |
317 |
|
318 |
$ sudo aptitude install libcurl3-gnutls libcurl3-gnutls-dev uuid-dev |
319 |
|
320 |
.. note:: |
321 |
Depending on the permissions of your system’s Python, you might need to be the |
322 |
root user to install those packages system-wide |
323 |
|
324 |
|
325 |
Database driver |
326 |
``````````````` |
327 |
|
328 |
Depending on the database software you choose to use one of the following: |
329 |
|
330 |
========= ======================= =================== ========== |
331 |
Database PyPi package name Debian package name version |
332 |
========= ======================= =================== ========== |
333 |
mysql MySQL-python python-mysql 1.2.3 |
334 |
postgres psycopg2 python-psycopg2 2.4 |
335 |
========= ======================= =================== ========== |
336 |
|
337 |
.. note:: |
338 |
The python sqlite driver is available by default with Python so no |
339 |
additional configuration is required. Also, most self-respecting systems |
340 |
have the sqlite library installed by default. |
341 |
|
342 |
|
343 |
Extra depedencies |
344 |
````````````````` |
345 |
|
346 |
Synnefo provides some optional features that require specific python packages to |
347 |
be installed. |
348 |
|
349 |
**Invitations and SSH Keys generation** |
350 |
|
351 |
======================= =================== ========== |
352 |
PyPi package name Debian package name version |
353 |
======================= =================== ========== |
354 |
pycrypto python-crypto 2.1.0 |
355 |
======================= =================== ========== |
356 |
|
357 |
|
358 |
|
359 |
Installing Synnefo package |
360 |
-------------------------- |
361 |
|
362 |
Using ``pip``:: |
363 |
|
364 |
$ pip install https://code.grnet.gr/projects/synnefo/synnefo-<version>.tar.gz --no-deps |
365 |
|
366 |
by checking out git repository:: |
367 |
|
368 |
$ git clone https://code.grnet.gr/git/synnefo synnefo-repo |
369 |
$ cd synnefo-repo |
370 |
$ python setup.py install |
371 |
|
372 |
this should be enough for synnefo to get installed in your system-wide or |
373 |
``virtualenv`` python installation and the following commands should be |
374 |
available from the command line:: |
375 |
|
376 |
$ snf-manage |
377 |
$ snf-dispatcher |
378 |
$ snf-admin |
379 |
|
380 |
Notice that Synnefo installation does not handle the creation of |
381 |
``/etc/synnefo/`` directory which is the place where custom configuration |
382 |
files are loaded from. You are encouraged to create this directory and place a |
383 |
file named ``settings.conf`` with the following contents: |
384 |
|
385 |
.. _sample-settings: |
386 |
.. literalinclude:: ../_static/sample_settings.conf |
387 |
:language: python |
388 |
|
389 |
`download <../_static/sample_settings.conf>`_ |
390 |
|
391 |
this is just to get you started on how to configure your Synnefo installation. |
392 |
From this point you can continue your read to the `Initial configuration`_ section |
393 |
in this document which contains quickstart instructions for some of the initial |
394 |
configuration required for Synnefo to get up and running. |
395 |
|
396 |
For additional instructions about Synnefo settings files and what the available |
397 |
settings are, you can refer to the :ref:`configuration <configuration>` guide. |
398 |
|
399 |
|
400 |
Initial configuration |
401 |
--------------------- |
402 |
|
403 |
Synnefo comes with most of the required settings predefined with values that |
404 |
would cover many of the most common installation scenarios. However some basic |
405 |
settings must be set be set before running Synnefo for the first time. |
406 |
|
407 |
:ref:`sample settings file <sample-settings>` |
408 |
|
409 |
|
410 |
Database |
411 |
******** |
412 |
|
413 |
Change ``DATABASES`` setting based on your :ref:`database setup <database-setup>` |
414 |
and :ref:`initialize/update your database structure <database-initialization>` |
415 |
|
416 |
.. seealso:: |
417 |
:ref:`database-configuration` / |
418 |
:ref:`database-initialization` |
419 |
|
420 |
|
421 |
Queue |
422 |
***** |
423 |
|
424 |
Change ``RABBIT_*`` settings to match your :ref:`RabbitMQ setup <rabbitmq-setup>`. |
425 |
|
426 |
|
427 |
Backend |
428 |
******* |
429 |
|
430 |
Set ``GANETI_NODES``, ``GANETI_MASTER_IP``, ``GANETI_CLUSTER_INFO`` based on your :ref:`Ganeti |
431 |
installation <ganeti-setup>` and change BACKEND_PREFIX_ID using an custom `prefix |
432 |
id`. |
433 |
|
434 |
|
435 |
Web application |
436 |
*************** |
437 |
|
438 |
See the extended :ref:`deployment guide <webapp-deploy>` for instructions on how to |
439 |
setup the Synnefo web application. |