profiles/hostmaster/INSTALL.txt

.. This document is formatted using the ReST syntax.

=================================
 Aegir Installation Instructions
=================================

------------------------------------------------------------------------------------------------------------------
 This document describes briefly how to install a multi-platform, single-server Aegir Drupal provisionning system.
------------------------------------------------------------------------------------------------------------------


Aegir requirements
==================

This section describes what is expected of the servers Aegir is running
on.

Aegir must run some UNIX flavour because the majority of functionality
in this system occurs in the back-end, through command line scripting.
There are also several features (such as symlinks), that are not
available to users on Windows. There are no plans currently to add
windows support.

The level of access required to be able to configure this system is
very far beyond what is commonly available to users with shared hosting.

Following instructions will provide example commands for a Debian-like
distribution. They are assumed to be run as root user. Prefix them with
sudo if you are working with a privileged user instead of root.


Web server
----------

You will need at least one dedicated web server, running Apache. We
generally work with Apache 2 but we should be compatible with the 1.x
series. You will need root access to that server and the server must
be reserved for Aegir. Sharing the server with other control panels
such as Cpanel, Plesk or AlternC will very likely create problems and
is not supported.

Shell commands::

 apt-get install apache2


PHP 5.2
-------

Since Aegir strongly depends on Drush, we therefore depend on PHP 5.2
or above. You also need to have the commandline version of PHP to run
Drush properly and the MySQL extensions.

Shell commands::

 apt-get install php5 php5-cli php5-mysql


Database server
---------------

You will require a database server, obviously. Aegir currently only 
supports MySQL. It is preferable to use a dedicated server since Aegir 
will create database users and will require a privileged user.

Shell commands::

 apt-get install mysql-server


Mail transfer agent
-------------------

Aegir requires an MTA (Mail Transfer Agent) installed on your webserver
in order to be able to install new sites to your new platform. If you
don't have an MTA, the site installation will fail with message like
"could not send email". Additional messages will show that site has been
removed because of this problem. To remedy the situation simply install
an MTA like sendmail, postfix, or exim and do the minimal configuration.

Shell commands::

 apt-get install postfix


CVS commands
------------

Aegir installs itself via a drush_make file that downloads via CVS (by using given tags).
If you don't have the cvs program you will need to install it on the server.

Shell commands::

 apt-get install cvs


Unzip
-----

The jQueryUI library is used in the Aegir UI, unzip is required to extract it.

Shell commands::

 apt-get install unzip


Aegir user
----------

The provision framework of Aegir requires that the scripts run as a 
non-root system account, to ensure that it can correctly set the file
permissions on the hosted files. 

Also to ensure that the file permissions of the hosted sites are
always as safe as can be, and especially to make sure that the web
server does not have the ability to modify the code of the site, the
configured system account needs to be a member of the web server group,
in order to be able to correctly set the file permissions.

More detailed instructions on this topic will be given later in the web 
installation wizard.

This document assumes the Aegir user is ``aegir``, its home directory is
``/var/aegir`` and the webserver group is ``www-data``. You can choose
another username if desired.

In addition we will create a directory layout for Aegir configuration
and backups.

Shell commands::

 adduser --system --group --home /var/aegir aegir
 adduser aegir www-data    #make aegir a user of group www-data
 mkdir -p /var/aegir/config/vhost.d
 mkdir -p /var/aegir/backups
 chmod 0711 /var/aegir/config
 chmod 0700 /var/aegir/backups
 chown -R aegir /var/aegir


Aegir installation instructions
===============================

This section deals with the installation of Aegir proper. These
instructions limit themselves to getting you into the Aegir install wizard,
which will then give you further configuration instructions.

All instructions and in general all commands must be run as aegir user,
so all permissions are always set correctly.

To become aegir user you can issue this command::

  su -s /bin/sh aegir

(Note you must run this as root or prefix with sudo).

Note that /bin/sh is an example. You may wish to instead use the shell
of your choice, i.e /bin/bash

