Commit 7b702629 authored by anarcat's avatar anarcat Committed by anarcat
Browse files

make format uniform: column at 78 chars, rst mode in emacs

parent 99722479
.. -*- mode: rst; fill-column: 78; -*-
.. This document is formatted using the ReST syntax. .. This document is formatted using the ReST syntax.
=============================================== ===============================================
......
.. -*- mode: rst; fill-column: 78; -*-
.. This document is formatted using the ReST syntax. .. This document is formatted using the ReST syntax.
================================================ ================================================
Aegir -- Solaris installation instructions hints Aegir -- Solaris installation instructions hints
================================================ ================================================
This is a helper file to the canonical INSTALL.txt. It is aimed at This is a helper file to the canonical INSTALL.txt. It is aimed at helping you
helping you install Aegir on Solaris. It simply lists commands that install Aegir on Solaris. It simply lists commands that diverge from the base
diverge from the base INSTALL.txt in a concise document that will be INSTALL.txt in a concise document that will be easy to maintain in the long
easy to maintain in the long term. term.
It is recommended that the INSTALL.txt document is consulted before It is recommended that the INSTALL.txt document is consulted before going
going ahead with this install. ahead with this install.
We reuse the same process describe in that document: We reuse the same process describe in that document:
...@@ -46,9 +47,9 @@ environment:: ...@@ -46,9 +47,9 @@ environment::
Then the compile instructions bundled with git should just be followed Then the compile instructions bundled with git should just be followed
plainly. plainly.
XXX: I had trouble installing the binaries, as git expects ginstall to XXX: I had trouble installing the binaries, as git expects ginstall to be
be available in the path. I ended up adding the source directory in available in the path. I ended up adding the source directory in the path,
the path, which works fine for most uses. which works fine for most uses.
2. Configure system requirements 2. Configure system requirements
================================ ================================
...@@ -82,9 +83,8 @@ Shell commands:: ...@@ -82,9 +83,8 @@ Shell commands::
============================ ============================
You should now be in the installation wizard. The wizard is usually You should now be in the installation wizard. The wizard is usually
self-documenting so you should just be able to follow the instructions self-documenting so you should just be able to follow the instructions in the
in the wizard to configure Aegir to properly use the webserver and wizard to configure Aegir to properly use the webserver and database server.
database server.
5. Common issues 5. Common issues
================ ================
...@@ -98,16 +98,16 @@ http://drupal.org/node/637574 ...@@ -98,16 +98,16 @@ http://drupal.org/node/637574
http://drupal.org/node/586466 http://drupal.org/node/586466
Those can be worked around by hardcoding the --php executable on the Those can be worked around by hardcoding the --php executable on the
commandline path. Adding the proper shebang header and using a proper commandline path. Adding the proper shebang header and using a proper PATH
PATH that includes the PHP executable also helps. that includes the PHP executable also helps.
Cron issues Cron issues
----------- -----------
I had numerous problems setting up a proper cron job, as Solaris' I had numerous problems setting up a proper cron job, as Solaris' crond seems
crond seems pretty anal about what it accepts. The only way I could pretty anal about what it accepts. The only way I could get it to work was to
get it to work was to create a wrapper shell script that would be create a wrapper shell script that would be called using the simplest cron
called using the simplest cron tab. tab.
Crontab entry:: Crontab entry::
......
.. -*- mode: rst; fill-column: 78; -*-
.. This document is formatted using the ReST syntax. .. This document is formatted using the ReST syntax.
================================= =================================
Aegir Installation Instructions Aegir Installation Instructions
================================= =================================
------------------------------------------------------------------------------------------------------------------ ------------------------------------------------------------------------------
This document describes briefly how to install a multi-platform, single-server Aegir Drupal provisionning system. This document describes briefly how to install a multi-platform, single-server
------------------------------------------------------------------------------------------------------------------ Aegir Drupal provisionning system.
------------------------------------------------------------------------------
Aegir installation seems difficult at first, but once you get around it, Aegir installation seems difficult at first, but once you get around it, it's
it's fairly simple. It's 4 basic steps: fairly simple. It's 4 basic steps:
1. Install requirements 1. Install requirements
2. Configure system requirements, which include: 2. Configure system requirements, which include:
...@@ -18,86 +20,84 @@ it's fairly simple. It's 4 basic steps: ...@@ -18,86 +20,84 @@ it's fairly simple. It's 4 basic steps:
3. Install the Aegir files 3. Install the Aegir files
4. Follow the install wizard 4. Follow the install wizard
Those steps are detailed below. The following instructions provide Those steps are detailed below. The following instructions provide example
example commands for a Debian-like distribution, but should be fairly commands for a Debian-like distribution, but should be fairly easy to adapt to
easy to adapt to your environment. In fact, this document is meant as a your environment. In fact, this document is meant as a canonical reference
canonical reference that should work on every platform and that can be that should work on every platform and that can be used for people porting
used for people porting Aegir to new platforms or installing on alien Aegir to new platforms or installing on alien platform for which Aegir is not
platform for which Aegir is not yet packaged. yet packaged.
Platform-specific cheat sheets are also available for other platforms in Platform-specific cheat sheets are also available for other platforms in
HINTS_.txt files alongside this document. Those files are basically a HINTS_.txt files alongside this document. Those files are basically a
bullet-point summary of the steps required for the installation. In case bullet-point summary of the steps required for the installation. In case of
of conflict between INSTALL.txt and other documentation, INSTALL.txt conflict between INSTALL.txt and other documentation, INSTALL.txt should be
should be considered the canonical source of information. considered the canonical source of information.
1. Install software requirements 1. Install software requirements
================================ ================================
This section describes what is expected of the servers Aegir is running This section describes what is expected of the servers Aegir is running on.
on.
Aegir must run some UNIX flavour because the majority of functionality Aegir must run some UNIX flavour because the majority of functionality in this
in this system occurs in the back-end, through command line scripting. system occurs in the back-end, through command line scripting. There are also
There are also several features (such as symlinks), that are not several features (such as symlinks), that are not available to users on
available to users on Windows. There are no plans currently to add Windows. There are no plans currently to add windows support.
windows support.
The level of access required to be able to configure this system is very The level of access required to be able to configure this system is very far
far beyond what is commonly available to users with shared hosting. beyond what is commonly available to users with shared hosting. Commands are
Commands are assumed to be run as root user. assumed to be run as root user.
Web server Web server
---------- ----------
You will need at least one dedicated web server, running Apache. We You will need at least one dedicated web server, running Apache. We generally
generally work with Apache 2 but we should be compatible with the 1.x work with Apache 2 but we should be compatible with the 1.x series. You will
series. You will need root access to that server and the server must need root access to that server and the server must be reserved for
be reserved for Aegir. Sharing the server with other control panels Aegir. Sharing the server with other control panels such as Cpanel, Plesk or
such as Cpanel, Plesk or AlternC will very likely create problems and AlternC will very likely create problems and is not supported.
is not supported.
PHP 5.2 PHP 5.2
------- -------
Since Aegir strongly depends on Drush, we therefore depend on PHP 5.2 Since Aegir strongly depends on Drush, we therefore depend on PHP 5.2 or
or above. You also need to have the commandline version of PHP to run above. You also need to have the commandline version of PHP to run Drush
Drush properly and the MySQL extensions. properly and the MySQL extensions.
Database server Database server
--------------- ---------------
You will require a database server, obviously. Aegir currently only You will require a database server, obviously. Aegir currently only supports
supports MySQL. It is preferable to use a dedicated server since Aegir MySQL. It is preferable to use a dedicated server since Aegir will create
will create database users and will require a privileged user. database users and will require a privileged user.
Mail transfer agent Mail transfer agent
------------------- -------------------
Aegir requires an MTA (Mail Transfer Agent) installed on your webserver Aegir requires an MTA (Mail Transfer Agent) installed on your webserver in
in order to be able to install new sites to your new platform. If you order to be able to install new sites to your new platform. If you don't have
don't have an MTA, the site installation will fail with message like an MTA, the site installation will fail with message like "could not send
"could not send email". Additional messages will show that site has been email". Additional messages will show that site has been removed because of
removed because of this problem. To remedy the situation simply install this problem. To remedy the situation simply install an MTA like sendmail,
an MTA like sendmail, postfix, or exim and do the minimal configuration. postfix, or exim and do the minimal configuration.
Other utilities: sudo, git and unzip Other utilities: sudo, git and unzip
------------------------------ ------------------------------
Aegir installs itself via a drush_make file that downloads via git if you want 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. the bleeding edge code, or via wget if you want the latest official release.
If you want the latest development version, and don't have the git program you If you want the latest development version, and don't have the git program you
will need to install it on the server. will need to install it on the server.
The jQueryUI library is used in the Aegir UI, unzip is required to extract it. 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 webserver Sudo is required to allow the aegir user the limited privilege to restart the
when required. webserver when required.
Summary Summary
------- -------
This may vary according to your platform, but under a Debian derivative, This may vary according to your platform, but under a Debian derivative, you
you can install all those packages using the following. can install all those packages using the following.
Shell commands:: Shell commands::
...@@ -108,31 +108,31 @@ Shell commands:: ...@@ -108,31 +108,31 @@ Shell commands::
2. Configure system requirements 2. Configure system requirements
================================ ================================
The following details what configuration needs to be performed on the The following details what configuration needs to be performed on the server
server before going ahead with the install. before going ahead with the install.
Aegir user Aegir user
---------- ----------
The provision framework of Aegir requires that the scripts run as a The provision framework of Aegir requires that the scripts run as a non-root
non-root system account, to ensure that it can correctly set the file system account, to ensure that it can correctly set the file permissions on
permissions on the hosted files. the hosted files.
Also to ensure that the file permissions of the hosted sites are Also to ensure that the file permissions of the hosted sites are always as
always as safe as can be, and especially to make sure that the web safe as can be, and especially to make sure that the web server does not have
server does not have the ability to modify the code of the site, the the ability to modify the code of the site, the configured system account
configured system account needs to be a member of the web server group, needs to be a member of the web server group, in order to be able to correctly
in order to be able to correctly set the file permissions. set the file permissions.
More detailed instructions on this topic will be given later in the web More detailed instructions on this topic will be given later in the web
installation wizard. installation wizard.
This document assumes the Aegir user is ``aegir``, its home directory is This document assumes the Aegir user is ``aegir``, its home directory is
``/var/aegir`` and the webserver group is ``www-data``. You can choose ``/var/aegir`` and the webserver group is ``www-data``. You can choose another
another username if desired. username if desired.
In addition we will create a directory layout for Aegir configuration In addition we will create a directory layout for Aegir configuration and
and backups. backups.
Shell commands:: Shell commands::
...@@ -143,13 +143,12 @@ Shell commands:: ...@@ -143,13 +143,12 @@ Shell commands::
Apache configuration Apache configuration
-------------------- --------------------
The rewrite module must be enabled and also Apache must be given a The rewrite module must be enabled and also Apache must be given a directive
directive to include Aegir's vhosts path, to read configurations from to include Aegir's vhosts path, to read configurations from there. In
there. In Debian-based systems you can put a file inside Debian-based systems you can put a file inside ``/etc/apache2/conf.d`` that
``/etc/apache2/conf.d`` that will be parsed on startup or will be parsed on startup or alternatively you can place the directive in
alternatively you can place the directive in apache.conf/httpd.conf. apache.conf/httpd.conf. We prefer the former. In other systems there are
We prefer the former. In other systems there are similar ways to similar ways to accomplish this. Consult your OS's documentation if unsure.
accomplish this. Consult your OS's documentation if unsure.
Shell commands as root:: Shell commands as root::
...@@ -160,9 +159,9 @@ Shell commands as root:: ...@@ -160,9 +159,9 @@ Shell commands as root::
Database configuration Database configuration
---------------------- ----------------------
Here you want to make a basic database configuration for the Drupal site Here you want to make a basic database configuration for the Drupal site you
you are going to install. You want to run these commands using your are going to install. You want to run these commands using your mysql 'root'
mysql 'root' user, substituting the 'XXXXXXXX' with a real password. user, substituting the 'XXXXXXXX' with a real password.
SQL commands:: SQL commands::
...@@ -177,9 +176,9 @@ DNS Configuration ...@@ -177,9 +176,9 @@ DNS Configuration
Configuring DNS is up to you. Currently Aegir does nothing with DNS. Configuring DNS is up to you. Currently Aegir does nothing with DNS.
As a help trick, if you are installing Aegir locally to try and test it, As a help trick, if you are installing Aegir locally to try and test it, you
you can do local DNS by adding entries to file ``/etc/hosts``. First can do local DNS by adding entries to file ``/etc/hosts``. First line of this
line of this file looks like: file looks like:
``127.0.0.1 localhost your-machine-name`` ``127.0.0.1 localhost your-machine-name``
...@@ -190,31 +189,29 @@ Simply add all domains you want to this line. e.g: ...@@ -190,31 +189,29 @@ Simply add all domains you want to this line. e.g:
3. Install the Aegir files 3. Install the Aegir files
========================== ==========================
This section deals with the installation of Aegir proper. These This section deals with the installation of Aegir proper. These instructions
instructions limit themselves to getting you into the Aegir install wizard, limit themselves to getting you into the Aegir install wizard, which will then
which will then give you further configuration instructions. give you further configuration instructions.
There is an install script part of the hostmaster profile that takes care There is an install script part of the hostmaster profile that takes care of
of installing the right packages and preparing the Drupal frontend install installing the right packages and preparing the Drupal frontend install for
for you. That script needs to be run as the aegir user created above. you. That script needs to be run as the aegir user created above. This file
This file is available alongside this one or can be downloaded through the is available alongside this one or can be downloaded through the web at:
web at:
http://git.aegirproject.org/?p=hostmaster.git;a=blob_plain;f=install.sh.txt;hb=HEAD http://git.aegirproject.org/?p=hostmaster.git;a=blob_plain;f=install.sh.txt;hb=HEAD
By default, the install script will install the "correct" version of By default, the install script will install the "correct" version of Aegir
Aegir (ie. if it was downloaded through git, it will install the version (ie. if it was downloaded through git, it will install the version from the
from the git master branch. If you downloaded an official release, it should git master branch. If you downloaded an official release, it should install
install the official release.). You can modify which version to install by the official release.). You can modify which version to install by editing the
editing the AEGIR_VERSION variable in the script. AEGIR_VERSION variable in the script.
The install script is shipped with other default settings that you The install script is shipped with other default settings that you will likely
will likely need to change (such as the URL of the Aegir site) prior need to change (such as the URL of the Aegir site) prior to running it.
to running it.
You can change which release to install or other parameters such as these You can change which release to install or other parameters such as these
through options passed to the script. Run "sh through options passed to the script. Run "sh install.sh.txt -h" for more
install.sh.txt -h" for more information on the available options. information on the available options.
Shell commands:: Shell commands::
...@@ -226,10 +223,10 @@ Note you must run this as root or prefix with sudo. ...@@ -226,10 +223,10 @@ Note you must run this as root or prefix with sudo.
Checkpoint! Checkpoint!
----------- -----------
At this point, you have checked out all the code and setup your basic At this point, you have checked out all the code and setup your basic Drupal
Drupal system (Drupal core, hosting, hostmaster and eldir) that will be the system (Drupal core, hosting, hostmaster and eldir) that will be the Aegir
Aegir frontend and the backend system (provision and drush). Your frontend and the backend system (provision and drush). Your filesystem layout
filesystem layout should look something like this:: should look something like this::
/var/aegir/hostmaster-0.x/ /var/aegir/hostmaster-0.x/
/var/aegir/hostmaster-0.x/profiles/hostmaster/ /var/aegir/hostmaster-0.x/profiles/hostmaster/
...@@ -246,20 +243,19 @@ filesystem layout should look something like this:: ...@@ -246,20 +243,19 @@ filesystem layout should look something like this::
/var/aegir/.drush/drush_make/ /var/aegir/.drush/drush_make/
/var/aegir/.drush/provision/ /var/aegir/.drush/provision/
Variations on this are acceptable (for example, the Drush Debian Variations on this are acceptable (for example, the Drush Debian package works
package works out of ``/usr/bin/drush`` and that's fine), but you are out of ``/usr/bin/drush`` and that's fine), but you are better to stick with
better to stick with the defaults if you really want to get through this. the defaults if you really want to get through this.
4. Follow the install wizard 4. Follow the install wizard
============================ ============================
Now point your browser to http://$AEGIR_DOMAIN/install.php and proceed Now point your browser to http://$AEGIR_DOMAIN/install.php and proceed with
with the remainder of the installation using the Hostmaster Install the remainder of the installation using the Hostmaster Install profile. Some
profile. Some of the instructions given, you will already have of the instructions given, you will already have completed, but carefully read
completed, but carefully read each step in turn to ensure you don't miss each step in turn to ensure you don't miss anything. Specifically you must
anything. Specifically you must still provide the database credentials, still provide the database credentials, add the Aegir user to /etc/sudoers
add the Aegir user to /etc/sudoers with the relevant command to restart with the relevant command to restart the webserver, create a MySQL superuser
the webserver, create a MySQL superuser capable of creating more databases, capable of creating more databases, and initialise the hosting system. These
and initialise the hosting system. These instructions are provided to you instructions are provided to you by the Hostmaster install profile.
by the Hostmaster install profile.
.. -*- mode: rst; fill-column: 78; -*-
.. This document is formatted using the ReST syntax. .. This document is formatted using the ReST syntax.
========================== ==========================
...@@ -11,8 +12,8 @@ This document describes briefly how to upgrade an existing Aegir installation ...@@ -11,8 +12,8 @@ This document describes briefly how to upgrade an existing Aegir installation
Conventions and tips Conventions and tips
==================== ====================
All instructions and in general all commands must be run as aegir user, All instructions and in general all commands must be run as aegir user, so all
so all permissions are always set correctly. permissions are always set correctly.
To become aegir user you can issue this command:: To become aegir user you can issue this command::
...@@ -20,11 +21,11 @@ To become aegir user you can issue this command:: ...@@ -20,11 +21,11 @@ To become aegir user you can issue this command::
(Note you must run this as root or prefix with sudo). (Note you must run this as root or prefix with sudo).
Note that /bin/sh is an example. You may wish to instead use the shell Note that /bin/sh is an example. You may wish to instead use the shell of your
of your choice, i.e /bin/bash choice, i.e /bin/bash
Additionally to make following instructions generic and not dependant on Additionally to make following instructions generic and not dependant on a
a concrete Drupal or Aegir version, we will use shell environment concrete Drupal or Aegir version, we will use shell environment
variables. Since 0.4, the hostmaster platform is prepended with 'hostmaster' variables. Since 0.4, the hostmaster platform is prepended with 'hostmaster'
so as not to clash with any other Drupal platforms. If you are upgrading from so as not to clash with any other Drupal platforms. If you are upgrading from
Aegir version 0.3, your hostmaster platform may be called 'drupal-6.14'. Aegir version 0.3, your hostmaster platform may be called 'drupal-6.14'.
...@@ -47,17 +48,17 @@ Shell commands:: ...@@ -47,17 +48,17 @@ Shell commands::
export DRUSH='php /var/aegir/drush/drush.php' export DRUSH='php /var/aegir/drush/drush.php'
As of the 0.4-alpha3 release, 'unzip' is a required dependency on your As of the 0.4-alpha3 release, 'unzip' is a required dependency on your server
server in order to successfully extract the jquery.ui library that is in order to successfully extract the jquery.ui library that is part of some UI
part of some UI improvements. On Debian, this means: improvements. On Debian, this means:
Shell commands:: Shell commands::
apt-get install unzip apt-get install unzip
If you intend on upgrading your system to the bleeding edge version of the If you intend on upgrading your system to the bleeding edge version of the
code from our git repositories, you will need the git program installed. code from our git repositories, you will need the git program installed. On
On Debian, this means: Debian, this means:
Shell commands:: Shell commands::
...@@ -66,31 +67,31 @@ Shell commands:: ...@@ -66,31 +67,31 @@ Shell commands::
Generic upgrade instructions Generic upgrade instructions
============================ ============================
We aim to create a generic upgrade process that will be consistent We aim to create a generic upgrade process that will be consistent across
across versions. This section describes this process. However, there versions. This section describes this process. However, there are
are version-specific upgrade instructions that may be more relevant to version-specific upgrade instructions that may be more relevant to your
your installation in the next section. installation in the next section.
Upgrading the backend Upgrading the backend
--------------------- ---------------------
In general, we try to keep the backend and the frontend compatible In general, we try to keep the backend and the frontend compatible with each
with each other during release cycles. That is: provision 0.3 and other during release cycles. That is: provision 0.3 and hosting 0.3 will
hosting 0.3 will always be able to talk to each other. hosting 0.2 was always be able to talk to each other. hosting 0.2 was able to talk to
able to talk to provision 0.3 too, but the API is not well enough provision 0.3 too, but the API is not well enough defined so that can be
defined so that can be counted upon. counted upon.
Therefore, you want to keep the frontend and the backend in sync. When Therefore, you want to keep the frontend and the backend in sync. When you do
you do a major upgrade (e.g. 0.3 -> 0.4) of the backend, you *must* a major upgrade (e.g. 0.3 -> 0.4) of the backend, you *must* upgrade the
upgrade the frontend soon after. frontend soon after.
Bottomline: first you upgrade the backend, then the frontend. Bottomline: first you upgrade the backend, then the frontend.
Upgrading the backend is as simple as installing a new version of Upgrading the backend is as simple as installing a new version of Drush and
Drush and Provision over the old ones. Provision over the old ones.
Keep a copy of the old Provision and Drush in case something goes wrong Keep a copy of the old Provision and Drush in case something goes wrong in the
in the frontend. frontend.
Shell commands:: Shell commands::
...@@ -105,9 +106,9 @@ Shell commands:: ...@@ -105,9 +106,9 @@ Shell commands::
gunzip -c provision-$AEGIR_VERSION.tgz | tar -xf - gunzip -c provision-$AEGIR_VERSION.tgz | tar -xf -
rm provision-$AEGIR_VERSION.tgz rm provision-$AEGIR_VERSION.tgz
Provision 0.4 has added a new dependency on drush_make, which will also Provision 0.4 has added a new dependency on drush_make, which will also need
need to be installed to upgrade the front end if you are upgrading from to be installed to upgrade the front end if you are upgrading from a pre-0.4
a pre-0.4 release. release.
If you are upgrading from an earlier 0.4 release, replace your copy of If you are upgrading from an earlier 0.4 release, replace your copy of
drush_make with the latest recommended release. drush_make with the latest recommended release.
...@@ -119,13 +120,13 @@ Shell commands:: ...@@ -119,13 +120,13 @@ Shell commands::
Upgrading the frontend Upgrading the frontend
---------------------- ----------------------
These are generic instructions to upgrade your hosting, hostmaster, These are generic instructions to upgrade your hosting, hostmaster, eldir or
eldir or Drupal core installation to new versions. As of 0.4 this process Drupal core installation to new versions. As of 0.4 this process has largely
has largely been automated, and will be able to upgrade 0.3 and any of been automated, and will be able to upgrade 0.3 and any of the 0.4 development
the 0.4 development releases to the latest applicable versions. releases to the latest applicable versions.