community.aegirproject.org
Manual Installation
This page describes to process you need to follow if Aegir doesn't have packages for your distribution. We currently provide Debian packages and others should be coming, if you help! This manual assumes you are fairly familiar with the UNIX commandline interface, but should be possible to follow through if you copy and paste faithfully all steps of the procedure.
A note on supported systems
These instructions provide example commands for a Debian-like distribution, but should be fairly easy to adapt to other environments. This document is meant as a canonical reference that should work on every supported platform. It can also be used for people porting Aegir to new platforms or installing on alien platform for which Aegir is not yet packaged.
It currently contains special recommendations for CentOS, RHEL 6, Arch Linux and Solaris. Users of those platforms are also strongly encouraged to review the common installation problems that occur on those platforms. Aegir is also known to be installable (and was developed partly on) Mac OS X, but that process is so obtuse that it has a separate page for the first part of the manual (up to Install Aegir components).
Installing Aegir may seem daunting at first (which is why we provide automated installs through packages), but once you get around it, it's fairly simple. It follows those steps:
- 1. Review System Requirements
- 2. Install system requirements
- 3. Configure system requirements
- 4. Install Aegir components
- 5. Install the Hosting Queue Daemon
- 6. Checkpoint / Finished!
Note that these instructions setup a complete Aegir system. If you want to only setup a new remote web/db server, it should be sufficient to install the system requirements (step 1), configure them (step 2) and follow the Remote server how-to.
1. Review System Requirements
Find http://community.aegirproject.org/content/installing/system-requirements
2. Install system requirements
To install the required components, run the following command as root:
apt-get install apache2 php5 php5-cli php5-gd php5-mysql php-pear postfix sudo rsync git-core unzip
Note: replace apache2
with nginx php5-fpm
to install nginx on Ubuntu Precise or newer. Since Debian Squeeze doesn't provide php5-fpm, you will need to follow http://www.dotdeb.org/instructions/ before you will be able to install php5-fpm.
2.1. CentOS-specific configuration
yum install httpd php php-mysql php-cli php-gd php-process sudo rsync git postfix
For versions of CentOS previous to 6.0, you will need to upgrade to PHP 5.3 using those instructions.
Also for Centos minimal you should install cron (for queue and drupal cron) and unzip (for jquery.ui)
yum install cronie unzip
2.2. RHEL 6 specific configuration
RHEL 6 Server needs an additional PHP package to enable POSIX support. To find the package php-process you must enable the RHEL Server Optional channel. Once enabled, download and install the php-process-5.3.2-6.el6_0.1.i686.rpm.
You will also need to install the php-xml package if you are planning to use Aegir to manage Drupal 7 sites.
2.3. Solaris specific configuration
Solaris has this way of dealing with third party software that is... far from ideal. You will need to find the best way to install the following packages: apache2, git, sudo, mysql, PHP 5.2 and wget. unzip and sendmail should be part of the base Solaris install. The other applications should be available on the companion CDs or on sunfreeware.com.
In particular, git can be compiled easily by exporting the following environment::
export CFLAGS="-I/usr/sfw/include -I/opt/sfw/include"
export LD_LIBRARY_PATH="/usr/sfw/lib:/opt/sfw/lib:$LD_LIBRARY_PATH"
Then the compile instructions bundled with git should just be followed
directly. I had trouble installing the binaries, as git expects ginstall to be
available in the $PATH
. I ended up adding the source directory in the $PATH
, which works fine for most uses.
2.4. Arch Linux specific configuration
To install the required components, run the following command as root:
pacman -S apache php php-apache php-gd mysql postfix sudo rsync unzip git
Although all of the necessary apache modules and php extensions are installed at this stage, further configuration is required to enable and tweak certain features. Critically, virtual hosts are not enabled. It is worth examining the Arch Linux wiki page on LAMP server set up and verifying that more than one named virtual host functions properly.
If setting up for standalone development, see this useful wiki page to configuring postfix for local mail only.
To ensure Apache and mysql start when the machine boots, enable the httpd and mysqld daemons by adding them to the /etc/rc.conf
file:
DAEMONS=(... mysqld httpd ...)
3. Configure system requirements
3.1. Create the 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.
While you can choose another username, most aegir documentation assumes the Aegir user is aegir
, its home directory is /var/aegir
and the webserver group is www-data
.
Shell commands as root:
adduser --system --group --home /var/aegir aegir
adduser aegir www-data #make aegir a user of group www-data
3.1.1. CentOS specific configuration
CentOS requires special commands to create the user, use those instead:
useradd --home-dir /var/aegir aegir gpasswd -a aegir apache chmod -R 755 /var/aegir
3.1.2. Solaris specific configuration
groupadd aegir useradd -g aegir -G webservd -d /var/aegir -s /bin/bash -c "Aegir sandbox" aegir chown aegir:aegir /var/aegir
3.1.3. Arch Linux specific configuration
useradd --system --groups http --home /var/aegir --create-home aegir chmod -R 755 /var/aegir
3.2. Webserver configuration
Aegir supports two popular web servers, Apache and Nginx.
3.2.1. Apache configuration
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.
If you are on a Debian-based system, you will also need to enable the mod_rewrite module manually.
Run the following shell commands as root. First, configure Apache to enable RewriteEngine:
a2enmod rewrite
Finally, create a symlink from an apache configuration file to a folder within the /var/aegir/:
ln -s /var/aegir/config/apache.conf /etc/apache2/conf.d/aegir.conf
3.2.1.1. Ubuntu 14.04+ specific Apache configuration
Ubuntu 14.04 departs from Debian and previous Ubuntu Apache setup in that it doesn't use /etc/apache2/conf.d
any more and better separates out sites-enabled
from conf-enabled
configurations. So:
ln -s /var/aegir/config/apache.conf /etc/apache2/conf-available/aegir.conf
a2enconf aegir
Do not reload/restart Apache if prompted to after running these commands, it will fail.
3.2.1.2. CentOS specific Apache configuration
On CentOS, mod_rewrite is enabled by default and you can create the following symlink:
ln -s /var/aegir/config/apache.conf /etc/httpd/conf.d/aegir.conf
3.2.1.3. Arch Linux specific Apache configuration
On Arch Linux, mod_rewrite is also enabled by default. Add the aegir apache configuration include file to the httpd.conf file:
echo "Include /var/aegir/config/apache.conf" >> /etc/httpd/conf/httpd.conf
3.2.1.4. Other systems' Apache configuration
In other systems that do not have a conf.d directory, this could also work:
echo "Include /var/aegir/config/apache.conf" >> /etc/apache2/httpd.conf
N.B.:
- A standard umask of 022 is assumed. This is the default on most systems.
- For more information, see the common installation errors.
- For all OSes, the installer script creates the configuration file referenced by the newly created symlink/or file referenced in the Apache config file.
3.2.2. Nginx configuration
(If you just succeeded in installing Apache, please skip this section.)
Aegir assumes standard Nginx configuration is 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/nginx/conf.d
that will be parsed on startup.
Please make sure your nginx installation is up and running before continuing. On Ubuntu 12.04 Server, for instance, you must edit /etc/nginx/nginx.conf and uncomment the line "types_hash_max_size 2048;" in order for nginx to start successfully.
Shell command as root::
ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf
Do not reload/restart Nginx after running these commands, it will fail.
The installer script creates the configuration file referenced by the newly created symlink.
3.3. PHP configuration
Some complex installation profiles or distributions require a PHP memory limit that is higher than the default. To avoid common errors when installing sites on some distributions, the PHP command line tool should be configured to use 192Mb of RAM.
Change the memory_limit directive in /etc/php5/cli/php.ini to read:
memory_limit = 192M ; Maximum amount of memory a script may consume (192MB)
Most modern Drupal sites require around 96M or even 128M of RAM for certain operations. This is far more than what is provided by the default PHP configuration.
Change the memory_limit directive in /etc/php5/apache2/php.ini to read:
memory_limit = 128M ; Maximum amount of memory a script may consume (128MB)
If your distributions require more memory than these limits, then use some common sense and update it as appropriate to suit your individual needs.
For Aegir 3, make sure you've installed the required PHP extensions, particularly the image library (php-gd).
3.3.1. RHEL 6 specific configuration
The default php.ini configuration beyond the above changes also requires that the timezone be set for your location. Otherwise, you get fun errors and warnings during the host-master install step.
- sudo vi /etc/php.ini
- enter your password
- /zone (this will bring you to the date specific timezone module area
Remove the semi colon in front of date.timezone and enter your specific timezone.
[Date]
; Defines the default timezone used by the date functions
; http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone
date.timezone = Your Time Zone Goes HereRestart apache to compile these changes.
sudo httpd -k graceful
3.3.2. Arch Linux specific configuration
Make the following changes to the php.ini file (/etc/php/php.ini
):
Add :/var/aegir/
to the open_basedir
directive:
open_basedir = /srv/http/:/home/:/tmp/:/usr/share/pear/:/var/aegir/
Add date.timezone
value as per PHP's runtime configuration instructions - this is an example:
date.timezone = Europe/London
Modify the memory_limit
directive:
memory_limit = 192M
Uncomment
extension=posix.so
extension=mysqli.so
3.4. Sudo configuration
Next, we need to give the aegir user permission to execute the Apache2 command to restart the web server without entering a password.
Create a file at /etc/sudoers.d/aegir
and add the following:
Defaults:aegir !requiretty aegir ALL=NOPASSWD: /usr/sbin/apache2ctl
After saving, change the permissions on the file:
chmod 0440 /etc/sudoers.d/aegir
Note - the path to your apache2ctl program may differ from this example. On some systems it may also be called 'apachectl' instead of apache2ctl. Adjust to suit your own requirements.
3.4.1. CentOS Linux specific sudo configuration
For CentOS apache2ctl is apachectl and you should use this instead, as root::
visudo
This command opens an editor to allow you to edit the /etc/sudoers file. Add the following to the end of the file (specific directions cannot be given since this depends on what editor you're using):
Defaults:aegir !requiretty
aegir ALL=NOPASSWD: /usr/sbin/apachectl
Note - the !requiretty
bit is to make aegir able to run sudo even though it's not attached to a terminal. By default CentOS enforces requiretty so this exception is necessary.
3.4.2. Nginx specific configuration
For those using Nginx, set the sudoers line as follows
aegir ALL=NOPASSWD: /etc/init.d/nginx
3.5. DNS configuration
Aegir requires a properly configured "FQDN" (Fully Qualified Domain Name) be assigned to the machine. In practice, this means that the hostname returned by the hostname
and uname -n
shell commands should resolve to the IP address for this server, and vice versa.
If you only intend to use Aegir on a single server, it is acceptable for the resolved IP address to be the '127.0.0.1' loopback address.
If you intend to manage multiple servers using Aegir, you will need to make sure that the IP address is the public IP of this server.
You can add multiple entries to your /etc/hosts file for testing purposes, for example:
127.0.0.1 aegir.example.com example.com test1.example.com test2.example.com test3.example.com
Then you can use test1.example.com to create your first site.
3.6. Database configuration
Aegir supports MySQL right now. It is best to install the MySQL server using your Linux distribution's package manager.
Shell commands as root::
apt-get install mysql-server
To make sure that the Aegir backend, and all the possible web servers can reach your database server, you need to configure mysql to listen on all the public IP addresses available to it.
Again, as root, edit the MySQL configuration file /etc/mysql/my.cnf
configuration line to comment out by placing a # at the beginning of the line as follow:
Before
bind-address = 127.0.0.1
After
# bind-address = 127.0.0.1
Without this line commented out, MySQL will listen only on localhost for database connection requests.
Now you need to restart mysql, to clear any caches.
Shell command as root:
/etc/init.d/mysql restart
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.
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.
Note that Aegir will ask you for your MySQL root password. If you do not want to use your regular root password for Aegir, you will need to create another root account for Aegir using a MySQL command like:
GRANT ALL PRIVILEGES ON *.* TO 'aegir_root'@'%' IDENTIFIED BY 'password' WITH GRANT OPTION;
Note: If you are running your Aegir databases on a remote DB server, you will want to create this aegir_root user. The install will often fail if you're trying to use the root user on a remote database. See this issue for details.
3.6.1. Ubuntu, RHEL, Arch linux specific configurations
NOTE: If you are running either Ubuntu 12.04 LTS, RHEL 6 or Arch Linux, you should still install MySQL in the same way as above. However, once done, you must now remove the anonymous, passwordless login that those platforms creates by default. To do this, run:
sudo mysql_secure_installation
Otherwise, Aegir will fail to install and work at all. See this FAQ entry.
3.6.2. RHEL 6 specific configuration
In Red Hat, you may need to move a default configuration file from /usr/share/mysql/
to /etc/my.cnf
to view or modify any of the settings mentioned above.
4. Install Aegir components
Next step is to install the Aegir software components themselves, that is: drush, provision and hostmaster.
4.1. Install drush
Before installing Aegir proper, you first need to install Drush. This can be done through your operating system's package manager (Drush is shipped with Debian and Ubuntu currently) or by following the Drush README.txt file which has all the information for installing and using drush.
Note for 1.x users: you should use Drush version 4. Aegir 1.x does not support Drush 5. Also note there is a bug in Drush 4.0 and 4.1 so you should use a version of Drush between 4.1 and 5.
pear channel-discover pear.drush.org pear install drush/drush-4.6.0
Note for 2.x users: you need to install a minimum of Drush version 5.10, though Drush 6.x is recommended. In this case, you may be able to install the regular release:
Note for 3.x users: you need to install a minimum of Drush version 6,some time you need apt-get install php-console-table before you become the Aegir user:
pear channel-discover pear.drush.org pear install drush/drush
This should install Drush system-wide, but if you follow the manual install, you may end up with Drush in a non-standard location (traditionally /var/aegir/drush/drush.php
), in which case you will need to add that directory to your path or use the following symlink:
ln -s /var/aegir/drush/drush /usr/local/bin/drush
4.1.1. Arch Linux specific configuration
It seems that Arch's PHP environment needs to be modified for Drush:
mkdir /var/aegir/.drush cp /etc/php/php.ini /var/aegir/.drush/
Edit /var/aegir/.drush/php.ini
to remove the values after open_basedir =
, as this will any open_basedir
values are likely to cause Drush to fail.
4.2. Stop! Now become the Aegir user!
The remaining of this manual assumes you are running as the Aegir user. Things will go very wrong if you do not change your shell credentials to become that user. You can do this by running the following command as root:
su -s /bin/bash - aegir
If this fails because /bin/bash
doesn't exist, try using /bin/sh
.
4.3. Install provision
Once Drush is installed you should be able to install the latest recommended Provision release using the following drush command:
Note for 1.x users:
drush dl --destination=/var/aegir/.drush provision-6.x
Note for 2.x users:
drush dl --destination=/var/aegir/.drush provision-6.x-2.0 drush cache-clear drush
Note for 3.x users: replace provison-6.x-2.0 to provison-7.x
4.4. Running hostmaster-install
Once you have downloaded drush and provision, you can just install provision in the commands directory of Drush (either ~aegir/.drush or /usr/share/drush/commands), if that's not already done. Once provision is properly installed, you can install all other aegir components using the hostmaster-install command:
drush hostmaster-install
You will be prompted for the required information if not provided on the commandline. See the inline help for the available options:
drush help hostmaster-install
For example, to install the frontend on Nginx, use:
drush hostmaster-install --http_service_type=nginx
Note for 2.x users: Drush 5 has a commandfile cache which you need to clear before installing Aegir:
drush cache-clear drush
It is imperative that you provide a valid FQDN to the installer. This is used for database GRANTs. Remote web servers depend on the FQDN being resolvable in order to connect back to your Aegir master server if it is used as your database server for managed sites.
Upon completion of the installation, the traditional Drupal 'Welcome' e-mail 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 installer process. This e-mail address will also be used as the default e-mail address of the first user and client in Aegir, but can be changed later.
There are other commandline switches available, documented in drush help hostmaster-install
, as usual.
4.4.1. Arch Linux specific configuration
drush hostmaster-install --web_group=http
5. Install the Hosting Queue Daemon
For Aegir 2.x installs, using the Hosting Queued Daemon (hosting_queued) is highly recommended. For Aegir 1.x, check out http://drupal.org/project/hosting_queue_runner instead.
These instructions will install the daemon to run as a regular service in /etc/init.d/. Instructions will vary according to platforms, but the following should work in Debian, running as root.
Install the init script in place
cp <hostmaster_platform_root>/profiles/hostmaster/modules/hosting/queued/init.d.example /etc/init.d/hosting-queued
Setup symlinks and runlevels
update-rc.d hosting-queued defaults
Start the daemon
/etc/init.d/hosting-queued
6. Checkpoint / Finished!
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-1.x/ /var/aegir/hostmaster-1.x/profiles/hostmaster/ /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/admin_menu/ /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/hosting/ /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/install_profile_api/ /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/jquery_ui/ /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/modalframe/ /var/aegir/hostmaster-1.x/profiles/hostmaster/themes/eldir/ /var/aegir/hostmaster-1.x/sites/aegir.example.com/ /var/aegir/config/server_master/apache.conf /var/aegir/config/server_master/apache/conf.d/ /var/aegir/config/server_master/apache/vhost.d/ /var/aegir/config/server_master/apache/platform.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 the defaults if you really want to get through this.
The installation will provide you with a one-time login URL to stdout or via an e-mail. Use this link to login to your new Aegir site for the first time.
For troubleshooting this process and resulting install, see the common installation problems page.
You may also want to read on with what you can do with Aegir now that it is installed.
Mac OS X installation instructions
Apache
For Apache based installation hints see Apache / mySQL / PHP / Aegir
Nginx
Nginx is more performant than Apache, if you are interested in setting Aegir up using nginx Brian Gilbert from Realityloop has created a script to install everything that you need on a clean Mac (not already running anything on port 80), see OSX Aegir Installer on github.
Apache / mySQL / PHP / Aegir
This is a helper file to the canonical manual install process. It is aimed at helping you install Aegir on Mac OS X. Since PHP and MySQL support on OS X is fairly limited and complicated, a separate documentation page was created for that part of the documentation. You should follow this page all the way through and then proceed with the regular install, step 4: becoming the aegir user.
1. Special software requirements
While Mac OS X comes with Apache & PHP (and even MySQL on the Server version), the version of PHP shipped with 10.6 Snow Leopard is 5.3.x and thus may not work with Aegir (as of the 0.4alpha-era) and various other software. If you're running 10.5 Leopard, it may work out of the box, but I haven't tested it.
There are several different ways to get Apache, PHP 5.2, and MySQL 5 onto a Mac OS X machine. I give detailed instructions for MacPorts below, but if that's a bit more than you're ready to bite off right now, feel free to use an alternative approach.
One such alternative is MAMP. There is a good but outdated HOWTO for installing Aegir on Mac OS X 10.6 (Snow Leopard) using MAMP located here: http://groups.drupal.org/node/30270
MAMP stands for Mac, Apache, MySQL, and PHP and is the Mac equivalent of "LAMP". It is a self-contained package of all of these programs with a nice graphical installer and control panel. You can find it here: http://www.mamp.info/
MAMP is pretty straightforward, but it's also not very flexible (IMHO). While certainly not without its own headaches, MacPorts is a decently powerful way to sanely manage a healthy stack of open source UNIX software on your Mac. Since this is what I use, I'm going to assume MacPorts is in use for the rest of this HINTS file. I have also only tested this on Mac OS X 10.6 Snow Leopard.
If you don't yet have MacPorts installed, go here to get it: http://www.macports.org/install.php
Once it's installed, quit and re-launch your Terminal before continuing. Otherwise MacPorts won't yet be in your PATH.
The first two commands below are optional but recommended.
sudo port selfupdate
sudo port upgrade outdated
sudo port install apache2 mysql5-server git-core unzip php52 php5-posix php5-gd php5-apc +mysql5
php5-apc is optional, but highly recommended as it will significantly increase PHP performance.
Watch the output of the last port command carefully, as there are usually some boring tasks for you to perform once the install is done. You'll be wishing you were running Ubuntu/Debian and apt-get by the time you're done.
2. Configure system requirements
Next we'll create the aegir user and add it to the _www group. This part is very different on Mac OS X than Linux or most other Unices. Must be a NeXTism. The command we will use he is "dscl", which is a short for Directory Service Command Line. In OSX 10.3 and earlier, that command is "nicl" (short for Net Info Command Line). It is also possible to create the user using the "Workgroup Manager" utility included with OS X Server. To obtain Workgroup Manager for the OS X Client, download the "Server Admin Tools" from Apple. For example, for Mac OS X 10.6, the admin tools can be found at:
http://support.apple.com/downloads/Server_Admin_Tools_10_6
sudo dscl . -create /Users/aegir NFSHomeDirectory /var/aegir
Now you need to find the next spare UID to assign the user.
Here's how you find out on your system:
sudo dsexport users.out /Local/Default dsRecTypeStandard:Users
Then open the file users.out in a text editor, search for the highest 5xx user ID and add 1 to it (in your brain, not in the file). So if you find 506 but no 507, use 507. When you're done, delete users.out to be safe.
sudo rm users.out
Now assign this UID to the aegir user, replacing "5xx" with the UID.
sudo dscl . -create /Users/aegir UniqueID 5xx
!! If you're running Mac OSX Lion, you also need to assign PrimaryGroupID to the aegir user. sudo dscl . -create /Users/aegir PrimaryGroupID XXX
Set a secure password for the aegir user, as it needs shell access.
sudo passwd aegir
Create the aegir home directory and set its permissions.
sudo mkdir /var/aegir
sudo chown aegir /var/aegir
sudo chgrp _www /var/aegir
Add the aegir user to the _www group. This is the group Apache runs as.
sudo dscl . -append /Groups/_www GroupMembership aegir
Give the aegir user the ability to restart Apache.
sudo mv /usr/sbin/apachectl /usr/sbin/apachectl-apple
sudo ln -s /opt/local/apache2/bin/apachectl /usr/sbin/apachectl
sudo visudo
Go to the last line of the file and add the following.
aegir ALL=NOPASSWD: /usr/sbin/apachectl
Save the file and exit your text editor.
Next configure Apache to include the Aegir config.
echo "Include /var/aegir/config/apache.conf" >> /opt/local/apache2/conf/httpd.conf
Configuring your MySQL database and user accounts is the same as in the INSTALL.txt file. But you probably want to add the path to its executables to your user's PATH and the aegir user's PATH.
echo 'export PATH=/opt/local/lib/mysql5/bin:$PATH' >> ~/.profile
su - aegir
Password: (the password you setup earlier)
echo 'export PATH=/opt/local/lib/mysql5/bin:$PATH' >> ~/.profile
exit
nginx / MariaDB / PHP / Aegir (MEMPÆ)
The instructions that used to be here are now outdated, instead use the OSXAegirInstaller created by Brian Gilbert of Realityloop.
Centos 6.x Aegir Install Guide
There are 2 methods of installing AEgir on CentOS both are the same but one is scripted and the other is manual and is documented below.
Scripted
The script can be found at https://github.com/marafa/aegir/tree/master/version2
NB. There is preliminary work to fix selinux at https://github.com/marafa/aegir/blob/master/aegir_selinux.sh. Feedback is quite welcome as well as git pulls.
Explanation
Connect to the server via ssh as root user.
ssh root@000.000.000.000
Install system requirements
yum install httpd php php-mysql php-cli php-gd php-process php-pear php-mbstring php-xml php-soap sudo rsync git postfix tree wget cronie unzip mysql-server mlocate nmap samba samba-client samba-common vim
Note: The following packages are not required but are very useful to include git wget mlocate nmap samba samba-client samba-common vim
SElinux
Make sure Security-Enhanced Linux is disabled as it creates install problems.
vim /etc/selinux/config Make sure SELINUX=disabled
If was SELINUX=enabled then we need to restart.
shutdown -r now
Note: I am not sure if it can be enabled at the end I have never tried.
Create the 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.
While you can choose another username, most aegir documentation assumes the Aegir user is aegir, its home directory is /var/aegir and the webserver group is www-data.
useradd --home-dir /var/aegir aegir
gpasswd -a aegir apache
chmod -R 755 /var/aegir
Apache configuration
Start Apache
service httpd start
Make apache start automatically after reboot.
chkconfig httpd on
We need to create a symbolic link between aegir and apache.
ln -s /var/aegir/config/apache.conf /etc/httpd/conf.d/aegir.conf
PHP configuration
vim /etc/php.ini
Increase the memory limit as complex installation profiles or distributions require a PHP memory limit that is higher than the default (128M)
memory_limit = 192M
Set Date Zone to your time zone see http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone
date.timezone = “”
Sudo configuration
Next, we need to give the aegir user permission to execute the Apache2 command to restart the web server without entering a password.
visudo
Add to end of file
Defaults:aegir !requiretty
aegir ALL=NOPASSWD: /usr/sbin/apachectl
DNS configuration
Aegir requires a properly configured "FQDN" (Fully Qualified Domain Name) be assigned to the machine. In practice, this means that the hostname returned by the hostname and uname -n shell commands should resolve to the IP address for this server, and vice versa.
If you only intend to use Aegir on a single server, it is acceptable for the resolved IP address to be the '127.0.0.1' loopback address.
If you intend to manage multiple servers using Aegir, you will need to make sure that the IP address is the public IP of this server.
You can add multiple entries to your /etc/hosts file for testing purposes, for example:#> >vim /etc/hosts Add your ip and hostname
000.000.000.000 hostname
Database configuration
Start mysql
service mysqld start
Make mysql start automatically after reboot.
chkconfig mysqld on
Configure Mysql
/usr/bin/mysql_secure_installation
Recommended:
Set root Password
Remove anonymous users? y
Disallow root login remotely? y
Remove test database and access to it? y
Reload privilege tables now? y
Install drush
pear channel-discover pear.drush.org
pear install drush/drush-4.5.0
Check if drush works If you get PHP Fatal error: Class 'Console_Table' not found then
pear install Console_Table
Stop! Now become the Aegir user!
The remaining of this manual assumes you are running as the Aegir user. Things will go very wrong if you do not change your shell credentials to become that user.
su -s /bin/bash - aegir
Install provision
drush dl --destination=/var/aegir/.drush provision-6.x
Clear the drush cache
drush cache-clear drush
Run hostmaster-install
drush hostmaster-install
Manual install of a web cluster aegir using nginx
These are some really rough notes on how to go about creating a 4 server aegir installation (aegir, mysql, web1, web2).
Adapted from reading through the BOA project and my own experimentation.
** Note -- regarding the wildcard SSL, your sites will need some configuration in your settings.php or local.settings.php to check for the X-Forwarded-Proto headers. I can't recall if the wildcard SSL config.
These notes also assume the last Ubuntu LTS -- 10.04/Lucid.
aegirmysql: sudo apt-get update sudo apt-get upgrade sudo apt-get install vim mysql-server _USER="aegir" _DOMAIN="aegir.domain.com" _AEGIR_HOST="aegir.server.hostname" _AEGIR_HOST_IP="123.456.789.01" _AEGIR_PASSWORD="password" #AEGIR_DB_USER=aegir_root #AEGIR_DB_PASS=`echo $RANDOM:\`date\`:$AEGIR_HOST | openssl md5` echo "[client] user=root password=password" >> .my.cnf mysql -uroot mysql<<EOFMYSQL GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_DOMAIN' IDENTIFIED BY 'password' WITH GRANT OPTION; GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_AEGIR_HOST' IDENTIFIED BY 'password' WITH GRANT OPTION; GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_AEGIR_HOST_IP' IDENTIFIED BY 'password' WITH GRANT OPTION; GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION; FLUSH PRIVILEGES; EOFMYSQL ======================== # https://launchpad.net/~brianmercer/+archive/nginx # https://launchpad.net/~nginx/+archive/php5 aegircontrol: sudo apt-get update sudo apt-get upgrade sudo mkdir -p /var/www/nginx-default #php5-suhosin CATHOSTDEBDEPS="git-core git-doc mysql-client-5.1 vim nginx-custom drush postfix php5-cli php5-mysql php5-fpm php5-gd rsync unzip bzr patch curl" sudo apt-get -V install $CATHOSTDEBDEPS #postfix config already sorted sudo adduser --system --group --home /var/aegir aegir sudo adduser aegir www-data sudo chsh -s /bin/bash aegir #patch drush, re: ereg() #as root: echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf #disable directives in nginx.conf: #types_hash_max_size #tcp_nopush #error_log invoke-rc.d nginx restart #install SSL cert to: /etc/ssl/private/domain.com.cert.pem cd /etc/ssl/private/ ln -s domain.com.cert.pem nginx-wild-ssl.crt ln -s domain.com.cert.pem nginx-wild-ssl.key #install SSL config to: /var/aegir/config/server_master/nginx/pre.d/nginx_wild_ssl.conf #TODO: also install for /var/aegir/config/server_aegirweb{1,2}.host.name #as aegir: cd ~ mkdir .ssh ssh-keygen -t rsa ln -s /usr/share/drush /var/aegir/drush mkdir ~/.drush cd ~/.drush wget -c http://ftp.drupal.org/files/projects/provision-6.x-1.3.tar.gz tar -zxf provision-6.x-1.3.tar.gz #htaccess password bit mkdir ~/tmp cd ~/tmp git clone --branch develop git://github.com/computerminds/aegir_http_basic.git #must be develop branch to use crypt() and for nginx support cp -r aegir_http_basic/provision ~/.drush/provision/aegir_http_basic cp -r aegir_http_basic/hosting ~/hostmaster-6.x-1.3/profiles/hostmaster/modules/hosting/http_basic_auth #set directory permissions? -- patch aegir/http_basic module to do so? _DOMAIN="aegir.domain.com" _USER="aegir" #_AEGIR_HOST=`uname -n` _AEGIR_HOST="aegir.server.hostname" _AEGIR_HOME="$HOME" _AEGIR_DB_PASS="password" _AEGIR_DB_HOST="mysql.server.fqdn" _AEGIR_VERSION="1.3" #_AEGIR_ROOT="$_AEGIR_HOME/hostmaster-$_AEGIR_VERSION" _ADM_EMAIL="admin@domain.com"" _WEBG=www-data _USRG=users #going vanilla echo "drush hostmaster-install $_DOMAIN --aegir_host=$_AEGIR_HOST --aegir_db_user=$_USER --aegir_db_pass=$_AEGIR_DB_PASS --http_service_type=nginx --db_service_type=mysql --db_port=3306 --aegir_db_host=$_AEGIR_DB_HOST --client_email=$_ADM_EMAIL --script_user=$_USER --web_group=$_WEBG --profile=hostmaster -d -v" drush hostmaster-install $_DOMAIN --aegir_host=$_AEGIR_HOST --aegir_db_user=$_USER --aegir_db_pass=$_AEGIR_DB_PASS --http_service_type=nginx --db_service_type=mysql --db_port=3306 --aegir_db_host=$_AEGIR_DB_HOST --client_email=$_ADM_EMAIL --script_user=$_USER --web_group=$_WEBG --profile=hostmaster -d -v cd hostmaster-6.x-1.3 echo "alive" >> healthcheck #enable aegir modules drush @hostmaster en hosting_web_cluster drush @hostmaster en hosting_alias drush @hostmaster en hosting_http_basic_auth #*** enable hosting client in features -- disabling client module cause WSOD on site add page # setup aegirweb{1,2} # test ssh to aegirweb{1,2} # add to known_hosts # NOTE: Aegir web clusters need to share the files, and private directories between web servers (also cache directory, if using boost module) # Setup provision hook for NFS links # http://drupal.org/node/1283738 mkdir -p /var/lib/sitedata/aegir chown -R aegir:www-data /var/lib/sitedata/aegir mkdir -p /var/lib/sitedata/aegir/cache chown -R aegir:www-data /var/lib/sitedata/aegir/cache # add web servers # add web cluster #TODO: Add DR web servers to cluster #TODO: Add WR, re: DR web servers & firewall # set date/time settings in Aegir #TODO: Logrotate webserver logs #TODO: Add an alias for the aegir user: #aegir: "admin@domain.com"" ======================== aegirweb{1,2}: #TODO: Check puppeted stuff, fix, etc sudo apt-get update sudo apt-get upgrade sudo mkdir -p /var/www/nginx-default CATWEBDEBDEPS="mysql-client-5.1 vim nginx-custom drush postfix php5-cli php5-mysql php5-fpm php5-gd rsync unzip patch" sudo apt-get -V install $CATWEBDEBDEPS sudo adduser --system --group --home /var/aegir aegir sudo adduser aegir www-data sudo chsh -s /bin/bash aegir #install SSL cert to: /etc/ssl/private/domain.com.cert.pem cd /etc/ssl/private/ ln -s domain.com.cert.pem nginx-wild-ssl.crt ln -s domain.com.cert.pem nginx-wild-ssl.key #install SSL config to: /var/aegir/config/server_master/nginx/pre.d/nginx_wild_ssl.conf #TODO: also install for /var/aegir/config/server_aegirweb{1,2}.host.name #as root: echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers #as aegir: mkdir /var/aegir/.ssh cat aegir.aegircontrol.id_rsa.pub >> /var/aegir/.ssh/authorized_keys2 #TODO: Logrotate webserver logs ==========================
nginx / MariaDB / PHP-FPM Single Server Installation
Note: This installation process assumes that you're using a fresh install of Ubuntu 14.04 x64. If you use a lower version of Ubuntu, you may have trouble with this guide.
On most VPS providers, you'll be logged in as root initially. The installation process below assumes that you are logged in as root. Obviously, this is not a secure long-term solution, so once you're done with this guide, I suggest setting up public key authentication, turning off root login over SSH, and creating yourself a new unprivileged user. That's out of scope for this doc page, so you're probably on your own for that.
Finally, this document assumes that you're going to be installing aegir at aegir.example.com. Any time you see example.com, replace it with your domain.
1. Housekeeping
Make sure you're up to date:
apt-get update
apt-get upgrade
And that you have the the python-software-properties package (we'll need it later):
apt-get install python-software-properties
2. Install MariaDB
From mariadb.org:
MariaDB is a database server that offers drop-in replacement functionality for MySQL.
MariaDB is built by some of the original authors of MySQL, with assistance from the
broader community of Free and open source software developers. In addition to the core
functionality of MySQL, MariaDB offers a rich set of feature enhancements including
alternate storage engines, server optimizations, and patches.
Install MariaDB:
apt-get install mariadb-server
You'll need to set your root password for the MariaDB server
3. Install Nginx
Next, install Nginx and PHP-FPM:
apt-get install nginx php5-cli php5-mysql php5-fpm php5-gd
Create the default docroot for Nginx as well:
mkdir -p /var/www/nginx-default
4. Install all the other stuff
apt-get install git-core git-doc vim drush postfix rsync unzip bzr patch curl
When prompted for Postfix configuration, select "Internet Site", then use "example.com" for the System mail name.
5. Create the Aegir user
Easy:
adduser --system --group --home /var/aegir aegir
adduser aegir www-data
chsh -s /bin/bash aegir
6. Misc Configuration
Make sure the Aegir user is allowed to restart Nginx:
echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers
Symlink Aegir's nginx configuration into place:
ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf
Disable duplicated directives in /etc/nginx/nginx.conf
(the Aegir config specifies these values as well - if you do not disable them in the main nginx.conf, nginx will fail to restart). You can just remove (or comment them out with a "#") the lines that start with the following
types_hash_max_size
tcp_nopush
error_log
Then, restart Nginx:
service nginx restart
7. Install Aegir
IMPORTANT Switch to the Aegir user now: IMPORTANT
su - aegir
cd ~/
Download the latest Provision release:
mkdir ~/.drush
cd ~/.drush
wget -c http://ftp.drupal.org/files/projects/provision-6.x-2.1.tar.gz
tar -zxf provision-6.x-2.1.tar.gz
rm provision-6.x-2.1.tar.gz
Start the Aegir install process:
cd ~/
drush hostmaster-install aegir.example.com \
--aegir_host="aegir.example.com" \
--http_service_type="nginx" \
--aegir_db_user="root" \
--aegir_db_pass="[YOUR ROOT DATABASE PASSWORD]" \
--db_service_type="mysql" \
--db_port=3306 \
--aegir_db_host="localhost" \
--client_email="[YOUR EMAIL ADDRESS]" \
--script_user="aegir" \
--web_group="www-data" \
--profile=hostmaster
8. Optional Improvements
drupal.org/project/hosting_queue_runner
drupal.org/project/provision_boost