Additionally to make following instructions generic and not dependant on
a concrete Drupal or Aegir version, we will use shell environment
variables. The current Aegir release is 0.4-alpha2.

You should replace the following command for the most current versions 
at the time you are reading this document.

Shell commands::

  export AEGIR_TAG=DRUPAL-6--0-4-ALPHA2
  export HOSTMASTER_DIR=hostmaster-0.4-alpha2


Installing drush 2.1
--------------------

At the time of writing, the current drush stable version is 2.1.
In the event a newer version exists and this document has not been
updated, you should use the latest stable version of the 2.x branch.

Shell commands::

 cd /var/aegir
 wget http://ftp.drupal.org/files/projects/drush-All-Versions-2.1.tar.gz
 tar -xvzf drush-All-Versions-2.1.tar.gz
 rm drush-All-Versions-2.1.tar.gz
 mkdir .drush

Drush is now downloaded to /var/aegir/drush. It is not in the system
path, so we must explicitly call it by using the complete path. 
We have also created the /var/aegir/.drush folder to put inside drush
commands that will only be available to Aegir's user. Please refer to 
the Drush documentation if needed, which will teach you more about 
these and other configuration instructions.


Installing drush_make
---------------------

Aegir uses makefiles to work with drush_make and automate the
installation of components. This drastically reduces the amount of manual 
downloads to perform, and also makes some Aegir components detect and install
compatible versions of other components.

Shell commands::

 php drush/drush.php dl drush_make --destination=.drush


Downloading provision framework
-------------------------------

The provision framework is not a drupal module but a drush extension, 
and it *must* always be run as Aegir's user to avoid further permission
problems. So we will place it in ``/var/aegir/.drush`` to ensure that.

Shell commands::

 export CVSROOT=:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
 cvs co -d .drush/provision -r$AEGIR_TAG contributions/modules/provision


Downloading the front end components
------------------------------------

As stated above, Aegir now uses makefiles to download the components.

Provision framework ships with aegir.make, which is responsible for
downloading Drupal core and the Hostmaster profile.

Hostmaster profile also ships with another makefile, hostmaster.make,
which will download required and optional components for Aegir.

Shell commands::

 php drush/drush.php hostmaster make $HOSTMASTER_DIR


Prepare the Hostmaster drupal site
----------------------------------

We are almost ready to install the Hostmaster drupal site using the installation
profile. 

It is recommended that you create the aegir site as a real site in the
sites/ directory instead of using sites/default. The following commands will
create this site directory and create the settings.php and files directory with
the appropriate permissions to proceed through the installer later.

These instructions assume you are installing Aegir in ``$AEGIR_DOMAIN``,
where ``AEGIR_DOMAIN = aegir.example.com``.

Shell commands::

 export AEGIR_DOMAIN=aegir.example.com 
 cd $HOSTMASTER_DIR
 mkdir sites/$AEGIR_DOMAIN
 cp sites/default/default.settings.php sites/$AEGIR_DOMAIN/settings.php
 chmod g+w sites/$AEGIR_DOMAIN/settings.php
 mkdir sites/$AEGIR_DOMAIN/files
 chmod 2770 sites/$AEGIR_DOMAIN/files
 chgrp www-data sites/$AEGIR_DOMAIN/settings.php
 chgrp www-data sites/$AEGIR_DOMAIN/files


Apache configuration
--------------------

Aegir VirtualHosts for Apache are stored in ``/var/aegir/config/vhost.d``
(if you have not changed default locations). 

Hostmaster provides an example virtualhost for apache. Copy it to Aegir's
virtual hosts directory and **modify** it to suit your needs,
particularly the path leading to the Drupal core ($HOSTMASTER_DIR in the
examples above).

Shell commands::

 cp profiles/hostmaster/apache2.conf.txt ../config/vhost.d/$AEGIR_DOMAIN
 # edit and configure


