INSTALL.txt 10.4 KB
Newer Older
1
.. -*- mode: rst; fill-column: 78; -*-
2 3 4 5 6 7
.. This document is formatted using the ReST syntax.

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

8 9 10 11
------------------------------------------------------------------------------
This document describes briefly how to install a multi-platform, single-server
Aegir Drupal provisionning system.
------------------------------------------------------------------------------
12

13 14
Aegir installation seems difficult at first, but once you get around it, it's
fairly simple. It's 4 basic steps:
15 16 17 18 19 20 21 22

 1. Install requirements
 2. Configure system requirements, which include:
    * create a Aegir user
    * configure Apache, MySQL, DNS, etc
 3. Install the Aegir files
 4. Follow the install wizard

23 24 25 26 27 28
Those steps are detailed below. The following instructions provide example
commands for a Debian-like distribution, but should be fairly easy to adapt to
your environment. In fact, this document is meant as a canonical reference
that should work on every platform and that can be used for people porting
Aegir to new platforms or installing on alien platform for which Aegir is not
yet packaged.
29 30

Platform-specific cheat sheets are also available for other platforms in
31
HINTS_*.txt files alongside this document. Those files are basically a
32 33 34
bullet-point summary of the steps required for the installation. In case of
conflict between INSTALL.txt and other documentation, INSTALL.txt should be
considered the canonical source of information.
35

36 37
Also note that those instructions setup a complete Aegir system. If you want
to only setup a new server, it should be sufficient to install requirement
38 39
(step 1) and configure them (step 2). You will just need the -b flag to
avoid installing the frontend on the server.
40 41 42 43

1. Install software requirements
================================

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

46 47 48 49
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.
50

51 52 53
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.  Commands are
assumed to be run as root user.
54 55 56 57

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

58 59 60 61 62
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.
63 64 65 66

PHP 5.2
-------

67 68 69
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.
70 71 72 73

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

74 75 76
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.
77 78 79 80

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

81 82 83 84 85 86
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.
87 88 89 90 91 92

Other utilities: sudo, git and unzip
------------------------------

Aegir installs itself via a drush_make file that downloads via git if you want
the bleeding edge code, or via wget if you want the latest official release.
93
If you want the latest development version, and don't have the git program you
94
will need to install it on the server.
95

96
The jQueryUI library is used in the Aegir UI, unzip is required to extract it.
97 98
Sudo is required to allow the aegir user the limited privilege to restart the
webserver when required.
99 100 101 102

Summary
-------

103 104
This may vary according to your platform, but under a Debian derivative, you
can install all those packages using the following.
105 106 107 108 109 110 111 112 113 114

Shell commands::

 apt-get install apache2 php5 php5-cli php5-mysql mysql-server postfix
 apt-get install sudo git-core unzip


2. Configure system requirements
================================

115 116
The following details what configuration needs to be performed on the server
before going ahead with the install.
117 118 119 120

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

121 122 123
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.
124

125 126 127 128 129
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.
130

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

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

138 139
In addition we will create a directory layout for Aegir configuration and
backups.
140 141 142 143 144 145 146 147 148 149

Shell commands::

 adduser --system --group --home /var/aegir aegir
 adduser aegir www-data    #make aegir a user of group www-data


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

150 151 152 153 154 155 156 157
Aegir assumes a few Apache modules are available on the server, and
generates its own configuration files. The way we enable this is by
symlinking a single file which contains all the configuration necessary.
In Debian-based systems, you should symlink this file inside
``/etc/apache2/conf.d`` that will be parsed on startup or alternatively
you can place include that file in your 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.
158 159 160

Shell commands as root::

161
 ln -s /var/aegir/config/apache.conf /etc/apache2/conf.d/aegir.conf
162 163 164 165 166


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

167 168 169
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, substituting the 'XXXXXXXX' with a real password.
170 171 172 173 174 175 176 177 178 179 180 181 182 183

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. 

184 185 186
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:
187 188 189 190 191 192 193 194 195 196

``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``

3. Install the Aegir files
==========================

197 198 199
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.
200

201 202 203 204
There is an install script part of the hostmaster profile that takes care of
installing the right packages and preparing the Drupal frontend install for
you. That script needs to be run as the aegir user created above.  This file
is available alongside this one or can be downloaded through the web at:
205

206
http://git.aegirproject.org/?p=provision.git;a=blob_plain;f=install.sh.txt;hb=HEAD
207

208 209 210 211 212
By default, the install script will install the "correct" version of Aegir
(ie. if it was downloaded through git, it will install the version from the
git master branch. If you downloaded an official release, it should install
the official release.). You can modify which version to install by editing the
AEGIR_VERSION variable in the script.
213

214 215
The install script is shipped with other default settings that you will likely
need to change (such as the URL of the Aegir site) prior to running it.
216 217

You can change which release to install or other parameters such as these
218 219
through options passed to the script. Run "sh install.sh.txt -h" for more
information on the available options.
220 221 222 223 224 225 226 227 228 229 230

Shell commands::

 su -s /bin/sh aegir -c "sh install.sh.txt"
 /etc/init.d/apache2 restart

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

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

231 232 233 234
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::
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250

 /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/

251 252 253
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
the defaults if you really want to get through this.
254 255 256 257 258


4. Follow the install wizard
============================

259 260 261 262 263 264 265 266
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 the webserver, 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.