Open Atrium is a rich distribution of many (150+) Drupal modules. Installing
Open Atrium may require additional resources beyond a minimal Drupal 7
installation.
System Requirements
In addition to the normal Drupal 7 requirements, you should ensure your PHP
memory_limit (php.ini) is set to at least 256M and your MySQL
max_allowed_packet (my.cnf) is at least 32M.
On a production Open Atrium site, keep in mind that the nature of
collaboration software implies many logged-in users. Caching layers, such
as Varnish, that are typically used to improve Drupal performance will be
less effective because authenticated users bypass these caching layers.
Thus, a production environment may require additional database memory and
resources to handle larger numbers of users. Using a hosting company
specifically tailored for Open Atrium can also help. You should not expect
to run Open Atrium effectively on minimal (cheap) shared VM hosts.
Please also see Additional OpenAtrium requirements when installing under Aegir.
One-click installation
Hosting companies, such as Pantheon provide an optimized infrastructure for
Open Atrium and offer a 1-click installation process. When using Pantheon,
skip down to the "Actual Installation" section for details.
Getting the Open Atrium files
Before you can install Open Atrium, you need to get the files. There are two
different methods for this:
** Using Releases from Drupal.org (recommended)
Official releases of Open Atrium are available on the drupal.org project page.
Click the link for the "gz" or "zip" archive of files for the latest release.
Older releases are also available, though not recommended. Once you have
downloaded this file, use your systems unarchive or unzip software to extract
all the files from the archive. These files form the "root" or top-level of
your web site, so transfer them to the appropriate top level location of your
web server. This will replace any existing Drupal or other web site that you
have, so if you are overwriting existing files, be sure to make a BACKUP first!
** Using "git" and "drush make" for the latest -dev version (for expert Drupal devs)
(NOTE: These instructions are for *nix-based systems, such as Linux or MacOSX.
Windows users will need to research how to use these tools on their system).
If you require the absolute latest development version of Open Atrium, you need
to be familiar with the "git" and "drush" tools:
-
From a command line shell, run
"git clone --branch 7.x-2.x http://git.drupal.org/project/openatrium.git"
to download the latest version of Open Atrium to the "openatrium" folder
on your computer.
-
Move to that folder using "cd opentrium"
-
Download and build the files for Open Atrium using the script
"./build.sh path-to-web-server". For example, if the root of your webserver
is in /htdocs/drupal, then you would use "./build.sh /htdocs/drupal".
This will build OA2 using the latest -dev files from drupal.org. For the
absolute latest code, you can get the development code from drupal by
running "./build-dev.sh path-to-web-server" instead. This script requires
the "drush" command and uses "drush make" to download and build all of the
dependencies for Open Atrium 2. You should be using at least Drush 5.x.
-
If you receive the following error message when you attempt to build the
the files, you will need to install the Drupal.org Drush commands.
"The drush command 'verify-makefile' could not be found. Run drush
cache-clear drush to clear the commandfile cache if you have installed
new extensions."
Updating your Open Atrium distribution
In the future when you wish to update to a newer version of Open Atrium, you
have two choices, based on how you originally obtained the files as described
in the previous section.
IMPORTANT NOTE: Before performing any site updates, it is extremely important
to BACKUP your Drupal files and MySQL database for your site. Updating Open
Atrium can cause irreversible changes to the database and if you decide to
roll back you'll need this backup.
** Updating files from drupal.org (recommended)
Save a copy of your Drupal sites/ directory. This contains any local code or
customization you might have made to your site. Now run the same procedure
shown above to download the latest version of Open Atrium from drupal.org and
replace your entire root web directory with the new version. Finally, replace
the copy of the sites/ directory that you previously saved. Follow the
instructions in the "Clearing Cache" section below to update your database and
your site should be updates.
** Updating the latest -dev version (for expert Drupal devs)
If you built your site using "git" and "drush" then you can use these same
tools to update your site. First, save a copy of your Drupal sites/ directory
as this will be overwritten by the update process. Next, go to the "openatrium"
folder where you initially used "git" to fetch the Open Atrium repository. Use
"git pull" to retrieve the latest version of the distribution. Then run the
./build.sh or ./build-dev.sh script exactly as before. Instead of pointing
these scripts to your root web directory, you can point them to a temp
directory in case the installation fails. The build.sh scripts delete
everything in the target directory so building to a temp directory prevents
your current web site from being lost if the build fails. Once the build is
successful you can move the temporary directory in place of your web root,
then restore the /sites directory that you previously saved.
If you just need to make a quick update of a specific open atrium module, you
can also just go to that module directory and use "git pull origin" to pull
in the latest changes without rebuilding the entire distribution.
Do NOT update Drupal core or any modules within Open Atrium 2 manually unless
you are an expert Drupal developer who knows exactly what you are doing.
Drupal Distributions such as Open Atrium are a complex collection of many
modules, often with specific patches to make them work together. If you update
a module manually you can easily break your Open Atrium site. The Open Atrium
distribution is regularly updated with security patches and new features and
is constantly evaluating new versions of modules. The advantage of using a
distribution is to let other people handle the headache of updating modules
and keeping them all working together.
Clearing Cache
If you are installing for the first time, ignore this section. If you are
updating your Open Atrium distribution you'll need to run a couple of commands
to clear the drupal cache and update your database:
drush updb
This is the same as running the update.php script on your site and is
needed to run any update hooks required for the new version.
drush rr
This is an OPTIONAL command but is sometimes needed if modules or files
have moved to a different directory location within Open Atrium. If you
get weird errors when clearing cache after an update, try this command.
It is a shortcut for the "registry rebuild" command which might need to
be installed into drush separately.
drush cc all
This clears the Drupal database cache and is the same as clicking "Clear
All Caches" from the admin/config/development/performance page on your
site. This drush command lets you clear cache from the command line more
quickly.
drush fra -y (Read notes first)
This command is required to update all of Open Atrium's features to the
latest version. Running it will revert and overwrite any existing
features, including any changes that you may have made to Open Atrium's
configuration. It is therefore very important to capture any customization
using the Features Override module before running this command. This
command can be run at any other time to restore Open Atrium's features to
their default settings (Eg: if someone has inadvertently tampered with any
Views or layouts within Open Atrium).
Actual Installation
To install Open Atrium the first time, you will run the "install.php" script
from your web browser. NOTE when using a hosting company such as Pantheon, it
will run install.php for you. The Install script will take you through
multiple pages of steps. There is very little difference between this process
and a normal Drupal site installation except that it takes longer to install
the large number of modules.
If you are a Maintainer of Open Atrium, you should copy the gitignore.example
file to .git/info/exclude to avoid adding extra files to the repository.
The most common problem encountered during installation is the lack of system
resources on your web server. Be sure to follow the instructions in the System
Requirements section shown above. If you still have trouble, try doing a plain
Drupal 7 installation using the links in the previous section to ensure that
your host is capable of installing Drupal itself.
