Difference between revisions of "Community/Community resources/Documentation"

Latest revision as of 12:23, 5 November 2020

Main Page > Community > Community/Community resources > Community/Community resources/Documentation

This page includes examples of community generated documentation - style guides, install instructions, institutional descriptive policies for AtoM use, User guide translations, and more. Have a resource to add, or one that you know about which is publicly available? Please help us by adding it!

Configuring AtoM uploads to be stored on a different server

Prepared by Mario Villar Corbo and shared via the AtoM User Forum on 2020-11-05, these instructions document how to configure a separate network-attached storage (NAS) server to be AtoM's default storage location for digital objects saved to the uploads directory. This should work with most AtoM 2.x instances (shared at the time of AtoM 2.6), as AtoM's digital object storage has not changed significantly since Release 2.0. This solution was tested on Ubuntu 18.04 by Mario.

From Mario:

By default, AtoM saves the digital objects that we upload in the server's own storage unit where it is hosted, in the "uploads" directory. Sooner or later when we handle audio files as is my personal case, the disk capacity will fill up.

While there is the option of CSV importing digital objects pointing to an external path, or linking to an external server, many users are more comfortable using the built-in GUI. In order to get the digital objects to be stored on an external network drive, in my case a NAS, I followed the following steps that I share with you in case someone finds it useful:

1 - Mount network drive via "mount" command, for example in /media /SHARED. It could be done using SMB or CIFS protocol. First we must install the packages; it's up to you to select which you want to use:

apt-get install smbfs smbclient

or

apt-get install cifs-utils

Then

apt-get update

Now, we check connection and shares of the external server:

smbclient -L IPOFEXTERNALSERVER -U USERNAME

It should display the network shares available on the server. According to the protocol enabled on external server, we mount the unit. If using SMB:

mount -t smbfs -o username=YOURUSERNAME //IPOFEXTERNALSERVER/SHARE_NAME /MOUNT_POINT -o OPTIONS

If using CIFS (recommended):

mount -t cifs //IPOFEXTERNALSERVER /MOUNT_POINT -o OPTIONS

2 - Add to / etc / fstab:

//IPOFEXTERNALSERVER / media / SHARED cifs uid = 33, username = (YOURUSERNAME), vers = 1.0, password = (YOURPASSWORD), sec = ntlm, iocharset = utf8, gid = 33 0 0

I'm using v 1.0 of cifs to maximize compatibility with older NAS boxes, as my case. For newer boxes, you can use 3.0.

3 - Rename the "uploads" folder within the AtoM working directory to "uploads_old" for example.

4 - Create a symbolic link called "uploads" that points to where we mount the network drive.

5 - Give 755 permissions to the destination network drive, and change the owner of it to www-data (33), as well as the group. Do it recursively.

6 - Mount network drive via mount command, for example in / media / SHARED.

7 - Add to / etc / fstab:

//IPOFEXTERNALSERVER/SHARENAME / media / SHARED cifs uid = 33, username = USERNAME, vers = 1.0, password = YOURPASSWORD, sec = ntlm, iocharset = utf8, gid = 33 0 0

8 - Rename the "uploads" folder within the AtoM working directory to "uploads_old" for example.

9 - Create a symbolic link called "uploads" that points to where we mount the network drive.

10 - Regenerate the derivatives of digital objects.

Tested on Ubuntu 18.04. It is recommended for ease of use using Webmin, going to the part of "Disk And Network Filesystem" in the "System" section. In my particular case the type of mount point corresponds to the CIFS protocol. We can also use Webmin to select which type of protocol or filesystem we prefer.

AtoM 2.5.4 startup ePub guide in Japanese

Prepared by Horiuchi Noboyuki of the National Institute of Japanese Literature at Tokyo and incorporating information from the Irisawa Dojo blog, this guide includes information on how to install AtoM in an Ubuntu VM using Virtualbox, basic AtoM usage, data preparation for import, and more. Below is a high-level summary of the content:

Chapter I: Installation

• How to download/install Virtualbox
• How to install Ubuntu in a Virtualbox VM
• How to install AtoM and its dependencies in the Ubuntu VM
• Initial AtoM configuration

Chapter II: Usage

• How to change AtoM UI language to Japanese
• How to restart AtoM
• How to edit pages
• How to import CSV files (from the web UI, and from command line)
• How to configure Japanese search support in AtoM using the Elasticsearch plugin "kuromoji"

Chapter III: Data preparation for import

• Extracting data from a PDF (using Adobe Acrobat OCR)
• Using MS Excel to arrange the data and export a CSV