In addition, Rewrite module must be enabled and also Apache must be given a
directive to include Aegir's vhosts path, to read configurations from there. 
In Debian-based systems you can put a file inside ``/etc/apache2/conf.d`` that
will be parsed on startup or alternatively you can place the directive in
apache.conf / httpd.conf. We prefer the former. In other systems there are
similar ways to accomplish this. Consult your OS's documentation if unsure.

Shell commands as root::

 a2enmod rewrite
 echo "Include /var/aegir/config/vhost.d/" > /etc/apache2/conf.d/aegir
 /etc/init.d/apache2 restart


Database configuration
----------------------

Here you want to make a basic database configuration for the Drupal site
you are going to install. You want to run these commands using your
mysql 'root' user.

SQL commands::

 CREATE DATABASE aegir;
 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, \
  CREATE TEMPORARY TABLES, LOCK TABLES ON aegir.* TO \
  'aegir'@'localhost' IDENTIFIED BY 'XXXXXXXX';


DNS Configuration
-----------------

Configuring DNS is up to you. Currently Aegir does nothing with DNS. 

As a help trick, if you are installing Aegir locally to try and test it,
you can do local DNS by adding entries to file ``/etc/hosts``. First
line of this file looks like:

``127.0.0.1  localhost your-machine-name``

Simply add all domains you want to this line. e.g:

``127.0.0.1  localhost your-machine-name $AEGIR_DOMAIN other1 other2``


Checkpoint!
-----------

At this point, you have checked out all the code and setup your basic
Drupal system (Drupal core, hosting, hostmaster and eldir) that will be the
Aegir frontend and the backend system (provision and drush). Your
filesystem layout should look something like this::

 /var/aegir/hostmaster-0.x/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/admin_menu/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/hosting/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/install_profile_api/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/jquery_ui/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/modalframe/
 /var/aegir/hostmaster-0.x/profiles/hostmaster/themes/eldir/
 /var/aegir/hostmaster-0.x/sites/aegir.example.com/
 /var/aegir/config/vhost.d/
 /var/aegir/backups/
 /var/aegir/drush/drush.php
 /var/aegir/.drush/drush_make/
 /var/aegir/.drush/provision/

