These are the installation instructions that are recommended on Debian. Aegir dependencies (Apache, MySQL, PHP...) are also automatically installed. If you are managing the installation from a remote Windows computer, well-known open source tools for this task are for example PuTTY (a SSH client for command line), and WinSCP (a SFTP client with easy text file editing).
If you wish to install Debian packages over an existing manual install, it's possible. See the Debian upgrade procedures.
Debian packages are uploaded to http://debian.aegirproject.org/ shortly after a release. We eventually want to upload those packages to the official archives, but this will take some adaptation and time to sponsor the packages in.
- 1. Adding the project repositories
- 2. Adding the archive key to your keyring
- 3. Adding backports for or manually installing Drush
- 4. DNS configuration
- 5. Manual sudo configuration
- 6. Manual installation of MySQL (on Ubuntu 12.04 LTS)
- 7. Installing Aegir
- 8. Custom Drupal distributions and make files
- 9. Troubleshooting the install
1. Adding the project repositories
Use this command to add the Aegir package "Software Source" repository to your system:
echo "deb http://debian.aegirproject.org stable main" | sudo tee -a /etc/apt/sources.list.d/aegir-stable.list
To install a customized Debian package, see the developer instructions for the debian package. Other distributions are available for courageous people that want to try development versions.
2.x note: to install the development version of Aegir, you can use the
stable distribution above.
2. Adding the archive key to your keyring
This repository self-signs packages uploaded to it (and packages uploaded are verified against a whitelist of trusted uploaders) using OpenPGP (GnuPG, to be more precise).
Use these commands to download and add the repository's PGP key, then update the package list on your system:
wget -q http://debian.aegirproject.org/key.asc -O- | sudo apt-key add -
sudo apt-get update
3. Adding backports for or manually installing Drush
If you are running Debian wheezy or later, or Ubuntu Natty 11.04 or later, you don't need to do anything here. The Drush package you need is available from your distribution's repositories.
1.x note: if you are running Debian Squeeze 6.0 or Debian Squeeze 7.0, add the following line to /etc/apt/sources.list :
deb http://backports.debian.org/debian-backports squeeze-backports main
You might also have to add a proper Pin-Priority before this works. Create a file called drush containing the following and drop it into /etc/apt/preferences.d:
Pin: release a=squeeze-backports
Alternatively, you could download and install the squeeze-backports package for Drush 4.5 directly from: http://packages.debian.org/squeeze-backports/all/drush/download. Then you could install it with:
dpkg -i drush_4.5-2~bpo60+1_all.deb
2.x note: if you are running Debian Squeeze 6.0, to get drush-5.8.x and above, download php-console-table manually and install it
dpkg -i php-console-table_1.1.4-1_all.deb
You do not need to edit /etc/apt/sources.list or create /etc/apt/preferences.d/drush
sudo apt-get update && sudo apt-get install drush
If you are running Debian lenny 5.0 or Ubuntu Maverick 10.10 or Karmic Koala or earlier, we recommend downloading and installing the Drush package manually. The version of Drush in the Ubuntu Universe repository for these versions of Ubuntu is outdated. If you are using Ubuntu Lucid LTS 10.04, you can install the Drush package manually or instead use Brian Mercer's PPA (Personal Package Archive) using the following command:
sudo apt-get install python-software-properties
sudo add-apt-repository ppa:brianmercer/drush
Now run apt-get update again to refresh the apt database.
sudo apt-get update
N.B. Since Aegir 2 requires Drush 5, which in turn requires PHP 5.3+, Drupal 5 sites are not supported in Aegir 2.
4. 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 -f and
uname -n shell commands should resolve to the IP address for this server, and vice versa, with the
resolveip command (included with the mysql-server package).
For Ubuntu, /etc/hosts should have entries that look like:
::1 host.example.com host ip6-localhost ip6-loopback
127.0.0.1 host.example.com host localhost
126.96.36.199 host.example.com host localhost
To set this up in a virtual machine (e.g. Virtualbox), here are the steps:
- Create a new VM
- Go to settings->network. Enable Adapter 2, and set to "host-only"
- Install Ubuntu. Set hostname as FQDN during install
- You may need to add the lines `auto eth1` and `iface eth1 inet dhcp` to /etc/network/interfaces
If you have a virtual machine already setup and want to change the FDQN:
- change /etc/hostname using: `sudo hostname NEW_NAME`
- change /etc/hosts using: `sudo nano /etc/hosts` and change name
- reboot and test `hostname -f`, `uname -n`, `resolveip NEW_NAME`, `resolveip IP`
- YMMV - Your Mileage May Vary
5. Manual sudo configuration
If you are running Debian squeeze or later, or Ubuntu Lucid 11.04 or later, you don't need to do anything here. The Aegir package configures sudoers automatically.
If not, you will need to manually modify your /etc/sudoers file to add the following line:
echo "aegir ALL=NOPASSWD: /usr/sbin/apache2ctl" | sudo tee -a /etc/sudoers
The line above assumes that you have created a user aegir as specified in the installation instructions.
6. Manual installation of MySQL (on Ubuntu 12.04 LTS)
Please note that Ubuntu 12.04 LTS installs, by default, an insecure MySQL installation that contains an anonymous user grant, allowing anyone to login without a password. This breaks Aegir functionality.
If you are running Ubuntu 12.04, you should install MySQL manually, and then ensure it is installed securely:
sudo apt-get install mysql-server
When running 'sudo mysql_secure_installation', answer 'Y' to 'Remove anonymous users?'
By default, a MySQL installation has an anonymous user, allowing anyone
to log into MySQL without having to have a user account created for
them. This is intended only for testing, and to make the installation
go a bit smoother. You should remove them before moving into a
Remove anonymous users? [Y/n] Y
Now you can proceed with installing Aegir below.
7. Installing Aegir
To install aegir, frontend and backend, use the following command:
sudo apt-get install aegir
2.x note: to install Aegir 2, use
sudo apt-get install aegir2 instead.
If apt-get reports that the aegir packages have unmet dependencies, then make sure that you have installed Drush (as explained above). On a debian system, you can force the install of Drush from the squeeze-backports repository:
sudo apt-get -t squeeze-backports install drush
Then install aegir using the apt-get command above.
This will prompt you for the required information (MySQL password, Postfix configuration...) and go ahead with the install.
During the Postfix configuration, the following options appear: "No configuration, Internet site, Internet with smarthost, Satellite system, Local only". That first text screen only allows to use the tab key to select "OK", and then the enter key to display a second screen where you can select one of the choices. The default is "Internet site", useful in most cases to enable the server to send email messages, for example to the admin.
At the end of the installation, you will receive an email message or, if the user "aegir" has been assigned with a local email account during the installation, the file /var/mail/aegir will contain the message. It will include a one-time login to your new Aegir control panel, that is a URL to copy into your browser so that you can set the password for the "admin" user.
8. Custom Drupal distributions and make files
If you have your own Drupal make file, you can go ahead with the above process, but change the make file to the one you want:
echo debconf aegir/makefile string /var/aegir/makefiles/aegir/aegir-custom.make | debconf-set-selections apt-get install aegir
This allows you to specify the makefile path for your custom distribution of Aegir. To maintain these customizations, you'll need to ensure you do the same when upgrading.
An example aegir-custom.make file could look like:
core = 6.x
api = 2
includes[aegir] = "/usr/share/drush/commands/provision/aegir.make"
projects = module_filter
Note that for this to work, you may need the patch from this issue, allowing drush_make to reference absolute system paths. If
drush make --version <= 2.2 you need this patch.
After installing Aegir, you can reinstall the front end (hostmaster), with following commands:
sudo rm -rf /var/aegir/hostmaster-*.*
sudo su -s /bin/sh aegir -c "drush -y hostmaster-install --aegir_db_pass=$DB_PASSWORD --makefile=$MAKEFILE $DOMAIN"
su -s /bin/sh aegir -c "some command"runs
some commandin the
/bin/shshell as user
sucommand as root - prompting for your user's password instead
suasking for aegir's password.
9. Troubleshooting the install
To make the install smoother, the install command is run without much debugging information, which can make diagnostics pretty hard. For this, there's a special environment variable you can set that will trigger debugging output. Install aegir with this*:
env DPKG_DEBUG=developer apt-get install aegir
You can build your own Debian packages from our repositories using those instructions.
Note: Prior to 1.1-4. the command was
env DEBUG=yes apt-get install aegir