Closing remarks

• Disclaimers and acknowledgements

Currently the guide is available via Amazon, and the money will go to supporting the author and fellow researchers at National Institute of Japanese Literature at Tokyo, Japan.

Running and Integrating AtoM and Archivematica test instances with Vagrant

These instructions, prepared by community user Grant Hurley on March 31, 2020, walk users through how to install both AtoM and Archivematica test instances on a local computer using Vagrant, and configuring them to be able to pass DIPs from Archivematica to AtoM. At the time these instructions were written, they use Archivematica 1.10 and AtoM 2.6, with instructions included on how to downgrade AtoM to version 2.5.3 if desired.

From Grant's blog post:

One thing I’ve been trying to do for a while is get the Archivematica and AtoM Vagrant boxes to integrate around the DIP deposit feature so I can better understand the workflow between the two. The setup instructions that follow are specific to this: they will take you through the process of getting both VMs running at once, and then on how to integrate the two for the Archivematica to AtoM workflow. If you are thinking of setting up and connecting both applications at your workplace, doing so here should give you a good sense of how to connect the two in production, though of course with the difference of your own appropriate production deployment settings since Vagrant isn’t suitable for production use.

Read the full blog post here: http://www.granthurley.ca/blog/running-and-integrating-archivematica-and-atom-with-vagrant/

Instructions for installing AtoM using RedHat or CentOS

Currently, the AtoM project only maintains official documentation for installation using Ubuntu LTS releases. However, it is possible for AtoM to be installed on other operating systems, including other linux flavors. Over the life of the AtoM project, several community users - as well as Artefactual team members - have prepared guides for installing AtoM on CentOS and/or RedHat Enterprise Linux (RHEL). Below are some of the guides that have been publicly shared.

AtoM 2.5 CentOS 8 installation guide

Prepared by community user J Grant Forrest in January 2020, this guide covers "How to build a server for AtoM 2.5 on CentOS 8.x with PHP 7.2, Elasticsearch 5.6, Apache 2.4.x, MariaDB 10.x and PHP handler = PHP-FPM."

You can find the instructions here:

• https://www.grantforrest.me.uk/index.php/guides/12-how-to-install-atom-2-5-x-on-centos-8
• See also: the AtoM user forum thread where this link was originally shared - https://groups.google.com/d/msg/ica-atom-users/ZcQZB9b8xg0/KMuXmanbAgAJ

AtoM 2.4/2.5 CentOS/RHEL 7.5 installation guide

Prepared by Santiago Rodríguez Collazo (Production Support Engineer with Artefactual Systems) in May of 2019, this gist includes instructions for installing either AtoM 2.4 or 2.5 using CentOS / RHEL version 7.5. Artefactual has previously successfully used these instructions in client production deployments.

You can find the gist with the instructions here:

• https://gist.github.com/scollazo/7a13dbea3ea88f8d7463befa4e996d0d

AtoM 2.2 CentOS/RHEL 7.1 installation guide

Prepared by community user Stefano Bortolato in September 2015, this guide offers instructions for installing and configuring AtoM (release 2.2) using either CentOS or RedHat 7.1 as the default server, instead of Ubuntu 14.04, as the default installation instructions outline (found here for 2.2). It also uses Apache server instead of Nginx, and MariaDB instead of MySQL.

Stefano has posted the instructions in the AtoM user forum, here, in both PDF and ODT formats:

• https://groups.google.com/d/msg/ica-atom-users/lXfeWzAIETE/9-fTTArvAwAJ

AtoM 2.0 CentOS 6.5 VirtualBox installation guide

Prepared by community user Ivan Rivera in August 2014, this guide walks through the process of installing AtoM 2.0 using CentOS 6.5 as the operating system, in a VirtualBox virtual appliance. Originally shared in this AtoM User Forum thread - if you find any problems, or have any suggestions for improvement, we suggest posting them there!

You can find a publicly accessible Google Doc with the instructions here:

• https://docs.google.com/document/d/1hjaFgINPWKhUYNtWrRHcxySiDsEBejTUGMfckjkStI4/edit

SFU AtoM - Data entry guidelines

At Simon Fraser University, the SFU Archives and SFU Library's Special Collections and Rare Books share an AtoM instance known as SFU AtoM, using AtoM's multi-institutional functionality. The archivists have created a comprehensive data entry guide for project archivists, students, and volunteers working in SFU AtoM:

• SFU AtoM: Data entry guidelines

Archeion for Archivists data entry guidelines