Variations on this are acceptable (for example, the Drush Debian
package works out of ``/usr/bin/drush`` and that's fine), but you are
better to stick with those if you really want to get through this. The
remaining of the documentation here will assume that layout.


Follow the wizard
-----------------

Now point your browser to http://$AEGIR_DOMAIN/install.php and proceed
with the remainder of the installation using the Hostmaster Install profile.
Some of the instructions given, you will already have completed, but carefully
read each step in turn to ensure you don't miss anything.
Specifically you must still provide the database credentials, add the Aegir user
to /etc/sudoers with the relevant command to restart Apache, create a MySQL
superuser capable of creating more databases, and initialise the hosting system.
These instructions are provided to you by the Hostmaster install profile.

1	.. This document is formatted using the ReST syntax.
2
3	=================================
4	Aegir Installation Instructions
5	=================================
6
7	------------------------------------------------------------------------------------------------------------------
8	This document describes briefly how to install a multi-platform, single-server Aegir Drupal provisionning system.
9	------------------------------------------------------------------------------------------------------------------
10
11
12	Aegir requirements
13	==================
14
15	This section describes what is expected of the servers Aegir is running
16	on.
17
18	Aegir must run some UNIX flavour because the majority of functionality
19	in this system occurs in the back-end, through command line scripting.
20	There are also several features (such as symlinks), that are not
21	available to users on Windows. There are no plans currently to add
22	windows support.
23
24	The level of access required to be able to configure this system is
25	very far beyond what is commonly available to users with shared hosting.
26
27	Following instructions will provide example commands for a Debian-like
28	distribution. They are assumed to be run as root user. Prefix them with
29	sudo if you are working with a privileged user instead of root.
30
31
32	Web server
33	----------
34
35	You will need at least one dedicated web server, running Apache. We
36	generally work with Apache 2 but we should be compatible with the 1.x
37	series. You will need root access to that server and the server must
38	be reserved for Aegir. Sharing the server with other control panels
39	such as Cpanel, Plesk or AlternC will very likely create problems and
40	is not supported.
41
42	Shell commands::
43
44	apt-get install apache2
45
46
47	PHP 5.2
48	-------
49
50	Since Aegir strongly depends on Drush, we therefore depend on PHP 5.2
51	or above. You also need to have the commandline version of PHP to run
52	Drush properly and the MySQL extensions.
53
54	Shell commands::
55
56	apt-get install php5 php5-cli php5-mysql
57
58
59	Database server
60	---------------
61
62	You will require a database server, obviously. Aegir currently only
63	supports MySQL. It is preferable to use a dedicated server since Aegir
64	will create database users and will require a privileged user.
65
66	Shell commands::
67
68	apt-get install mysql-server
69
70
71	Mail transfer agent
72	-------------------
73
74	Aegir requires an MTA (Mail Transfer Agent) installed on your webserver
75	in order to be able to install new sites to your new platform. If you
76	don't have an MTA, the site installation will fail with message like
77	"could not send email". Additional messages will show that site has been
78	removed because of this problem. To remedy the situation simply install
79	an MTA like sendmail, postfix, or exim and do the minimal configuration.
80
81	Shell commands::
82
83	apt-get install postfix
84
85
86	CVS commands
87	------------
88
89	Aegir installs itself via a drush_make file that downloads via CVS (by using given tags).
90	If you don't have the cvs program you will need to install it on the server.
91
92	Shell commands::
93
94	apt-get install cvs
95
96
97	Unzip
98	-----
99
100	The jQueryUI library is used in the Aegir UI, unzip is required to extract it.
101
102	Shell commands::
103
104	apt-get install unzip
105
106
107	Aegir user
108	----------
109
110	The provision framework of Aegir requires that the scripts run as a
111	non-root system account, to ensure that it can correctly set the file
112	permissions on the hosted files.
113
114	Also to ensure that the file permissions of the hosted sites are
115	always as safe as can be, and especially to make sure that the web
116	server does not have the ability to modify the code of the site, the
117	configured system account needs to be a member of the web server group,
118	in order to be able to correctly set the file permissions.
119
120	More detailed instructions on this topic will be given later in the web
121	installation wizard.
122
123	This document assumes the Aegir user is ``aegir``, its home directory is
124	``/var/aegir`` and the webserver group is ``www-data``. You can choose
125	another username if desired.
126
127	In addition we will create a directory layout for Aegir configuration
128	and backups.
129
130	Shell commands::
131
132	adduser --system --group --home /var/aegir aegir
133	adduser aegir www-data #make aegir a user of group www-data
134	mkdir -p /var/aegir/config/vhost.d
135	mkdir -p /var/aegir/backups
136	chmod 0711 /var/aegir/config
137	chmod 0700 /var/aegir/backups
138	chown -R aegir /var/aegir
139
140
141	Aegir installation instructions
142	===============================
143
144	This section deals with the installation of Aegir proper. These
145	instructions limit themselves to getting you into the Aegir install wizard,
146	which will then give you further configuration instructions.
147
148	All instructions and in general all commands must be run as aegir user,
149	so all permissions are always set correctly.
150
151	To become aegir user you can issue this command::
152
153	su -s /bin/sh aegir
154
155	(Note you must run this as root or prefix with sudo).
156
157	Note that /bin/sh is an example. You may wish to instead use the shell
158	of your choice, i.e /bin/bash
159
160	Additionally to make following instructions generic and not dependant on
161	a concrete Drupal or Aegir version, we will use shell environment
162	variables. The current Aegir release is 0.4-alpha2.
163
164	You should replace the following command for the most current versions
165	at the time you are reading this document.
166
167	Shell commands::
168
169	export AEGIR_TAG=DRUPAL-6--0-4-ALPHA2
170	export HOSTMASTER_DIR=hostmaster-0.4-alpha2
171
172
173	Installing drush 2.1
174	--------------------
175
176	At the time of writing, the current drush stable version is 2.1.
177	In the event a newer version exists and this document has not been
178	updated, you should use the latest stable version of the 2.x branch.
179
180	Shell commands::
181
182	cd /var/aegir
183	wget http://ftp.drupal.org/files/projects/drush-All-Versions-2.1.tar.gz
184	tar -xvzf drush-All-Versions-2.1.tar.gz
185	rm drush-All-Versions-2.1.tar.gz
186	mkdir .drush
187
188	Drush is now downloaded to /var/aegir/drush. It is not in the system
189	path, so we must explicitly call it by using the complete path.
190	We have also created the /var/aegir/.drush folder to put inside drush
191	commands that will only be available to Aegir's user. Please refer to
192	the Drush documentation if needed, which will teach you more about
193	these and other configuration instructions.
194
195
196	Installing drush_make
197	---------------------
198
199	Aegir uses makefiles to work with drush_make and automate the
200	installation of components. This drastically reduces the amount of manual
201	downloads to perform, and also makes some Aegir components detect and install
202	compatible versions of other components.
203
204	Shell commands::
205
206	php drush/drush.php dl drush_make --destination=.drush
207
208
209	Downloading provision framework
210	-------------------------------
211
212	The provision framework is not a drupal module but a drush extension,
213	and it must always be run as Aegir's user to avoid further permission
214	problems. So we will place it in ``/var/aegir/.drush`` to ensure that.
215
216	Shell commands::
217
218	export CVSROOT=:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal
219	cvs co -d .drush/provision -r$AEGIR_TAG contributions/modules/provision
220
221
222	Downloading the front end components
223	------------------------------------
224
225	As stated above, Aegir now uses makefiles to download the components.
226
227	Provision framework ships with aegir.make, which is responsible for
228	downloading Drupal core and the Hostmaster profile.
229
230	Hostmaster profile also ships with another makefile, hostmaster.make,
231	which will download required and optional components for Aegir.
232
233	Shell commands::
234
235	php drush/drush.php hostmaster make $HOSTMASTER_DIR
236
237
238	Prepare the Hostmaster drupal site
239	----------------------------------
240
241	We are almost ready to install the Hostmaster drupal site using the installation
242	profile.
243
244	It is recommended that you create the aegir site as a real site in the
245	sites/ directory instead of using sites/default. The following commands will
246	create this site directory and create the settings.php and files directory with
247	the appropriate permissions to proceed through the installer later.
248
249	These instructions assume you are installing Aegir in ``$AEGIR_DOMAIN``,
250	where ``AEGIR_DOMAIN = aegir.example.com``.
251
252	Shell commands::
253
254	export AEGIR_DOMAIN=aegir.example.com
255	cd $HOSTMASTER_DIR
256	mkdir sites/$AEGIR_DOMAIN
257	cp sites/default/default.settings.php sites/$AEGIR_DOMAIN/settings.php
258	chmod g+w sites/$AEGIR_DOMAIN/settings.php
259	mkdir sites/$AEGIR_DOMAIN/files
260	chmod 2770 sites/$AEGIR_DOMAIN/files
261	chgrp www-data sites/$AEGIR_DOMAIN/settings.php
262	chgrp www-data sites/$AEGIR_DOMAIN/files
263
264
265	Apache configuration
266	--------------------
267
268	Aegir VirtualHosts for Apache are stored in ``/var/aegir/config/vhost.d``
269	(if you have not changed default locations).
270
271	Hostmaster provides an example virtualhost for apache. Copy it to Aegir's
272	virtual hosts directory and modify it to suit your needs,
273	particularly the path leading to the Drupal core ($HOSTMASTER_DIR in the
274	examples above).
275
276	Shell commands::
277
278	cp profiles/hostmaster/apache2.conf.txt ../config/vhost.d/$AEGIR_DOMAIN
279	# edit and configure
280
281
282	In addition, Rewrite module must be enabled and also Apache must be given a
283	directive to include Aegir's vhosts path, to read configurations from there.
284	In Debian-based systems you can put a file inside ``/etc/apache2/conf.d`` that
285	will be parsed on startup or alternatively you can place the directive in
286	apache.conf / httpd.conf. We prefer the former. In other systems there are
287	similar ways to accomplish this. Consult your OS's documentation if unsure.
288
289	Shell commands as root::
290
291	a2enmod rewrite
292	echo "Include /var/aegir/config/vhost.d/" > /etc/apache2/conf.d/aegir
293	/etc/init.d/apache2 restart
294
295
296	Database configuration
297	----------------------
298
299	Here you want to make a basic database configuration for the Drupal site
300	you are going to install. You want to run these commands using your
301	mysql 'root' user.
302
303	SQL commands::
304
305	CREATE DATABASE aegir;
306	GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, \
307	CREATE TEMPORARY TABLES, LOCK TABLES ON aegir.* TO \
308	'aegir'@'localhost' IDENTIFIED BY 'XXXXXXXX';
309
310
311	DNS Configuration
312	-----------------
313
314	Configuring DNS is up to you. Currently Aegir does nothing with DNS.
315
316	As a help trick, if you are installing Aegir locally to try and test it,
317	you can do local DNS by adding entries to file ``/etc/hosts``. First
318	line of this file looks like:
319
320	``127.0.0.1 localhost your-machine-name``
321
322	Simply add all domains you want to this line. e.g:
323
324	``127.0.0.1 localhost your-machine-name $AEGIR_DOMAIN other1 other2``
325
326
327	Checkpoint!
328	-----------
329
330	At this point, you have checked out all the code and setup your basic
331	Drupal system (Drupal core, hosting, hostmaster and eldir) that will be the
332	Aegir frontend and the backend system (provision and drush). Your
333	filesystem layout should look something like this::
334
335	/var/aegir/hostmaster-0.x/
336	/var/aegir/hostmaster-0.x/profiles/hostmaster/
337	/var/aegir/hostmaster-0.x/profiles/hostmaster/modules/admin_menu/
338	/var/aegir/hostmaster-0.x/profiles/hostmaster/modules/hosting/
339	/var/aegir/hostmaster-0.x/profiles/hostmaster/modules/install_profile_api/
340	/var/aegir/hostmaster-0.x/profiles/hostmaster/modules/jquery_ui/
341	/var/aegir/hostmaster-0.x/profiles/hostmaster/modules/modalframe/
342	/var/aegir/hostmaster-0.x/profiles/hostmaster/themes/eldir/
343	/var/aegir/hostmaster-0.x/sites/aegir.example.com/
344	/var/aegir/config/vhost.d/
345	/var/aegir/backups/
346	/var/aegir/drush/drush.php
347	/var/aegir/.drush/drush_make/
348	/var/aegir/.drush/provision/
349
350	Variations on this are acceptable (for example, the Drush Debian
351	package works out of ``/usr/bin/drush`` and that's fine), but you are
352	better to stick with those if you really want to get through this. The
353	remaining of the documentation here will assume that layout.
354
355
356	Follow the wizard
357	-----------------
358
359	Now point your browser to http://$AEGIR_DOMAIN/install.php and proceed
360	with the remainder of the installation using the Hostmaster Install profile.
361	Some of the instructions given, you will already have completed, but carefully
362	read each step in turn to ensure you don't miss anything.
363	Specifically you must still provide the database credentials, add the Aegir user
364	to /etc/sudoers with the relevant command to restart Apache, create a MySQL
365	superuser capable of creating more databases, and initialise the hosting system.
366	These instructions are provided to you by the Hostmaster install profile.
367