HostMaster Easy One Page Install

We try to document here the most current install process of hostmaster and current issues. Please share your steps on installing and setting up HostMaster and related dependencies (Apache, MySQL, cron, etc.).

Those instructions are specific to the 0.1 release. For subsquent releases, see the INSTALL.txt file packaged with the hostmaster install profile.

Install Aegir on Ubuntu/Apache2/php5/mysql5

This is a guide on how to install Aegir on a preconfigured LAMP stack. This guide assumes Ubuntu 8.04, Apache2, php5 and Mysql5 are all configured and working on your system. It also assumes you are installing Aegir on the DRUPAL-5 branch of Drupal.

Checkout from CVS

We will be installing the aegir directory in /var with the Drupal codebase at /var/aegir/drupal-5 so lets move to /var.

cd /var

Now we need to checkout the latest Drupal release (in this case DRUPAL-5-12) from CVS.

sudo cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal co -d aegir/drupal-5 -r DRUPAL-5-12 drupal

To install the required modules for Aegir we need to move into the Drupal codebase

cd aegir/drupal-5/

First we need the Hostmaster profile to use when we install the first Drupal instance. We are using the DRUPAL-5--0-1-BETA2 version of Aegir in this example, however you should use the latest stable release.

sudo cvs co -d profiles/hostmaster -r DRUPAL-5--0-1-BETA2 contributions/profiles/hostmaster

Next we need the two Aegir core modules, hosting and provision. Note that they must be placed in the sites/default/modules directory so no other sites have access to them.

sudo cvs co -d sites/default/modules/hosting -r DRUPAL-5--0-1-BETA2 contributions/modules/hosting

sudo cvs co -d sites/default/modules/provision -r DRUPAL-5--0-1-BETA2 contributions/modules/provision

Aegir also has some third party dependencies which you will need. You should get the latest stable release for these modules.

They do not need to be in sites/default/modules. We will be placing drush in sites/default/modules and cvs deploy in the shared directory.

sudo cvs co -d sites/default/modules/drush -r DRUPAL-5--1-4 contributions/modules/drush

sudo cvs co -d sites/all/modules/cvs_deploy -r DRUPAL-5--1-1 contributions/modules/cvs_deploy

Apache configuration

We need a directory to store the Aegir virtual host configs in. This should be outside the root of the Drupal install.

sudo mkdir -p /var/aegir/config/vhost.d/

We are also going to need the apache rewrite module.

sudo a2enmod rewrite

Next we need to setup a domain to run the Aegir Drupal instance. For the purpose of this guide we will be using the domain aegir.example.com. Lets start by creating an apache virtual host for the domain.

sudo vi /etc/apache2/sites-available/aegir.example.com

This is an example of what your virtual host config should look like. You can customise this to suit your needs but the last line must be included.

  # Admin email, Server Name (domain name) and any aliases
    ServerAdmin admin@example.com
    ServerName  aegir.example.com
    ServerAlias aegir.example.com

  # Index file and Document Root (where the public files are located)
    DirectoryIndex index.html, index.php
    DocumentRoot /var/aegir/drupal-5

    <Directory />
      Options FollowSymLinks
      AllowOverride None
    </Directory>
    <Directory /var/aegir/drupal-5>
      Options Indexes FollowSymLinks MultiViews
      AllowOverride All
      Order allow,deny
      allow from all
     </Directory>



Include /var/aegir/config/vhost.d

Enable your site

sudo a2ensite aegir.example.com

Now lets restart apache

sudo /etc/init.d/apache2 restart

Drupal install

Firstly we need to create a database for the Aegir install.

mysql -u root -p

Once you are logged into mysql you can create the aegir database.

CREATE DATABASE aegir;

You will also need to create a user for this database. Make sure to set a password by replacing XXXXXXX.

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

Exit mysql

exit

We can now point our browser to http://aegir.example.com. You should see the default Drupal install page with the option to select the Hostmaster install profile. Before we can go any further we need to allow the installer access to sites/default/settings.php

sudo chmod a+w /var/aegir/drupal-5/sites/default/settings.php

Select the Hostmaster install profile and fill out the form with the database and user you just created. The installer will then prompt you to secure the settings.php file.

sudo chmod a-w /var/aegir/drupal-5/sites/default/settings.php

There will also be an error message: user warning: Access denied for user 'aegir'@'localhost' to database 'provision_test' query. You can ignore this error as we will be creating another mysql user to handle provisioning in a minute.

Press the 'configure your user account' button in the installer and fill out the details. These will be used as the root login to the Aegir install. Once this is done you can move on and start configuring the provisioning framework.

The first thing the provisioning installer requires is a configuration path.

sudo mkdir -p /var/aegir/config

Lets tighten up the security on that.

sudo chmod 700 /var/aegir/config

Next the provisioning framework wants a backup directory to store all hosted site backups.

sudo mkdir -p /var/aegir/backups

And again, tighten up the security on that.

sudo chmod 700 /var/aegir/backups

Make sure the paths you set in the installer match the paths you have just created.

Once you have done this you can move onto configuring the web server.