Archeion is the Ontario (Canada) provincial archival portal maintained by the Archives Association of Ontario (AAO), with archival descriptions contributed by over 170 different institutions in Ontario. To assist participating institutions, the AAO has created some data entry documentation, in English and French, entitled Archeion for Archivists, and covering topics such as how to create authority records, archival descriptions, and repository records in AtoM. See the guides here:

• Archeion for Archivists (English)
• Archeion pour archivistes (French)

AtoM RAD CSV notes

Created by community user Katrina Cohen-Palacios, these notes were compiled from the documentation as a cheat sheet while embarking on my first CSV imports and exports. The notes as kept in a publicly-viewable Google spreadsheet.

• http://bit.ly/AtoMCSV

ICA-AtoM User Manual in Spanish, from Vidimus

Created by Blanca Biarge Gallardo for Vidimus, a Barcelona-based company specializing in archival and document management services, this User Manual was first created in 2012, and then updated to its current version 2 status in April of 2014. Instructions are based on ICA-AtoM release 1.3.

• https://issuu.com/rodrigoalvarezportugal/docs/ica_atom_manual_v02

Intstalling ICA-AtoM using XAMPP

Created by Lucía Fernández Granados, this Spanish-language guide outlines how to install ICA-AtoM (1.x) using XAMPP for a Windows-based virtual installation. Created as part of a 2013/2014 course, the guide can be found here:

• https://www.academia.edu/12759023/Software_para_archivos_C%C3%B3mo_instalar_ICA-_atom_en_modo_local

ICA-AtoM Finding Aid Style Guide and AtoM FAQ - Dumbarton Oaks

In June 2014, The Image Collections and Fieldwork Archives (ICFA) of Dumbarton Oaks Research Library and Collection announced the release of its AtoM Finding Aid Style Guide. "Developed by ICFA staff to document local practices for internal reference and training, the Guide addresses all aspects of description: from collection-level details such as creation and acquisition information to providing file-specific storage locations. In addition, there are sections on developing an intellectual arrangement and devising titles for each record group in a collection."

The landing page also notes: "In advance of the department’s conversion of their legacy finding aids, ICFA staff also produced a workflow to help guide staff to the system. The Workflow provides step-by-step instructions on how to develop new collections in ICA-AtoM based on existing Word finding aids, and is intended to be used in conjunction with the Guide, a more comprehensive reference resource for description." The Workflow is available upon request (icfa@doaks.org).

Dumbarton Oaks also maintains an online FAQ about using AtoM@DO, the AtoM installation used by the Image Collections and Fieldwork Archives (ICFA) and the Dumbarton Oaks Archives (DOA).

• See the Finding Aid Style Guide landing page
  • Direct link to the Finding Aid style guide (PDF)
• AtoM@DO FAQ

Upgrading from ICA-AtoM 1.0.x

Artefactual developer José Raddaoui Marin created this documentation for users upgrading from ICA-AtoM 1.0.x to AtoM 2.x. If you are upgrading from AtoM 1.1.x or newer, please see the Upgrading page in the documentation. The guide for upgrading from ICA-AtoM 1.0.x can be found here:

• Upgrading from ICA-AtoM 1.0.x

AtoM documentation in Brazilian Portuguese

Produced via a collaboration between the Comissão Nacional da Verdade (CNV - National Truth Commission) and the Instituto Brasileiro de Informação em Ciência e Tecnologia (IBICT - Brazilian Institute of Information in Science and Technology) and with support from the Brazilian Arquivo Nacional (National Archives), this manual captures both the User manual and the Administrator's manual for installation and maintenance of AtoM. Based on version 2.2.

• http://livroaberto.ibict.br/handle/123456789/1065

There is also a previous version of the ICA-AtoM (v. 1.2) User Manual available. Prepared by Neiva Pavezi of the Federal University of Santa Maria (Universidad Federal de Santa Maria), this guide translates the 1.2 version of the ICA-AtoM online User Guide into Brazilian Portuguese. It was prepared in 2013.

• File:ICA-AtoM-Manual-v1.2-pt BR.pdf

AtoM 2.3 Installation instructions for Ubuntu 16.04 in Brazilian Portuguese

With translation work overseen by Sérgio Rodrigues, member of a Digital Documents group based at the Federal University of Santa Maria (UFSM), this document translates the AtoM 2.3 installation guide into Brazilian Portuguese:

• https://docs.google.com/document/d/1mMyAqcsBwbORC2AvNWEPutmZyHOQW4yWh0vme3KsZqk/pub#ftnt1

• Back to the Community resources index
• Back to the Main Page of the AtoM wiki