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