The first thing you are asked to do is modify your virtual host file to include the Aegir virtual host directory. We did this when we set up our virutal host so you can move on to the system account details.

The provision framework takes special care to make sure that the file permissions of the hosted sites are always as safe as can be, especially to make sure that the web server does not have the ability to modify the code of the site.

To do this we need a system user for the script to run as. This username needs to be a member of the web server group (in this case www-data), in order to be able to correctly set the file permissions.

sudo adduser --system --home /var/aegir --no-create-home --disabled-login --disabled-password --shell /bin/sh aegir

sudo adduser aegir www-data

It is required that you provide access to the Apache restart command for the user account the script will be running as. If this is not configured, every command will ask for a sudo password when restarting the server.

sudo visudo

This will open the visudo file. You need to add a line at the bottom of the file as follows:

aegir   ALL=NOPASSWD: /usr/sbin/apache2ctl

Save the file and exit.

We should now also change the ownership and grouping of the /var/aegir directory and its contents.

Firstly we make everything aegir.root

sudo chown -R aegir.root /var/aegir

Now we need to change the group to www-data for some directorys.

sudo chgrp -R www-data /var/aegir/*/sites

Finally, we alter the permissions for the sensitive directories.

sudo chmod -R o-rwx /var/aegir/*/sites /var/aegir/config /var/aegir/backups

In the installer you can now enter the user and group for the system account - and the path to the restart command - then move on to configuring your database server.

The database server needs a user to create new databases for each site you install using aegir. It is suggested to have a seperate account than the one used for the aegir database that we setup earlier. Lets get back into mysql.

mysql -u root -p

Lets make another root user for aegir. Make sure to change XXXXXXX to a secure password.

GRANT ALL PRIVILEGES ON *.* TO 'aegir_root'@'localhost' IDENTIFIED BY 'XXXXXXXX' WITH GRANT OPTION;

Exit mysql

exit

In the installer we need to fill out the database account details using the priviledged user credentials we just created (i.e. aegir_root). Once you have done that we can move on to setting up the hosting framework.

The hosting framework can be setup by drush. First lets change to the aegir user.

sudo su aegir

Next we need to move into the Drupal root.

cd /var/aegir/drupal-5

Finally we need to issue the Drush command.

sites/all/modules/drush/drush.php hosting setup

You should receive a response like this:

Created symlink for drush.php file
Generating provision.settings.php file
Changed permissions of provision.settings.php to 400
Dispatch command was run successfully

You can now return the the web installer and follow the instructions to your new Aegir install. You can enable some experimental modules if you like, or just carry on to Aegir and start creating sites.

Adding a platform

This is now working, but with a lot more pains than expected.

then install a drupal on that host. drupal will ask you for a user/pass. i reused the main hostmaster user.

then ask you for a bunch of things like the site name, email, a username, password...

then a bunch of errors:

seems to be harmless.

modules are enabled automatically by the hostslave install profile.

then:

this creates the symlinks.

then create the platform node on the hostmaster site and let the cronjob process the associated tasks.

Issues left:

• this process is too complex and annoying, and should be automated. basically, everything should be in provision setup
• we need to figure out a way to not need the database on the platform
• create site shouldn't allow provisionning hostslave profiles (hostmaster profiles are fine: we'd like to have hostmaster provision itself)
• the hostslave README should mention all of this
• the hostslave README says that we should put the modules in profiles/hostslave/modules, i disagree. they should be in sites/default/modules.

Installing new modules

We also discussed how we would go around easily adding modules into subsites and attempted to do this with drush pm

this doesn't work as the subsite doesn't have drush installed. this is an issue similar to the platform issue.

On your Mac Laptop

For download, feel free to substitute CVS checkout

1. Download Drupal 5 into your root web server docroot (e.g. /Library/WebServer/Documents)
2. Download the hostmaster install profile into the profiles folder, so that it is at /profiles/hostmaster
3. Download required modules: views, drush, ...
4. Create a new directory in the /sites folder with a name equivalent to your local machine -- this can be either 127.0.0.1, localhost, or your machine name (in my case, sleipnir.local) -- and copy over the settings.php file; NOTE: currently, the main hostmaster site can't be run out of the "default" folder
5. Navigate to the new site created in the last step by going to it in your local web browser -- e.g. http://sleipnir.local
6. You should now see the profile selection install screen -- select the Hostmaster option and install
7. Once installed, run through the wizard
8. The only snag you should hit is when it asks you what user/group to use for running the system; the default should show your currently logged in username (e.g. 'bmann'), and the help instructions explain how to use vigr to add that user to a group. This does not work on Mac OS X. This page explains dscl, which is what is used on OS X. On Leopard, you'll need to run the following command: sudo dscl . -append /Groups/_www GroupMembership bmann Alternately, you can also follow instructions on that page to ccreate a brand new 'hm' user and add that user to the '_www' group.

Additional notes

• I ended up using our Bryght Basic Drupal 5 SVN checkout for my D5 base install -- since we backported watchdog you'll need to edit the hostmaster.profile to comment out watchdog as a required module