Linux - Ubuntu 16.04 LTS (Xenial Xerus)¶

MySQL¶

We strongly recommend using MySQL 5.6 as it’s much better than the 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!

Ubuntu 16.04 does not include an installation candidate for MySQL 5.6 but we can use Percona Server 5.6 instead. Let’s install it with the following command:

sudo apt-get update
sudo apt install percona-server-server-5.6

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 somewhere safe, 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.x 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. In this example we are going to use OpenJDK but Oracle’s JVM would also work.

sudo apt install openjdk-8-jre-headless software-properties-common

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 -

Now add their repository:

sudo add-apt-repository "deb http://packages.elasticsearch.org/elasticsearch/1.7/debian stable main"

Ready to be installed. Run:

sudo apt update
sudo apt install elasticsearch

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

sudo systemctl enable elasticsearch
sudo systemctl start elasticsearch

Web server¶

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 merely on Nginx.

sudo apt install nginx

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

upstream atom {
  server unix:/run/php7.0-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;
  }

  location ~* /uploads/r/(.*)/conf/ {

  }

  location ~* ^/uploads/r/(.*)$ {
    include /etc/nginx/fastcgi_params;
    set $index /index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$index;
    fastcgi_param SCRIPT_NAME $index;
    fastcgi_pass atom;
  }

  location ~ ^/private/(.*)$ {
    internal;
    alias /usr/share/nginx/atom/$1;
  }

  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;
  }

}

sudo systemctl enable nginx
sudo systemctl reload nginx

PHP¶

Ubuntu 16.04 bundles PHP 7.0 which is much faster than older releases.

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 install php7.0-cli php7.0-curl php7.0-json php7.0-ldap php7.0-mysql php7.0-opcache php7.0-readline php7.0-xml php7.0-fpm php7.0-mbstring php7.0-mcrypt php7.0-xsl php7.0-zip php-apcu

If you are using Memcached as cache engine, you will also need to install php-memcache:

sudo apt-get install php-memcache

We also need php-apcu-bc, which is not available yet in Ubuntu 16.04. Let’s install it manually for now:

sudo apt install php-dev
sudo pecl install apcu_bc-beta
echo "extension=apc.so" | sudo tee /etc/php/7.0/mods-available/apcu-bc.ini
sudo ln -sf /etc/php/7.0/mods-available/apcu-bc.ini /etc/php/7.0/fpm/conf.d/30-apcu-bc.ini
sudo ln -sf /etc/php/7.0/mods-available/apcu-bc.ini /etc/php/7.0/cli/conf.d/30-apcu-bc.ini
sudo systemctl restart php7.0-fpm

Let’s add a new PHP pool for AtoM by adding the following contents in a new file called /etc/php/7.0/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 = /run/php7.0-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
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
php_admin_value[opcache.enable] = 1
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"

The process manager has to be enabled and restarted:

sudo systemctl enable php7.0-fpm
sudo systemctl start php7.0-fpm

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 php-fpm7.0 --test

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

sudo rm /etc/php/7.0/fpm/pool.d/www.conf
sudo systemctl restart php7.0-fpm

Gearman job server¶

Gearman job server is required by AtoM as of version 2.2.

sudo apt install gearman-job-server

We’ll configure the job server and the workers after initial installation (see below). Full configuration detalis can be found here:

• Asynchronous jobs and worker management.

Other packages¶

In order to generate PDF finding aids, AtoM requires Apache FOP 2.1 to be installed. Fortunately, Apache FOP 2.1 can now be installed directly from Ubuntu packages using the command below.

sudo apt install --no-install-recommends fop libsaxon-java

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 install imagemagick ghostscript poppler-utils ffmpeg

Option 1: Download the tarball¶

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

Please note that the tarball may not be available yet if this version is still in development. In this case, you can try the alternative installation method explained below.

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

Install git:

sudo apt install git

sudo mkdir /usr/share/nginx/atom
sudo git clone -b stable/2.4.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:

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt install nodejs make
sudo npm install -g "less@<2.0.0"
sudo make -C /usr/share/nginx/atom/plugins/arDominionPlugin