Linux - Ubuntu 20.04 LTS (Focal Fossa)¶

MySQL¶

AtoM 2.8 requires MySQL 8.0 or higher as it uses common table expressions. Also, we’ve experienced very good results using Percona Server for MySQL 8.0, so don’t be afraid and use it if you want!

sudo apt update
sudo apt install mysql-server

sudo mysql_secure_installation

Finally, let’s configure our MySQL modes. The MySQL server can operate in different SQL modes, which affects the SQL syntax MySQL supports and the data validation checks it performs.

Paste the following values in a new file at /etc/mysql/conf.d/mysqld.cnf and save:

[mysqld]
sql_mode=ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
optimizer_switch='block_nested_loop=off'

Now we’ll restart MySQL:

sudo systemctl restart mysql

Elasticsearch¶

A 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.

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-11-jre-headless apt-transport-https software-properties-common

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

wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -

Now add their repository:

echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list

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

PHP¶

Ubuntu 20.04 bundles PHP 7.4, which is much faster than older releases. The following command will install it along with the rest of PHP extensions required by AtoM:

sudo apt install php-common php7.4-common php7.4-cli php7.4-curl php7.4-json php7.4-ldap php7.4-mysql php7.4-opcache php7.4-readline php7.4-xml php7.4-mbstring php7.4-xsl php7.4-zip php-apcu php-apcu-bc

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

sudo apt install php-memcache

Gearman job server¶

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

sudo apt install gearman-job-server

Other packages¶

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

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

Make sure the default java command points to the java version 11 binary (ignore errors):

sudo update-java-alternatives -s java-1.11.0-openjdk-amd64

sudo update-java-alternatives -l
sudo update-alternatives --get-selections | grep 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.8.0.tar.gz
sudo mkdir /usr/share/nginx/atom
sudo tar xzf atom-2.8.0.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 -p /usr/share/nginx/atom
sudo git clone -b stable/2.8.x http://github.com/artefactual/atom.git /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 -b stable/2.8.x --depth 1 http://github.com/artefactual/atom.git /usr/share/nginx/atom

We use Composer to install and manage some third-party PHP libraries. To install Composer download and run the Composer installer according to the instructions at https://getcomposer.org/download/ in the “Command-line installation” section.

Once Composer is installed you will need to run it to install the required libraries. First, move to the AtoM folder:

cd /usr/share/nginx/atom

For production sites, the development libraries do not need to be included:

sudo ~/composer.phar install --no-dev

Or if you have installed Composer globally:

sudo composer install --no-dev

For development environments, the dev libraries should also be installed:

sudo ~/composer.phar install

After downloading the code, you will need to compile the themes files:

sudo npm install
sudo npm run build

sudo apt install npm make
sudo npm install -g "less@<4.0.0" n
sudo n stable
sudo npm install
sudo npm run build
sudo make -C /usr/share/nginx/atom/plugins/arDominionPlugin
sudo make -C /usr/share/nginx/atom/plugins/arArchivesCanadaPlugin
sudo rm -rf node_modules

Filesystem permissions¶

By default, Nginx runs as the www-data user. There are a few directories under AtoM that must be writable by the web server. The easiest way to ensure this is to update the owner of the AtoM directory and its contents by running:

sudo chown -R www-data:www-data /usr/share/nginx/atom

If you are deploying AtoM in a shared environment we recommend you to pay attention to the permissions assigned to others. The following is an example on how to clear all mode bits for others:

sudo chmod o= /usr/share/nginx/atom

If you are planning to do DIP uploads from AM, check the SWORD deposit directory section to set the permissions of that directory.

Deployment of workers¶

Gearman is used in AtoM to support asynchronous tasks, some of which are core functionality such as updating the publication status of a descriptive hierarchy, moving descriptions to a new parent record, and much more. A worker is just a CLI task that you can run in a terminal or supervise with specific tools like upstart, supervisord or systemd. The worker will wait for jobs that are assigned by the job server.

We will use systemd to manage the AtoM worker; create the following service file /usr/lib/systemd/system/atom-worker.service:

[Unit]
Description=AtoM worker
After=network.target
# High interval and low restart limit to increase the possibility
# of hitting the rate limits in long running recurrent jobs.
StartLimitIntervalSec=24h
StartLimitBurst=3

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/usr/share/nginx/atom
ExecStart=/usr/bin/php7.4 -d memory_limit=-1 -d error_reporting="E_ALL" symfony jobs:worker
KillSignal=SIGTERM
Restart=on-failure
RestartSec=30

Now reload systemd, enable and start the AtoM worker:

sudo systemctl daemon-reload
sudo systemctl enable atom-worker
sudo systemctl start atom-worker

Check out the following page for more information about asynchronous jobs and worker management: Asynchronous jobs and worker management.

PHP-FPM¶

Our favorite way to deploy AtoM is using PHP-FPM, a process manager that scales better than other solutions like FastCGI.

sudo apt install php7.4-fpm

Let’s add a new PHP pool for AtoM by adding the following contents in a new file called /etc/php/7.4/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.4-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 started:

sudo systemctl enable php7.4-fpm
sudo systemctl start php7.4-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.4 --test

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

sudo rm /etc/php/7.4/fpm/pool.d/www.conf
sudo systemctl restart php7.4-fpm

Nginx¶

In Ubuntu, the installation of Nginx is simple:

sudo apt 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-available/atom.

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

   location ~* ^/(css|dist|js|images|plugins|vendor)/.*\.(css|png|jpg|js|svg|ico|gif|pdf|woff|ttf)$ {

   }

   location ~* ^/(downloads)/.*\.(pdf|xml|html|csv|zip|rtf)$ {

   }

   location ~ ^/(ead.dtd|favicon.ico|robots.txt|sitemap.*)$ {

   }

   location / {
      try_files $uri /index.php?$args;
      if (-f $request_filename) {
         return 403;
      }
   }

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

}

Now you need to enable and reload Nginx:

sudo systemctl enable nginx
sudo systemctl reload nginx