7. The installer will prompt you for your MySQL root user password. The root
user will be used to make administrative tasks such as creating new databases,
and granting and revoking access to those databases for sites.
C'est parti !
Even though MySQL is now listening on all IP's, it will not allow invalid users
to connect to the databases, without the correct user accounts configured.
If you are concerned about MySQL being accessible in this way, you can also
configure your firewall to only allow incoming connections from certain addresses.
This is outside the scope of this document however.
3. Run the install script
=========================
This section deals with the actual installation of Aegir. You can
install aegir in one of two ways: one assumes you have already
downloaded drush and provision, while the other will do that for you.
3.1 Installing aegir with only the install.sh script
----------------------------------------------------
.. -*- mode: rst; fill-column: 78; -*-
There is an install script that takes care of installing the right packages and
.. This document is formatted using the ReST syntax.
preparing the backend and frontend install for you. That script needs to be run
2. Configure system requirements as the aegir user created above, so it needs to be placed somewhere that the
================================= ================================ aegir user can access in order to execute it. This file is available in
Aegir Installation Instructions
Provision or can be downloaded through the web with this command::
================================= The following details what configuration needs to be performed on the server
before going ahead with the install. Shell commands::
------------------------------------------------------------------------------ wget -O install.sh 'http://git.aegirproject.org/?p=provision.git;a=blob_plain;f=install.sh.txt;hb=provision-0.4-beta2'
This document describes briefly how to install a multi-platform, single-server
Aegir Drupal provisionning system. DNS Configuration 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
Aegir installation seems difficult at first, but once you get around it, it's Aegir requires that the hostname returned by the `hostname` and `uname -n` the official release.). You can modify which version to install by editing the
fairly simple. It's 3 basic steps:: shell commands, resolves to the IP address for this server. AEGIR_VERSION variable in the script.
1. Install requirements Shell commands as root:: Shell commands::
2. Configure system requirements, which include:: AEGIR_HOST=`uname -n` su -s /bin/sh aegir -c "sh install.sh"
* create a Aegir user resolveip $AEGIR_HOST
* configure Apache, MySQL, DNS, etc Note you must run the above command as root or prefix with sudo.
3. Run the install script. If the command returns your IP address, you are all set. If it returns
an error you will need to edit your ``/etc/hosts`` file. You will be prompted for the information necessary to complete the
Those steps are detailed below. The following instructions provide example installation.
commands for a Debian-like distribution, but should be fairly easy to adapt to First line of this file looks like::
your environment. In fact, this document is meant as a canonical reference
Once you have run install.sh once, drush and provision should be
that should work on every platform and that can be used for people porting ``127.0.0.1 localhost`` installed and you can use the more powerful hostmaster-install command
Aegir to new platforms or installing on alien platform for which Aegir is not to retry the install if it failed the first time.
yet packaged. Simply add all domains you want to this line. e.g::
3.2 Installing aegir with drush and provision installed
Platform-specific cheat sheets are also available for other platforms in ``127.0.0.1 localhost $AEGIR_HOST $AEGIR_DOMAIN other1 other2`` -------------------------------------------------------
HINTS_*.txt files alongside this document. Those files are basically a
bullet-point summary of the steps required for the installation. In case of If you only intend to use Aegir on a single server, it is acceptable for If you have already downloaded drush and provision, you can just install
conflict between INSTALL.txt and other documentation, INSTALL.txt should be the resolved IP address to be the '127.0.0.1' loopback address. provision in the commands directory of Drush (either ~aegir/.drush or
considered the canonical source of information. /usr/share/drush/commands), if that's not already done. Once provision
If you intend to manage multiple servers using Aegir, you will need to is properly installed, you can install all other aegir components using
Also note that those instructions setup a complete Aegir system. If you want make sure that the IP address is the public IP of this server. the hostmaster-install command.
to only setup a new server, it should be sufficient to install requirement
(step 1) and configure them (step 2). You will just need the --backend-only flag Aegir user Shell commands::
to avoid installing the frontend on the server. ----------
drush hostmaster-install --version=HEAD
1. Install software requirements 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 You will be prompted for the required information if not provided on the
the hosted files. commandline. See the inline help for the available options::
This section describes what is expected of the servers Aegir is running on.
Also to ensure that the file permissions of the hosted sites are always as drush help hostmaster-install
Aegir must run some UNIX flavour because the majority of functionality in this safe as can be, and especially to make sure that the web server does not have
system occurs in the back-end, through command line scripting. There are also the ability to modify the code of the site, the configured system account It is imperative that you provide a valid FQDN to the installer. This is used
several features (such as symlinks), that are not available to users on needs to be a member of the web server group, in order to be able to correctly for database GRANTs. Remote web servers depend on the FQDN being resolvable
Windows. There are no plans currently to add windows support. set the file permissions. in order to connect back to your Aegir master server if it is used as your
database server for managed sites.
The level of access required to be able to configure this system is very far This document assumes the Aegir user is ``aegir``, its home directory is
beyond what is commonly available to users with shared hosting. Commands are ``/var/aegir`` and the webserver group is ``www-data``. You can choose another Upon completion of the installation, the traditional Drupal 'Welcome' e-mail
assumed to be run as root user. username if desired. will be sent to the e-mail address specified by --client_email=(your e-mail)
or if not provided as a command line switch, the address prompted by the
A standard umask of 022 is assumed. This is the default on most systems. In addition we will create a directory layout for Aegir configuration and installer process. This e-mail address will also be used as the default e-mail
backups. address of the first user and client in Aegir, but can be changed later.
Web server
---------- Shell commands:: Checkpoint / Finished!
----------------------
You will need at least one dedicated web server, running Apache. We generally adduser --system --group --home /var/aegir aegir
work with Apache 2 but we should be compatible with the 1.x series. You will adduser aegir www-data #make aegir a user of group www-data At this point, you have checked out all the code and setup your basic Drupal
need root access to that server and the server must be reserved for
system (Drupal core, hosting, hostmaster and eldir) that will be the Aegir
Aegir. Sharing the server with other control panels such as Cpanel, Plesk or frontend and the backend system (provision and drush). Your filesystem layout
AlternC will very likely create problems and is not supported. PHP Configuration should look something like this::
-----------------
PHP 5.2
/var/aegir/hostmaster-0.x/
------- Some complex installation profiles or distributions require a PHP memory limit /var/aegir/hostmaster-0.x/profiles/hostmaster/
that is higher than the default. To avoid common errors when installing sites on /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/admin_menu/
Since Aegir strongly depends on Drush, we therefore depend on PHP 5.2 or some distributions, the PHP command line tool should be configured to use 192Mb /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/hosting/
above. You also need to have the commandline version of PHP to run Drush of RAM. /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/install_profile_api/
properly and the MySQL extensions. /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/jquery_ui/
Change the memory_limit directive in /etc/php5/cli/php.ini to read:: /var/aegir/hostmaster-0.x/profiles/hostmaster/modules/modalframe/
Note that Drupal's support for PHP 5.3 is still under development.
/var/aegir/hostmaster-0.x/profiles/hostmaster/themes/eldir/
Currently, using PHP 5.3 will cause (innocuous) warnings on every page memory_limit = 192M ; Maximum amount of memory a script may consume (192MB) /var/aegir/hostmaster-0.x/sites/aegir.example.com/
load. As a result, we suggest using PHP 5.2 for the time-being. /var/aegir/config/server_master/apache.conf
Most modern Drupal sites require around 96M or even 128M of RAM for certain /var/aegir/config/server_master/apache/conf.d/
See http://drupal.org/node/360605 (amongst other issues) for details. operations. This is far more than what is provided by the default PHP configuration. /var/aegir/config/server_master/apache/vhost.d/
/var/aegir/config/server_master/apache/platform.d/
Database server Change the memory_limit directive in /etc/php5/apache2/php.ini to read:: /var/aegir/backups/
--------------- /var/aegir/drush/drush.php
memory_limit = 128M ; Maximum amount of memory a script may consume (128MB) /var/aegir/.drush/drush_make/
You will require a database server, obviously. Aegir currently only supports /var/aegir/.drush/provision/
MySQL. It is preferable to use a dedicated server since Aegir will create
database users and will requires the use of the mysql 'root' user. Variations on this are acceptable (for example, the Drush Debian package works
Apache configuration out of ``/usr/bin/drush`` and that's fine), but you are better to stick with
Mail transfer agent -------------------- the defaults if you really want to get through this.
-------------------
Aegir assumes a few Apache modules are available on the server, and The installation will provide you with a one-time login URL to stdout or via
Aegir requires an MTA (Mail Transfer Agent) installed on your webserver in generates its own configuration files. The way we enable this is by an e-mail. Use this link to login to your new Aegir site for the first time.
order to be able to install new sites to your new platform. If you don't have symlinking a single file which contains all the configuration necessary.
an MTA, the site installation will fail with message like "could not send In Debian-based systems, you should symlink this file inside
email". Additional messages will show that site has been removed because of ``/etc/apache2/conf.d`` that will be parsed on startup or alternatively
this problem. To remedy the situation simply install an MTA like sendmail, you can place include that file in your apache.conf/httpd.conf. We
postfix, or exim and do the minimal configuration. prefer the former. In other systems there are similar ways to accomplish
this. Consult your OS's documentation if unsure.
Other utilities: sudo, rsync, git and unzip
------------------------------ If you are on a Debian-based system, you will also need to enable the
mod_rewrite module manually.
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. Shell commands as root::
If you want the latest development version, and don't have the git program you
will need to install it on the server. a2enmod rewrite
ln -s /var/aegir/config/apache.conf /etc/apache2/conf.d/aegir.conf
The jQueryUI library is used in the Aegir UI, unzip is required to extract it.
Sudo is required to allow the aegir user the limited privilege to restart the **Do not reload/restart Apache if prompted to after running these commands,
webserver when required. Rsync is used to sync files to remote servers. it will fail.**
The installer script creates the configuration file referenced by the newly
Summary created symlink.
-------
The aegir user needs to have sudo access. Add the relevant line to your sudoers
This may vary according to your platform, but under a Debian derivative, you file.
can install all those packages using the following.
/etc/sudoers configuration::
Shell commands:: aegir ALL=NOPASSWD: /usr/sbin/apache2ctl
apt-get install apache2 php5 php5-cli php5-gd php5-mysql mysql-server Remote web servers
postfix sudo rsync git-core unzip ------------------
Any number of remote web servers may be configured. They need an aegir user and
Apache configuration as above, with the same user name and directory paths. SSH
public/private keys should be set up so hostmaster's Aegir user can access
remote web Aegir users with no passwords. The above apache configuration needs
to be performed too.
They will also need a login shell, which can be modified using the ``chsh`` command.
Shell command as root::
chsh -s /bin/sh aegir
apt-get install rsync apache2 php5 php5-cli php5-mysql
8. Remote servers
Any number of remote web servers may be configured. They need an aegir user and
Apache configuration as above, with the same user name and directory paths. SSH
public/private keys should be set up so hostmaster's Aegir user can access
remote web Aegir users with no passwords. The above apache configuration needs
to be performed too.
They will also need a login shell, which can be modified using the ``chsh`` command.
Shell command as root::
chsh -s /bin/sh aegir
apt-get install rsync apache2 php5 php5-cli php5-mysql
9. Database configuration
To make sure that the Aegir backend, and The installer will prompt you for your MySQL
all the possible web servers can root user password. The root
user will be used to make administrative tasks
reach your database server, you need to such as creating new databases,
configure mysql to listen on all
and granting and revoking access to those
the public IP addresses available to it. databases for sites.
/etc/mysql/my.cnf configuration line to Even though MySQL is now listening on all IP's,
it will not allow invalid users
comment out::
to connect to the databases, without the
bind-address = 127.0.0.1 correct user accounts configured.
Now you need to restart mysql, to clear If you are concerned about MySQL being
any caches. accessible in this way, you can also
configure your firewall to only allow incoming
connections from certain addresses.
Shell command as root:: This is outside the scope of this document
/etc/init.d/mysql restart however.