Linux¶

MySQL¶

We strongly recommend using MySQL 5.5 as it’s much better than its previous major release in terms of speed, scalability and user-friendliness. Also, we’ve experienced very good results using forks like Percona Server or MariaDB, so don’t be afraid and use them if you want!

Let’s install MySQL using apt-get:

sudo apt-get install mysql-server-5.5

During the installation, you will be prompted to set a password for the default administrator user (root). We strongly recommend that you use a strong password and please write it down as you are going to need it later.

Elasticsearch¶

A relatively new search server based on Apache Lucene and developed in Java that has brought AtoM a lot of advanced features, performance and scalability. This is probably the biggest change introduced in AtoM 2.1 and we are pleased with the results.

Ubuntu doesn’t provide a package but you can download it directly from the Elasticsearch site if you are unable to download it using the method that follows.

First, make sure that Java is installed. Elasticsearch is compatible with OpenJDK (package openjdk-7-jre-headless) but we are going to use Oracle’s JVM distributed by Web Upd8.

sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer

After successfully installing Java, proceed to install Elasticsearch. Download and install the public signing key used in their repository:

wget -qO - http://packages.elasticsearch.org/GPG-KEY-elasticsearch | sudo apt-key add -

Add the following to your /etc/apt/sources.list to enable the repository:

deb http://packages.elasticsearch.org/elasticsearch/1.3/debian stable main

Ready to be installed. Run:

sudo apt-get update
sudo apt-get install elasticsearch

Start the service and configure it to start when the system is booted.

sudo update-rc.d elasticsearch defaults 95 10
sudo /etc/init.d/elasticsearch start

Nginx¶

There are many web servers out there capable of working well with PHP. Apache is probably the most popular and we like it, but we’ve found that Nginx adapts itself much better to limited resource environments while it also scales better and more predictably under high loads. You are welcome to try other solutions, but the following documentation will focus upon Nginx, our preferred web server solution.

The installation in Ubuntu is simple:

sudo apt-get install nginx

Ubuntu 12.04 uses Nginx 1.1. However, the team behind Nginx provides an official PPA (Personal Package Archive) channel for Ubuntu users that supports more recent stable packages for the different releases of Ubuntu, including 12.04. This could be a good choice if you want to enjoy some of the latest features and improvements added to Nginx while taking minimal risks in your production environments. If you are interested, run the following commands:

sudo add-apt-repository ppa:nginx/stable
sudo apt-get update
sudo apt-get install nginx

Nginx deploys a default server (aka VirtualHost, for Apache users) called default and you can find it in /etc/nginx/sites-available/default. In order to install AtoM you could edit the existing server block or add a new one. We are going to you show you how to do the latter:

sudo touch /etc/nginx/sites-available/atom
sudo ln -sf /etc/nginx/sites-available/atom /etc/nginx/sites-enabled/atom
sudo rm /etc/nginx/sites-enabled/default

We have now created the configuration file and linked it from sites-enabled/, which is the directory that Nginx will look for. This means that you could disable a site by removing its symlink from sites-enabled/ while keeping the original one under sites-available/, in case that you want to re-use it in the future. You can do this with the Nginx default server.

The following is a recommended server block for AtoM. Put the following contents in /etc/nginx/sites-enabled/atom.

upstream atom {
  server unix:/var/run/php5-fpm.atom.sock;
}

server {

  listen 80;
  root /usr/share/nginx/atom;

  # http://wiki.nginx.org/HttpCoreModule#server_name
  # _ means catch any, but it's better if you replace this with your server
  # name, e.g. archives.foobar.com
  server_name _;

  client_max_body_size 72M;

  # http://wiki.nginx.org/HttpCoreModule#try_files
  location / {
    try_files $uri /index.php?$args;
  }

  location ~ /\. {
    deny all;
    return 404;
  }

  location ~* (\.yml|\.ini|\.tmpl)$ {
    deny all;
    return 404;
  }

  location ~* /(?:uploads|files)/.*\.php$ {
    deny all;
    return 404;
  }

  # This is the most important part, as here we are redirecting some specific
  # requests to PHP-FPM so PHP can do its job passing data to and from the
  # web server.
  location ~ ^/(index|qubit_dev)\.php(/|$) {
    include /etc/nginx/fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_split_path_info ^(.+\.php)(/.*)$;
    fastcgi_pass atom;
  }

  location ~* \.php$ {
    deny all;
    return 404;
  }

}

Now you need to restart Nginx:

sudo service nginx restart

PHP¶

Our favorite way to deploy AtoM is using PHP-FPM, a process manager that scales better than other solutions like FastCGI. The following command will install it along with the rest of PHP extensions required by AtoM:

sudo apt-get install php5-cli php5-fpm php5-curl php5-mysql php5-xsl php5-json php5-ldap php-apc

