I read on the Development Seed blog about a New Release: Aegir 0.4 Alpha 5, and since aWebFactory finds itself in the midst of retooling (Git! Aegir! … more soon), I knew this was a great moment for biting the bullet and stop reading about Aegir and actually installing and enjoying all that hard work the devs had been doing.
The post includes a link to mig5’s incredible video (see below for References and links), which also basically follows the step-by-step instructions found in the officially supported INSTALL.txt and the first part of this article basically consists of the steps I took following along. It took me about two hours to install Aegir and make my first use of it (deploying some new staging sites), as well as writing this post.
Server Dependencies
On my Linode VPS Ubuntu server, I already had all of the dependencies met (Apache HTTP Server, MySql, PHP, Git (yeah, I’m hooked), drush (very hooked), etc) but they are all explained in the doc. In fact, one of the things I was concerned about was that installing Aegir wouldn’t disturb my existing Virtual Host staging instances. In any case I did an apt-get update and an apt-get upgrade to make sure my system was up to date (which you should do before installing the dependencies).
Aegir User
For me the first actual step was to install the aegir user, to ensure tasks queued by aegir’s front-end are carried out in the background by a non-root user account via its own crontab command scheduler.
I created the aegir user without a password or a shell:
# adduser --system --group --home /var/aegir aegir
Adding system user `aegir' (UID xxx) ...
Adding new group `aegir' (GID xxx) ...
Adding new user `aegir' (UID xxx) with group `aegir' ...
Creating home directory `/var/aegir' ...
#
# adduser aegir www-data
Adding user `aegir' to group `www-data' ...
Done.
#One more thing which is very important in the default apache server restart command (“sudo /usr/sbin/apache2ctl graceful”) is that the system user “aegir” must be given “sudoer” rights on the system.
This simply means running the command “visudo” in order to edit the sudoers file, and adding the following line, (you will see this covered later on by the wonderful installation wizard of aegir):
aegir ALL=NOPASSWD: /usr/sbin/apache2ctlHit Ctrl-W to write this to disk while in the visudo editor and Ctrl-X to quit.
Apache HTTP server setup
Aegir requires mod rewrite, which I already had enabled since it is also required for running Drupal "clean URLs".The Aegir virtual host setup, which will take advantage of the wild card DNS setup I have for my server in order to be able to create sites associated with subdomains on the fly, needs to be included in the basic Apache setup. This is accomplished with the following command:# echo "Include /var/aegir/config/vhost.d/" > /etc/apache2/conf.d/aegirwhich ensures that the aegir setup, along with all the sites you instantiate on the server with their subdomains and URLs, will be parsed by the Apache server on startup.Create database and database user for Aegir Drupal front-end
I created a database and a database user for aegir just as I would for any Drupal installation. Following along the video, I did it on the command line:
Enter password:
Welcome to the MySQL monitor. Commands end with ; or g.
Your MySQL connection id is 9856
Server version: 5.0.45-Debian_1ubuntu3.4-log Debian etch distribution
Type 'help;' or 'h' for help. Type 'c' to clear the buffer.
mysql> CREATE DATABASE aegir;
Query OK, 1 row affected (0.00 sec)
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER,
-> CREATE TEMPORARY TABLES, LOCK TABLES ON aegir.* TO
-> 'aegir'@'localhost' IDENTIFIED BY 'xxxxxxxx';
Query OK, 0 rows affected (0.04 sec)
mysql> exit;
Bye#DNS setup for Aegir
Just get the wild card setup, as described above, then any site you create can be just another subdomain without touching DNS.
Disabled existing drush install
I had drush 2.0 installed, but was not sure whether or not it was compatible with this newest version of Aegir. Since looking over the script I saw it only downloads the new version of drush if it doesn’t find the drush command in the path, I decided to temporarily at least disable my version 2 of drush. I had drush installed in /usr/local/sbin like so:
root@textworks:/usr/local/sbin # ls -l
total 28
-rwxr-xr-x 1 root staff 753 2007-12-11 06:28 backonedb.sh
-rwx------ 1 root staff 387 2007-12-11 06:29 backupall.sh
-rwxr-xr-x 1 root staff 642 2007-11-26 09:37 backupdb.sh
lrwxrwxrwx 1 root staff 15 2009-07-11 18:29 drush -> drush-2.0/drush
drwxr-xr-x 4 root root 4096 2009-06-08 22:55 drush-2.0
drwxr-sr-x 2 root staff 4096 2009-12-26 13:03 flv
-rwxr-xr-x 1 root staff 558 2008-01-11 06:28 restoredb.sh
-rwxr-xr-x 1 awebfactory awebfactory 30 2007-12-03 06:04 wget-siteSo I simply removed the sybolic link, taking it off the path. We’ll come back to this later.
Installation of Aegir itself
I took Miguel’s advice and grabbed the Aegir install script by selecting and copying it directly from the browser after pointing it at:
http://git.aegirproject.org/?p=hostmaster.git;a=blob_plain;f=install.sh.txt;hb=hostmaster-0.4-alpha5and then pasted it into a text file in any convenient working directory (in my case I chose /tmp/aegir/install.sh.txt).
Before closing it, I did specify the Aegir domain, however, around line 21:
########################################################################
# basic variables, change before release
AEGIR_DOMAIN=aegir.example.com
AEGIR_VERSION=0.4-alpha5
AEGIR_HOME=$HOME
WEB_GROUP=www-data
DRUSH_VERSION=6.x-3.0-alpha1
DRUSH_MAKE_VERSION=6.x-2.0-beta6I changed the AEGIR_DOMAIN from aegir.example.com to reflect my own server domain, then saved the install script.
Still logged in as root, I executed it from the command line with the following (notice full path name of install script):
# su -s /bin/sh aegir -c "sh /tmp/aegir/install.sh.txt"My settings were shown to me, I confirmed by hitting enter, and the script ran.
Well, a bunch of “success” and “ok” signs greeted me as the lines went flying by. Basically, the shiniest version of drush was installed for me, and tested, the provision framework (an extension of drush specially built for aegir) was installed, drupal was downloaded for the aegir front end, the hostmaster package was downloaded, along with its components as per a hostmaster drush make file, a new apache configuration file was installed and so I was told to restart apache and then “follow the wizard”.
I restarted apache with
# apache2ctl restartAnd I was all set. By the way, if you see this error:
[Mon Feb 08 13:26:02 2010] [error] VirtualHost *:80 -- mixing * ports and non-* ports with a NameVirtualHost address is not supported, proceeding with undefined resultsthen it simply means you are using an older version of Ubuntu, with uses the syntax “<VirtualHost *>” instead of “<VirtualHost *:80>” so just edit /var/aegir/config/vhost.d/aegir.webproworkshop.com (whatever it is named as per your system) accordingly. Jaunty and Karmic will be fine without making any changes).
You may need to make other changes, according to your Linux distribution and release. I had to remove the NameVirtualHost statement at the beginning, after getting the following warnings, because the statement was repeated in my oldish Apache settings:
[warn] NameVirtualHost *:80 has no VirtualHosts
[warn] NameVirtualHost *:0 has no VirtualHosts
# apache2ctl restart
#All was well, as soon as I could do an apache restart with no warnings or errors, then I could sing:
We’re off to see the wizard…
I pointed my browser at http://aegir.example.com (actually, it isn’t example.com of course, but rather my server domain), and there was the beautiful Drupal install wizard, offering the Hostmaster install profile just like Miguel’s video. I just followed the instructions (as per the wizard and as per the video) and I was all set. From here on in, for the most part, if you can install Drupal, you can install Aegir. The actual aegir site, of course (it’s in the INSTALL.txt under “Checkpoint” and shown in the video) has /var/aegir/hostmaster-0.4-alpha5 as its document root.
What’s this special database superuser thing?
The wizard is really cool and most things are self-explanatory (or at least INSTALL.txt and/or video-explanatory).
One of the differences between a standard Drupal install and an Aegir install, though, is this “second” database info set you are asked for on the “Configure your database server” asking for an “aegir_root” MySql supervisor user capable of creating databases. These permissions are stronger than those usually given to the regular Drupal mysql user, and you should not use the mysql user running Aegir’s Drupal front end. Instead, click on “How do I configure this” under the “Mysql user account capable of creating new databases” heading. The help there tells you everythng you need to know and holds your hand while you do it 🙂
So I did:
# mysql -uroot -p mysql
Enter password:
mysql> GRANT ALL PRIVILEGES ON *.* TO 'aegir_root'@'localhost'
-> IDENTIFIED BY 'xxxxxxxx' WITH GRANT OPTION;
Query OK, 0 rows affected (0.00 sec)
mysql> exit;
Bye
#Initializing the aegir system
The wizard will soon get you to the hosting system initialization page, which calls for you to login as the aegir system user and execute a special command from a specific directory.
Login as the aegir user:
su -s /bin/sh aegirchange to the aegir document root
cd /var/aegir/hostmaster-0.4-alpha5and execute the following command (note: this command will be tailored to your server domain; copy it from the wizard page):
php /var/aegir/drush/drush.php --uri=http://aegir.example.com hosting-setupJust say yes when asked, and after running the command, you can see that the wizard install info is correct, one of the main things accomplished by this command is the installation of a crontab entry for the aegir user (which is why it must be run as that user):
$ php /var/aegir/drush/drush.php --uri=http://aegir.example.com hosting-setup
This command will replace your crontab for this user. continue? (y/n): y
php '/var/aegir/drush/drush.php' hosting-dispatch --root='/var/aegir/hostmaster-0.4-alpha5' --uri='http://aegir.example.com'
Dispatch command was run successfully [success]
sh-3.2$ crontab -l
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games
*/1 * * * * php '/var/aegir/drush/drush.php' hosting-dispatch --root='/var/aegir/hostmaster-0.4-alpha5' --uri='http://aegir.example.com'
sh-3.2$The “crontab -l” command simply lists the crontab entry for user aegir. Also worthy of note is aegir’s dependency on drush commands.
After doing this, we click the “Next” button and hopefully are greeted by a nice empty “Verify your configuration” page (any errors will be reported here). We click Next once again, in order to import the Aegir site itself, for it to be under the aegis of aegir (sorry, couldn’t resist). We should see a nice green check mark, with everything set to import the aegir site we have just created. Clicking next kicks off some housekeeping… and Next again completes the installation, and clicking on the “your new site” link takes us to our shiny, handsomely efficient looking Aegir dashboard.
Power to the people, indeed! You’ve got your own hosting system server, there, dude!!!
So my client needs a simple e-commerce site…
So should I just smack it together from scratch, just one more time, and stick it into Git, just this time, and then… or should I… YES! Let’s create an e-commerce platform and instantiate it into the site my client needs! Then maybe we can follow that exciting new aegir/drush/git/ Drupal development workflow I was reading about…
Cool!
Well, let’s just get the platform set up and then we’ll create the site off of it, and feel pretty good for just a couple of hours’ work!
The e-commerce platform: set it up with drush_make, tell Aegir, create a site!
So basically, we just need to download our stuff, and then tell Aegir about it. It’s all explained in http://groups.drupal.org/node/24991
But wait, we can go one better. Our friend Miguel (a.k.a mig5) made another video about 3 months ago, called Building Drupal applications with drush_make, provisioning sites with Aegir. Wot, today? Oh, OK!
The video shows how to use http://drupal.org/project/drush_make (whose Aegir version has been included as part of our install) to make scripts similar to module info fiiles, in order to easily create Drupal website applications, and by extension, Aegir platforms.
So, still logged in as the aegir user (if you are logged in as root, just do ” su -s /bin/sh aegir” and “cd /var/aegir”):
$ pwd
/var/aegir
$ mkdir builds
$ cd buildsFollowing Miguel’s lead (in the “building with drush-make” video and also in his workflow blog post, we will create our drush make files here and use the .build extension purely as a convention. In the build directory I create a file e_commerce.build as a trivial starter example, having the following contents to start off with:
$ cat e_commerce.build
core = 6.x
projects[] = drupal
projects[] = acquia_prosper
projects[] = admin_menu
projects[] = adminrole
projects[] = advanced_help
projects[] = cck
projects[] = date
projects[] = filefield
projects[] = imageapi
projects[] = imagecache
projects[] = imagefield
projects[] = pathauto
projects[] = skinr
projects[] = token
projects[] = ubercart
projects[] = vertical_tabs
projects[] = viewsI now execute the makefile to create my ecommerce platform:
$ pwd
/var/aegir
sh-3.2$ ls
backups builds config drush hostmaster-0.4-alpha5
sh-3.2$ php drush/drush.php make builds/e_commerce.build ecommerce
Project information for drupal retrieved. [ok]
Project information for acquia_prosper retrieved. [ok]
Project information for admin_menu retrieved. [ok]
Project information for adminrole retrieved. [ok]
Project information for advanced_help retrieved. [ok]
Project information for cck retrieved. [ok]
Project information for date retrieved. [ok]
Project information for filefield retrieved. [ok]
Project information for imageapi retrieved. [ok]
Project information for imagecache retrieved. [ok]
Project information for imagefield retrieved. [ok]
Project information for pathauto retrieved. [ok]
Project information for skinr retrieved. [ok]
Project information for token retrieved. [ok]
Project information for ubercart retrieved. [ok]
Project information for vertical_tabs retrieved. [ok]
Project information for views retrieved. [ok]
drupal downloaded from [ok]
http://ftp.drupal.org/files/projects/drupal-6.15.tar.gz.
acquia_prosper downloaded from [ok]
http://ftp.drupal.org/files/projects/acquia_prosper-6.x-1.0-beta4.tar.gz.
admin_menu downloaded from [ok]
http://ftp.drupal.org/files/projects/admin_menu-6.x-1.5.tar.gz.
adminrole downloaded from [ok]
http://ftp.drupal.org/files/projects/adminrole-6.x-1.2.tar.gz.
advanced_help downloaded from [ok]
http://ftp.drupal.org/files/projects/advanced_help-6.x-1.2.tar.gz.
cck downloaded from [ok]
http://ftp.drupal.org/files/projects/cck-6.x-2.6.tar.gz.
date downloaded from [ok]
http://ftp.drupal.org/files/projects/date-6.x-2.4.tar.gz.
filefield downloaded from [ok]
http://ftp.drupal.org/files/projects/filefield-6.x-3.2.tar.gz.
imageapi downloaded from [ok]
http://ftp.drupal.org/files/projects/imageapi-6.x-1.6.tar.gz.
imagecache downloaded from [ok]
http://ftp.drupal.org/files/projects/imagecache-6.x-2.0-beta10.tar.gz.
imagefield downloaded from [ok]
http://ftp.drupal.org/files/projects/imagefield-6.x-3.2.tar.gz.
pathauto downloaded from [ok]
http://ftp.drupal.org/files/projects/pathauto-6.x-1.2.tar.gz.
skinr downloaded from [ok]
http://ftp.drupal.org/files/projects/skinr-6.x-1.3.tar.gz.
token downloaded from [ok]
http://ftp.drupal.org/files/projects/token-6.x-1.12.tar.gz.
ubercart downloaded from [ok]
http://ftp.drupal.org/files/projects/ubercart-6.x-2.2.tar.gz.
vertical_tabs downloaded from [ok]
http://ftp.drupal.org/files/projects/vertical_tabs-6.x-1.0-beta7.tar.gz.
views downloaded from [ok]
http://ftp.drupal.org/files/projects/views-6.x-2.8.tar.gz.It worked! Check it out:
$ ls ecommerce/
CHANGELOG.txt INSTALL.mysql.txt MAINTAINERS.txt scripts xmlrpc.php
COPYRIGHT.txt INSTALL.pgsql.txt misc sites
cron.php install.php modules themes
includes INSTALL.txt profiles update.php
index.php LICENSE.txt robots.txt UPGRADE.txt
sh-3.2$ ls ecommerce/sites/all/modules/
admin_menu cck imageapi pathauto ubercart
adminrole date imagecache skinr vertical_tabs
advanced_help filefield imagefield token viewsSo now, let Aegir in on the secret:
- Logged into Aegir, we go to Content management > Create content > Platform
- I type in “ecommerce” as the name, and /var/aegir/ecommerce as the Publish path
- There is no step 3: hit Save
Platform ecommerce has been created. Queued in the tasks on the right-hand side, I see “Verify: ecommerce”. After about a minute, it gets verified, a nice green checkmark appears and “we got platform”.
So now let’s get a site going!
- Content management > Create content > Site
- I type in ec.webproworkshop.com for the Domain name
- I type in my email as the Client (owner)
- I select ecommerce as the platform
- I hit Save
Site ec.webproworkshop.com has been created.
A couple of minutes later, I am notified that the site has been installed. It’s up dude, and running! On the top of the left hand column is a link: “Log in to ec.webproworkshop.com”. OMG. It’s up and running. I hit the Log in button of the one-time login for admin. I’m on the user page for admin. No apache setup for the virtual host; no mysql database setup; no tranferring files. Ok…
I fill in a password. That’s it.
I go to Administer > Site building > Modules and all the modules are there waiting to be enabled.
Oh wow. Why are you still reading this? Go install Aegir!
Epilog
And what Miguel’s video is telling me is that if I had added an install profile (see References below), it would have been automatically detected, the theme would have been enabled together with all the modules; and ubercart with the product module and maybe a default payment gateway.
In another post, we’ll explore how to do that, plus add other configurations, menus, and blocks to the mix via features. Plus migrate sites to production or private development staging servers, backups and all the rest of it.
Also, I will be developing that site, using Git as version control, and will later modify my platform to automatically check out files from that repository.
I will let you know more about this later.
I also will mention any weird additional stuff I run into as I use Aegir in my day to day work in the comments to this post.
References
| Development seed blog announcing release of Aegir 0.4 Alpha 5 | http://developmentseed.org/blog/2010/feb/02/new-release-aegir-04-alpha-5 |
| mig5’s incredible step by step video on how to actually install this latest version of Aegir | http://www.mig5.net/content/video-installing-aegir-04-alpha5 |
| Aegir Hosting System on g.d.o | http://groups.drupal.org/aegir-hosting-system |
| Official announcement of Aegir 0.4 Alpha 5by devs on g.d.o. | http://groups.drupal.org/node/47784 |
| INSTALL.txt | http://git.aegirproject.org/?p=hostmaster.git;a=blob_plain;f=INSTALL.txt;hb=hostmaster-0.4-alpha5 |
| Creating a platform in Aegir | http://groups.drupal.org/node/24991 |
| Building Drupal applications with drush_make, provisioning sites with Aegir | http://vimeo.com/7766472 |
| How to package a profile on drupal.org | http://drupal.org/node/642116 |