If you are using Ubuntu 14.04, the package php5-readline is also required.

sudo apt-get install php5-readline

Let’s add a new PHP pool for AtoM by adding the following contents in a new file called /etc/php5/fpm/pool.d/atom.conf:

[atom]

# The user running the application
user = www-data
group = www-data

# Use UNIX sockets if Nginx and PHP-FPM are running in the same machine
listen = /var/run/php5-fpm.atom.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0600

# The following directives should be tweaked based in your hardware resources
pm = dynamic
pm.max_children = 30
pm.start_servers = 10
pm.min_spare_servers = 10
pm.max_spare_servers = 10
pm.max_requests = 200

chdir = /

# Some defaults for your PHP production environment
# A full list here: http://www.php.net/manual/en/ini.list.php
php_admin_value[expose_php] = off
php_admin_value[allow_url_fopen] = on
php_admin_value[memory_limit] = 512M
php_admin_value[max_execution_time] = 120
php_admin_value[post_max_size] = 72M
php_admin_value[upload_max_filesize] = 64M
php_admin_value[max_file_uploads] = 10
php_admin_value[cgi.fix_pathinfo] = 0
php_admin_value[display_errors] = off
php_admin_value[display_startup_errors] = off
php_admin_value[html_errors] = off
php_admin_value[session.use_only_cookies] = 0

# APC, which is still used in PHP 5.5 for userland memory cache unless you
# are switching to something like sfMemcacheCache
php_admin_value[apc.enabled] = 1
php_admin_value[apc.shm_size] = 64M
php_admin_value[apc.num_files_hint] = 5000
php_admin_value[apc.stat] = 0

# Zend OPcache
# Only in Ubuntu 14.04 (PHP 5.5).
# Don't use this in Ubuntu 12.04, it won't work.
php_admin_value[opcache.enable] = 1
php_admin_value[opcache.enable_cli] = 0
php_admin_value[opcache.memory_consumption] = 192
php_admin_value[opcache.interned_strings_buffer] = 16
php_admin_value[opcache.max_accelerated_files] = 4000
php_admin_value[opcache.validate_timestamps] = 0
php_admin_value[opcache.fast_shutdown] = 1

# This is a good place to define some environment variables, e.g. use
# ATOM_DEBUG_IP to define a list of IP addresses with full access to the
# debug frontend or ATOM_READ_ONLY if you want AtoM to prevent
# authenticated users
env[ATOM_DEBUG_IP] = "10.10.10.10,127.0.0.1"
env[ATOM_READ_ONLY] = "off"

Note that the section “Zend OPcache” won’t work in Ubuntu 12.04. Comment it out or remove it unless you are using Ubuntu 14.04.

The process manager has to be restarted:

sudo service php5-fpm restart

If the service fails to start, make sure that the configuration file has been has been pasted properly. You can also check the syntax by running:

sudo php5-fpm --test

If you are not planning to use the default PHP pool (www), feel free to remove it:

sudo rm /etc/php5/fpm/pool.d/www.conf
sudo service php5-fpm restart

Other packages¶

If you want AtoM to be able to process digital objects in formats like JPEG or to extract the text from your PDF documents, there are certain packages that you need to install. They are not mandatory but if they are found in the system, AtoM will use them to produce digital object derivatives from your master objects. for more information on each, see: Requirements: other dependencies. The following will install all the recommended dependencies at once:

sudo apt-get install imagemagick ghostscript poppler-utils

Install ffmpeg from Archivematica’s PPA, which works for both Ubuntu 12.04 (precise) and Ubuntu 14.04 (trusty).

sudo add-apt-repository ppa:archivematica/externals
sudo apt-get update
sudo apt-get install ffmpeg

Option 1: Download the tarball¶

wget https://storage.accesstomemory.org/releases/atom-2.1.2.tar.gz
sudo mkdir /usr/share/nginx/atom
sudo tar xzf atom-2.1.2.tar.gz -C /usr/share/nginx/atom --strip 1

Option 2: Check out the code from our git repository¶

Install git:

sudo apt-get install git

sudo mkdir /usr/share/nginx/atom
sudo git clone -b stable/2.1.x http://github.com/artefactual/atom.git /usr/share/nginx/atom
cd /usr/share/nginx/atom

If you are not interested in downloading all the history from git, you could also truncate it to a specific number of revisions, e.g.: just one revision

git clone --depth 1 http://github.com/artefactual/atom.git /usr/share/nginx/atom

Once you’ve cloned the code from our git repository, you’ll need to compile the CSS files:

sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs make
sudo npm install -g "less@<2.0.0"
cd /usr/share/nginx/atom/plugins/arDominionPlugin/
sudo make # At this point the files still belong to root