Install a new Digital Archive site

This page explains all of the tasks that AvantLogic performs to install and configure a new Digital Archive installation. For each task, it lists the steps necessary to perform the task.

Step by step

Installation tasks appear in the navigation panel at left. Perform them one at a time in the order listed.

Print an installation checklist


Prerequisites


Hosting requirements

The web host must be an Apache web server that satisfies the system requirements for Omeka Classic. AvantLogic uses InMotion Hosting as its host.

These instructions assume that the host has cPanel. If you don't have cPanel, see Installing on a bare Linux server.

Site name

Some of the installation steps require that you specify a site name. Choose a concise and meaningful name that you and others will recognize when performing system administration. An acronym is usually a good choice. For example, the site name for the Southwest Harbor Public Library is swhpl.

Site folder

The files for a Digital Archive installation reside in what this documentation refers to as the site folder. The location of the folder varies depending on whether the installation is standalone (has its own cPanel account on the server) or is a subdomain installation (shares the same cPanel account as other installations).

Standalone installation folder

On a standalone installation, the Digital Archive files will be installed in /public_html/digitalarchive. AvantLogic uses the digitalarchive folder to isolate the Digital Archive files from other applications on the web server. For example, some installations use a digitalarchive folder and a wp folder side-by-side where the wp folder contains a WordPress application for content related to the Digital Archive collection. If would be very messy, and make application updates difficult, if the Digital Archive and WordPress files were together in the same public_html.

Do not create the digitalarchive folder at this time.
It will get created later during the Install Omeka Classic files step.

Subdomain installation folder

On a subdomain installation, the Digital Archive files will be installed in /domains/site-name for a subdomain e.g. demo.digitalarchive.us. Create the subdomain now before continuing.

  • Go to cPanel for digitalarchive.us
  • Use the File Manager tool to create a new subfolder in the domains folder e.g. /domains/demo
  • Choose the Domains tool
  • Click the Create a New Domain button
  • Enter the domain name e.g. demo.digitalarchive.us
  • Enter the document root e.g. /domains/demo
  • Leave the share document root option unchecked
  • Click the Submit button

MySQL database

Follow the steps below to use cPanel to create a new empty database and a database user for the Digital Archive installation.

Standalone installation

Create a database

Important

cPanel will automatically prefix any database or user name that you choose with the first seven letters of the domain name, followed by _. For example, if you specify the name omeka and the domain name is swhpl the actual name will be shwpl_omeka. Keep this in mind because the name you choose will really be a suffix.

  • In WHM, select the account where the installation will be performed
  • Go to cPanel and choose MySQL Database Wizard
  • In wizard Step 1 Create a Database:
    • Decide on the database name suffix
      • A good choice is omeka
    • Enter the suffix in the New Database field
  • Click the Next Step button

Note

If you want to populate the new database with data from an existing Digital Archive database, follow the instructions to copy a MySQL database.

Create a user

  • In wizard Step 2 Create Database Users:
    • Decide on the user name suffix
      • A good choice for a standalone installation is archivist
      • A good choice for a subdomain installation is admin
    • Enter the suffix in the Username field
  • Click the Password Generator button
  • In the popup dialog:
    • If you don't like the password, click the Generate Password button to get another
    • Copy the password to a password vault or other safe place
    • Click the checkbox confirming that you copied the password to a safe place
    • Click the Use Password button
    • The two password fields get filled in with the generated password automatically
  • Click the Create User button
  • In wizard Step 3 Add user to the database:
    • Check the ALL PRIVILEGES checkbox at the top
    • Click the Next Step button

subdomain installation

Create a database

  • Go to cPanel and choose MySQL Databases
  • In the Create New Database section enter the site name e.g. demo as the database name
  • Click the Create Database button
  • On the database added page, click Go Back
  • In the Add User To Database section
    • Choose daus_admin as the user
    • Choose the new database name as the database e.g. daus_demo
    • Click the Add button
  • On the Manage User Privileges page
    • Check the ALL PRIVILEGES box
    • Click the Make Changes button

Configure MySQL Workbench

This step is only necessary for a standalone installation. For a subdomain installation, the new database will already be availale in MySQL Workbench as one of the digitalarchive.us databases.


Omeka installation

Copy installation files to server

Follow these steps to upload the Omeka Classic files to the web server. You can also read Omeka's installation instructions.

Standalone installation

  • Navigate into the public_html folder
  • Upload and extract the zip file
  • A new folder having the same name as the zip file will appear
  • Rename the new folder from the zip file's name to digitalarchive
  • Delete the zip file.
  • Copy C:\laragon\www\favicon.png to the public_html folder

Subdomain installation

  • Navigate into the site folder e.g. domains/demo
  • Upload and extract the zip file
  • A new folder having the same name as the zip file will appear
  • Navigate into the new folder
  • Select all of the files and move them to the site folder e.g. domains/demo
  • Navigate back up to the site folder
  • Delete the zip file
  • Delete the now empty folder having the same name as the zip file
  • Copy C:\laragon\www\favicon.png to the site folder

Edit database configuration

Follow these steps to configure Omeka to use the database you created. The username, password, and dbname values come from the create MySQL database task.

  • Go to cPanel and choose File Manager
  • Navigate into the site folder
  • Edit db.ini
  • Replace occurrences of "XXXXXXX" as follows:
    • host = "localhost"
    • username = "database username"
    • password = "database password"
    • dbname = "database name"
    • prefix = "omeka_"
    • charset = "utf8"
    • Leave port commented out
  • Save your changes and close the file

To learn more, see the Omeka documentation for the database configuration file.

Important

The db.ini file tells Omeka how to access the database. Any errors, typos, or incorrect information in this file will prevent Omeka from running and result in the display of a fatal error.


Enable error reporting and HTTPS

This step allows PHP errors to appear in the browser. Normally you would not want this for a production site, but it's better to become aware of a problem if it occurs.

In these steps you'll also add code to force URLs to https. The code gets added here and in the root-level .htaccess file and in the steps to configure site security.

  • Go to cPanel and choose File Manager
  • Allow hidden files to be displayed:
    • Click the Settings button in the upper right of the File Manager
    • Check the box for Show Hidden Files
  • Navigate into the site folder
  • Edit .htaccess
  • Uncomment SetEnv APPLICATION_ENV development
  • Add the code below to force URLs to HTTPs
  • Save your changes and close the file

Put the code below immediately after the line RewriteEngine on

# Force all URLs to HTTPS
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R,L]

Enable error logging and background process

Follow these steps to enable Omeka error logging so that a history of errors will be recorded. To learn more, see the Omeka documentation for retrieving error messages.

  • Go to cPanel and choose File Manager
  • Navigate into the site's application/config/ folder
  • Edit config.ini
  • Change log.errors from false to true
  • Change background.php.path from blank to /usr/local/bin/php
  • Save your changes and close the file

Errors are written to:

  • digitalarchive/error_log
    • Okay to delete – it gets recreated automatically. Shows PHP errors.
  • digitalarchive/admin/error_log
    • Okay to delete – it gets recreated automatically
  • digitalarchive/application/logs/errors.log
    • Must exist – will get Omeka error if not present and writable.
      If the file gets too big for cPanel to allow editing, you can delete the file and create a new one with the same name.

If errors are not appearing in the browser, make sure that display_errors=On and error_reporting=32767 (or E_ALL). These two settings can be applied in php.ini, but since there can be multiple php.ini files, it's not always clear which applies.


Omeka configuration

You are now ready to launch Omeka and configure site settings.

  • Open a browser using the URL for the digitalarchive folder, for example: avantlogic.net/digitalarchive.

The Omeka Configure Your Site page should appear.

Site settings

Enter configuration settings

You can now configure the Omeka site. See the Omeka general settings documentation and the appearance settings documentation for an explanation of the configuration settings.

Super user

The username and password you will specify below are for an Omeka super user.
See Omeka terminology to learn what it means to be a super user.

  • Set:
    • Username: a super user name
    • Password: super user password
    • Re-type the Password: super user password
    • Email: a valid email address
    • Administrator Email: same as Email
    • Site Title: the organization name
    • Site Description: leave blank
    • Site Copyright Information: the organization name
    • Site Author Information: your name or company
    • Tag Delimiter: , (a comma)
    • Fullsize Image Size: 600
    • Thumbnail Size: 300
    • Square Thumbnail Size: 100
    • Items Per Page (admin): 50
    • Items Per Page (public): 50
    • Show Empty Elements: Unchecked
    • ImageMagick Directory Path: /usr/bin
  • Click the Install button
  • You should see the Success! page.

Site settings

  • Click the Admin Dashboard button
  • Login with the super user user name and password
  • Check the Remember Me checkbox
  • Click the Login button
  • The Dashboard page should display.

Configure additional settings

Follows these steps to finishing configuring Omeka.

Appearance settings

  • On the Dashboard page, click Appearance in the top menu bar
  • Click Settings in the Appearance page menu bar
  • At the bottom of the page, uncheck Show Element Set Headings
  • Click the Save Changes button

Search settings

  • Click Settings in the top menu bar
  • Click Search in the Settings page menu bar
  • Uncheck all Search Record Types except Item
  • Click the Save Changes button

General settings

  • Click General in the Settings page menu bar
  • Click the Test at the bottom of the page
    You should see The ImageMagick directory path works
  • If the message says that the path does not work:
    • Go to cPanel and choose Terminal
    • In the terminal window, type which convert and press Enter
    • Use the response to determine the correct path and try again or contact your host's technical support and ask them to tell you the path

Change database storage engine

This step is only necessary when using AvantSearch without AvantElasticsearch.

These steps change the storage engine for the search_texts table from MyISAM to InnoDB. They also add a FULLTEXT index to the title column of the search_texts table. To learn the reason for making these changes, see the AvantSearch plugin topics on improving search results and the Titles Only option.

Follow these steps to change the storage engine:

  • Go to cPanel and choose phpMYAdmin
  • In the left panel, click on the Omeka database name to see its tables
  • Click on the omeka_search_texts table in the left panel
  • Click on the Operations tab
  • In the Table Options section, change Storage Engine from MyISAM to InnoDB
  • Click the Go button in the lower right of the section
  • Click on the omkea_search_texts table
  • Click the Structure tab
  • On the row for title, click Fulltext among the actions at the far right. If the browser window is too narrow to see all the options, click on More and choose Fulltext from the dropdown menu
  • On the Confirm dialog click the OK button to alter the table
  • Title now appears in the Indexes section showing with Type as FULLTEXT
  • Close the phpMyAdmin browser tab

Web server settings


Disallow bots

Crawling of Digital Archive sites by Google and other major search engines is generally a good thing; however, some commercial bots can hit a single Digital Archive site as often as 100,000 times a day or more. The robots.txt file is used to block specific bots while allowing others to access the site. As of September 2020, the bots listed below were the worst offenders, though their behavior was not malicious.

To see bot traffic, use the cPanel tool Awstats and click the Robots/Spiders visitor link in the left panel.

Edit (or create) public_html/robots.txt to contain the content below:

User-agent: *
Disallow: /files/

User-agent: AhrefsBot
Disallow: /

User-agent: SemrushBot
Disallow: /

Configure PHP settings

  • Go to cPanel and choose MultiPHP INI Editor
  • Select the Basic Mode tab
  • Choose the site from the dropdown menu
  • Set:
    • max_execution_time: 120
    • memory_limit: 512M
    • post_max_size: 128M
    • upload_max_filesize: 128M
  • Click the Apply button

Verify PDF support

These steps verify that a program called pdftotext is installed on the web server. It is used by the AvantElasticsearch plugin to make PDF files searchable. If you won't be using AvantElasticsearch, you can skip this task.

  • Go to cPanel and choose Terminal
  • In the terminal window, type pdftotext -v and press Enter
  • The pdftotext program should display its version
  • If instead you see command not found, ask your host to install pdftotext

Verify that background processing works

Some Omeka operations are performed in the background. Examples are a request to reindex records and using the Bulk Edit plugin to perform bulk edits in the background.

Follow these steps to determine if the default configuration for background processing is working properly.

  • Click Settings in the top menu bar
  • Click Search in the Settings page menu bar
  • Click the Index Records button (even though there are no records to index)
  • You should see a green message Indexing records. This may take a while...
  • If instead you get an error that the configured PHP path is or does not point to a PHP-CLI binary:
    • Edit digitalarchive/application/config/config.ini
    • Set background.php.path to the correct path for the server e.g. /usr/local/bin/php
    • Save changes and close the config.ini file
    • Verify that the Index Records operations works with no error

Finding the right path might be a trial and error process. Leaving background.php.path = "" works correctly on some servers. On others it needs to be set to /usr/local/bin/php or /usr/bin/php-cli. If you are not successful, contact the host to ask for the right path. Also read the next section.

Installations that don't support background processing

Some installations such as XAMPP on Windows might not support background processing. In that case, you can have background jobs run in the foreground. To do this, edit the Omeka core file /application/config/config.ini as shown below:

jobs.dispatcher.default = "Omeka_Job_Dispatcher_Adapter_Synchronous"
jobs.dispatcher.longRunning = "Omeka_Job_Dispatcher_Adapter_Synchronous"
;jobs.dispatcher.longRunning = "Omeka_Job_Dispatcher_Adapter_BackgroundProcess"

When upgrading to a new release of Omeka, make sure that you edit the file again.


Plugin acquisition

It is now time to acquire the zip files containing the plugins, and the theme, required by the Digital Archive. This section explains where to locate the files and how to add them to the installation so that later you can install and configure them and each plugin. To add them means to upload them to the web server and extract them into the proper installation folders.

Get Digital Archive zip files

The following zip files are required for most Digital Archive installations. All the files are located on GitHub. The link on the zip file name takes you to the GitHub repository for that file.

Type Plugin Name Zip file name
Omeka plugin ArchiveRepertory ArchiveRepertory 2.15.7.zip
Avant plugin AvantAdmin AvantAdmin-master.zip
Avant plugin AvantCommon AvantCommon-master.zip
Avant plugin AvantCustom AvantCustom-master.zip
Avant plugin AvantDPLA AvantDPLA-master.zip
Avant plugin AvantElasticsearch AvantElasticsearch-master.zip
Avant plugin AvantElements AvantElements-master.zip
Avant plugin AvantImport AvantImport-master.zip
Avant plugin AvantRelationships AvantRelationships-master.zip
Avant plugin AvantS3 AvantS3-master.zip
Avant plugin AvantReport AvantReport-master.zip
Avant plugin AvantSearch AvantSearch-master.zip
Avant theme AvantTheme AvantTheme-master.zip
Avant plugin AvantZoom AvantZoom-master.zip
Omeka plugin BulkMetadataEditor BulkMetadataEditor.zip
Omeka plugin Geolocation* Geolocation.zip
Omeka plugin OaiPmhRepository OaiPmhRepository-master.zip
Omeka plugin SimpleVocab SimpleVocab-2.2.2.zip

* Indicates that the Omeka plugin has been modified by AvantLogic for the Digital Archive


Get Avant plugin or theme zip file

Follow these steps to locate and download each zip file one at a time:

  • Click on a link in the table above to go to the GitHub repository for the file

  • If the link takes you to the main repository page:

    • Be sure that the latest revision is what you want.
      If in doubt, download the latest release instead.
    • Click the green Clone or download dropdown as shown below
    • Choose Download ZIP
    • Save the file to a folder on your computer

    GitHub download

  • If the link takes you to a release page:

    • Click the link for the .zip asset (pointed to by the arrow below)
    • Save the file to a folder on your computer

    GitHub download


The sections that follow assume that you are familiar with the process to upload and extract a zip file.

Upload and extract the theme

  • Upload AvantTheme-master.zip into public_html/digitalarchive/themes
  • Extract AvantTheme-master.zip
  • Click the cPanel Reload menu item to see the resulting folder
  • Delete AvantTheme-master.zip
  • Rename the AvantTheme-master folder to AvantTheme

Upload the plugin zip files

  • Go to the folder where you downloaded the zip files
  • Select all the files, except for the theme
  • Right click the selection and choose Send to > Compressed (zip) folder

GitHub download

  • Rename the newly created zip file to plugins.zip
  • Upload plugins.zip into public_html/digitalarchive/plugins
  • Extract plugins.zip to get the individual plugin zip files
  • Delete plugins.zip

Extract individual plugin zip files

For each of the plugin zip files:

  • Extract the zip file
  • Click the cPanel Reload menu item to see the resulting folder
  • Delete the zip file
  • Rename the folder to remove -master

There does not seem to be a way to extract all of them at once.


Remove unused plugins

Delete these two folders for plugins that the Digital Archive does not use:

public_html/digitalarchive/plugins/Coins
public_html/digitalarchive/plugins/ExhibitBuilder

The plugins folder on the web server should now look like this: GitHub download


AvantTheme configuration

AvantTheme, and many of the AvantPlugins, depend on the AvantCommon plugin being installed. Before you can install the theme, install AvantCommon by following these steps:

  • Login to Omeka as a super user
  • Click Plugins in the top menu bar
  • Many of the plugins added in the previous task will be shaded in pink
  • Click the Install button for AvantCommon
  • On the Configure Plugin: AvantCommon page:
    • Don't enter any values for now
    • Click the Save Changes button
  • The pink shading should be gone from all of the plugins except for AvantLocation, AvantRelationships, AvantReport, and AvantVocabulary.
  • Click Appearance in the top menu bar
  • On the Themes page, click the Use this theme button for AvantTheme
  • AvantTheme is now the current theme

Remove unused themes

  • Use cPanel to navigate into public_html/digitalarchive/themes
  • Delete all the theme folders except AvantTheme

Item elements definition

Omeka installs with a number of different Item Types and Elements; however, the Digital Archive uses only one Item Type which contains all of the Dublin Core elements plus only those additional elements that the organization needs. Having just one Item Type makes data entry easier and faster. To learn more, see the Omeka documentation for Item Types.

Follow the steps below to remove unused Item Types and Elements and create a single Item Type having the elements needed by the organization.


Delete unused item types

  • Open the database in MySQL Workbench
  • Right click on the omeka_item_types table and choose Select Rows
  • Select all the rows
  • Right click on the selection and choose Delete Rows
  • Click the Apply button in the lower right
  • Click the Apply button on the Apply SQL Script to Database dialog
  • When the deletion completes, click the Finish button

Delete unused elements

  • Right click on the omeka_elements table and choose Select Rows
  • Select all the non Dublin Core element rows. Those rows have an
    element_set_id value of 3 and are named Text, Interviewer, Interviewee etc.
  • Right click on the selection and choose Delete Rows
  • Click the Apply button in the lower right
  • Click the Apply button on the Apply SQL Script to Database dialog
  • When the deletion completes, click the Finish button

You can now quit MySQL Workbench.


Create a new Item Type

  • Login to Omeka
  • Click Items Types in Omeka's left admin menu
  • Click either of the green Add an Item Type buttons
  • For Name use the site name in all caps, for example NEHL for Northeast Harbor Library
  • Leave the description blank
  • Click the Add Item Type button

The new Item Type contains all of the Dublin Core elements. If you know what other elements the organization needs, you can add them now, or you can add additional elements as the last task of the installation. The Administrator documentation explains how to add a new element.


Add additional elements

See the Administrator documentation on how to add a new element.
Also, arrange the order of all elements.


Arrange element order

The default order in which the Dublin Core elements appear when editing an item is not suitable because the Identifier and Type fields appears near the end. Follow the instructions to arrange the element order into the recommended sequence for the Digital Archive.


FTP access

This section describes how to set up FTP access for a superuser.

This is an optional step during installation. It can be done later if/when the organization needs FTP access e.g. to upload zoom tiles.

Set up superuser FTP access

Follow these steps to access the Digital Archive web server via FTP.

Note

The settings below are for the site's primary FTP account which can use the SSH protocol. The settings for a limited FTP account are restricted to using the FTP protocol. To learn more see this post.

  • Run FileZilla
  • Choose File > Site Manager from the top menu bar
  • On the Site Manger dialog click the New site button
  • Fill in the site name in the My Sites tree
  • On the General Tab set:
    • Protocol: SFTP – SSH File Transfer Protocol
    • Host: Example: ftp.mydomain.net
    • Port: leave blank
    • Logon Type: Normal
    • User: cPanel username
    • Password: cPanel password
  • Click the Connect button
  • On the Unknown host key dialog:
    • Check the Always trust this host checkbox
    • Click the OK button

Administrator FTP access


Beyond Compare

Beyond Compare is a tool for comparing and synchronizing local files and folders with their remote counterparts on the Digital Archive server. It does this using its builtin FTP support.

To add a Digital Archive site to Beyond Compare, you need to specify the location of the local site and the remote site and then save two comparison sessions, one for the themes folder and one for the plugins folder.

Create theme comparison session

  • Run Beyond Compare
  • Click on the Folder Compare option on the home page
  • Set the local site
    • Click the folder icon in the upper right of the left pane
    • Click Local File System in the left panel
    • Navigate to C:\laragon\www\omeka-2.6 in the right panel
    • Click the OK button
  • Set the FTP site
    • Click the folder icon in the upper right of the right pane
    • Click on Quick Connect > FTP Profile in the left panel
    • Enter the FTP credentials for the remote server
    • Click the Connect & Browse button to verify that you can access the site
    • Click the OK button
  • In each pane:
    • Navigate to the themes folder
    • Right click on the folder and choose Set as Base Folder
  • On the main menu, click Session > Save Session As
  • In the Save current settings as field, type e.g. SWHPL Theme
  • In the Create in tree click Digital Archive
  • Click the OK button

Create plugin comparison session

  • In each pane:
    • Navigate to the plugins folder
    • Right click on the folder and choose Set as Base Folder
  • On the main menu, click Session > Save Session As
  • In the Save current settings as field, type e.g. SWHPL Plugins
  • In the Create in tree click Digital Archive
  • Click the OK button
  • In the top menu bar click Session > Session Settings...
  • On the Session Settings dialog click the Name Filters tab
  • Past the list below in the Exclude folders: panel
  • Click the OK button
.git
.\ArchiveRepertory
.\AvantDpla
.\AvantElasticsearch\vendor
.\BulkMetadataEditor
.\CsvExport
.\Dropbox
.\ExhibitBuilder
.\Gcihs
.\Geolocation
.\OaiPmhRepository
.\SimplePages
.\SimpleVocab

To rename or delete existing sessions, click on the Home button in the ribbon and then access the session of interest in the Sessions tree at left.


Plugin installation

You are now ready to install the plugins that turn an Omeka installation into the Digital Archive.

At this point in the installation, the plugin files have been uploaded to the web server and will appear on the Omeka Plugins page; however, most of the plugins have not yet been installed as is evidenced by the green Install button.

Install button

Once a plugin is installed, it shows buttons that let you configure, deactivate, or uninstall it.

Install button

Install and configure the plugins in the order in which they appear in the sections that follow.


Archive Repertory

The Archive Repertory plugin controls where files are stored when you attach files, such as images or documents, to Omeka items.

Important

Install this plugin now before adding any items to Omeka because the plugin overrides Omeka's default file storage mechanism and it won't work correctly if some files have already been stored.

Follow these steps to install and configure the Archive Repertory plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for Archive Repertory
  • Set:
    • Collections option:
      • How do you want to name ...: Don’t add folder
    • Items options:
      • How do you want to name ...: Identifier
      • Prefix for Item: leave blank
      • Convert folder names: Full conversion to Ascii
    • Files option:
      • Convert filenames: Full conversion to Ascii
      • Keep only base...: Unchecked
    • Special derivative folders options:
      • Other derivative folders: leave blank
      • Process: Omeka internal
      • Max size for downloads: 30000000
      • Confirm downloaded: Unchecked
      • Legal: I agree with terms of use.
  • Click the Save Changes button

Verify that the plugin is working as expected.

Add a test item

  • Click Items in Omeka's left admin menu
  • Click the Add an item link
  • Enter 12345 in the Identifier field
  • Enter Test 1 in the Title field
  • Click the Add Item button

Upload a test image

  • Click Items in Omeka's left admin menu
  • Click the Edit link under the Test 1 item
  • Click on the Files tab at the top of the page
  • Click the Choose File button
  • Browse for an image
  • Click the Save Changes button
  • You should now be on the Item page for new item.
  • Use FTP or cPanel to navigate to the /digitalarchive/files folder
  • Verify that the subfolders (fullsize, original etc) contain a subfolder named 12345
  • Verify that the12345 folder contains the uploaded image

Delete the test item

  • On the Item page, click the Delete button
  • Click Delete on the Are you sure dialog
  • Verify that the 12345 folders got deleted from the /digitalarchive/files folders

Do not attempt to add any more items until the installation is completed including setting up AvantElasticsearch and AvantVocabulary.

If using Filezilla, you may need to disconnect and reconnect to verify that the files got deleted because the Refresh option does not always seem to work. Or do the verification using the cPanel File Manager.


Bulk Metadata Editor

Follow these steps to install Bulk Metadata Editor:

  • Go to the Omeka Plugins page
  • Click the Install button for Bulk Metadata Editor
  • The plugin has no configuration options

Geolocation

Skip this task if the installation will not be using the Geolocation plugin.

The only Digital Archive installation that has the Geolocation plugin installed is Southwest Harbor Public Library and it uses a version modified by AvantLogic; however, the Library has deactivated the plugin because too much advertising shows up in the maps.

Follow these steps to install the Geolocation plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for Geolocation
  • Configure the plugin as appropriate for the installation
  • Click the Save Changes button

OAI-PMH Repository

Skip this task if the installation will not ingested by the Digital Public Library of America.

Follow these steps to install the OAI-PMH Repository plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for OAI-PMH Repository
  • Configure the plugin as appropriate for the installation
  • Click the Save Changes button

Simple Pages

Simple Pages has no configuration options.

Follow these steps to install the Simple Pages plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for Simple Pages
  • Go to the Omeka Settings > Security page
  • Uncheck the Enable HTML Filtering checkbox to allow all HTML tags such as <img>

Notes

When adding Simple pages, be sure to check the box for Publish this page? so it will show up in the Omeka navigation section.


Simple Vocab

You'll install the Simple Vocab plugin next because it is needed by the AvantElements plugin.

Follow these steps to install and configure the Simple Vocab plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for Simple Vocab
  • Leave Apply to Files unchecked
  • Click the Save Changes button
  • Click Simple Vocab in Omeka's left admin menu
  • Add vocabularies for the Rights, Subject, Type, and Place elements (see below)
  • Click the Save Changes button after specifying values for each element

Rights

In Copyright
In Copyright - Educational Use Permitted
In Copyright - Non-Commercial Use Permitted
In Copyright - Rights-holder(s) Unlocatable or Unidentifiable
No Copyright - United States
No Copyright - Non-Commercial Use Only
Copyright Not Evaluated
Copyright Undetermined
No Known Copyright

If you will be using the AvantVocabularyplugin, set Subject, Type, and Place as shown below. Otherwise, provide the values you want.

Subject

Use the Vocabulary Editor to specify Subject terms

Type

Use the Vocabulary Editor to specify Type terms

Place

Use the Vocabulary Editor to specify Place terms

AvantAdmin

Follow these steps to install and configure the AvantAdmin plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantAdmin
  • Leave the Maintenance checkbox unchecked
  • Enter the Item Type name for the organization (usually all caps e.g. SWHPL)
  • Click the Save Changes button

AvantCommon

The AvantCommon plugin was installed as part of the task to install AvantTheme.

Follow these steps to configure the AvantCommon plugin:

  • Go to the Omeka Plugins page
  • Click the Configure button for AvantAdmin
  • Enter the Identifier as Identifier
  • Enter an Alias if applicable or leave blank
  • Enter any Private Elements
  • Enter the Unused Elements shown below plus any others
Source
Contributor
Relation
Format
Language
Coverage
  • Check the Enable Lightbox checkbox
  • Leave Request Image URL blank
  • Click the Save Changes button

AvantCustom

AvantCustom has no configuration options. Follow these steps to install AvantCustom:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantCustom
  • The plugin has no configuration options

AvantDPLA

Skip this task if the installation will not ingested by the Digital Public Library of America.

Follow these steps to install the AvantDPLA plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantDPLA
  • The plugin has no configuration options

AvantElements

Follow these steps to install and configure the AvantElements plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantElements
  • Enter the Display Order elements shown below plus any others
Identifier
Title
Type
Subject
Description
Creator
Publisher
Date
Rights
  • Enter the Implicit Link elements shown below plus any others
Type
Subject
  • Leave External Link blank
  • Check the External Link Icon checkbox
  • Enter the Validation specifiers shown below plus any others
Title: required, simple-text
Type: required
Creator: simple-text
Publisher: simple-text
Date: date
Rights: required
  • Enter the Allow Add Input elements shown below plus any others
Title
Creator
Subject
  • Leave Allow HTML blank
  • Enter the Text Field specifiers shown below plus any others
Identifier: 70
Date: 160
Creator
  • Enter the Vocabulary Field specifiers shown below plus any others
Type: 320
Subject: 320
Rights
  • Leave Checkbox field blank
  • Leave Read-only Field blank
  • Leave Default Value blank
  • Enter the Suggest elements shown below plus any others
Creator
Publisher
  • Enter the Title Sync specifiers shown below plus any others
Creator
Publisher
  • Enter the Custom Callback specifiers shown below plus any others
Identifier, default: DigitalArchive, getDefaultIdentifier
Identifier, validate: DigitalArchive, validateIdentifier
Rights, filter: DigitalArchive, filterRights
Date, filter: DigitalArchive, filterDate
<item>, validate: DigitalArchive, validateItem
  • Verify that you have set all of the options correctly
  • Click the Save Changes button

Change Element Set order

  • Click Settings in the top menu bar
  • Click the Element Sets tab
  • Click the Edit link for Dublin Core
  • Reorder the elements by dragging them to the order shown below.
  • Click the Save Changes button
Identifier
Title
Type
Subject
Description
Date
Creator
Publisher
Source
Contributor
Rights
Relation
Format
Language
Coverage

AvantImport

Skip this task if the installation will not be importing items from a CSV file.

Follow these steps to install the AvantImport plugin:

  • Go to cPanel and choose File Manager
  • Create this folder: public_html/digitalarchive/files/import
  • Go to the Omeka Plugins page
  • Click the Install button for AvantImport
  • Leave Mappings blank
  • Click the Save Changes button

To learn how to use AvantImport, see how to import CSV data.


AvantRelationships

Follow these steps to install the AvantRelationships plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantRelationships
  • Set Visualization Preview to At designated location
  • Set Max Direct Items to 6
  • Set Max Indirect Items to 8
  • Enter the Title Relationships specifier shown below plus any others
Creator: Created
Publisher: Published
  • Leave Custom Relationships blank
  • Leave Delete Tables unchecked
  • Click the Save Changes button

AvantSearch

Ignore the MyISAM warning if the installation will be using Elasticsearch.

Follow these steps to install and configure the AvantSearch plugin:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantSearch
  • Check the Titles Only checkbox

  • Enter the Columns specifiers shown below plus any others

Identifier, Item: 65, right
Title
Type
Subject
Creator
Publisher
  • Enter the Layout specifiers shown below plus any others
L1, Details
L2, Type / Subject: Identifier, Title, Type, Subject
L3, Creator / Publisher: Identifier, Title, Creator, Publisher, Date
  • Enter the Detail Layout elements shown below plus any others
Identifier
Type
Subject
Creator
Publisher
Date
<tags>
<score>
  • Enter Identifier for Integer Sorting
  • Leave Address Sorting unchecked (will not be available if there is no Address element)
  • Leave Elasticsearch unchecked (will not be available until AvantElasticsearch is installed)
  • Click the Save Changes button

AvantReport

AvantReport has no configuration options. Follow these steps to install AvantReport:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantReport

AvantZoom

AvantZoom has no configuration options. Follow these steps to install AvantZoom:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantZoom

To learn about using AvantZoom, see the documentation for zoomable images.

Create a Zoom folder

Follow these steps to create the folder used to store the tiles for zoomable images.

  • Go to cPanel and choose File Manager
  • Create these two folders within the files folder of the site folder:
    • files/zoom
    • files/zoom/images
  • Copy the OpenSeadragon icons from public_html/digitalarchive/plugins/AvantZoom/images to public_html/digitalarchive/files/zoom/images

Create limited FTP account

Follow these steps to create a limited access FTP account that will allow an administrator to upload zoomable image tiles to the zoom folder, but will prevent them from seeing any other installation folders.

  • Go to cPanel and choose FTP Accounts
  • Type zoom for the Log in name and generate a password
  • Set the Directory to public_html/digitalarchive/files/zoom
  • Leave the Quota as Unlimited
  • Click the Create FTP Account button
  • The FTP username will look like this example: zoom@mydomain.net
  • Test the account using the documentation for zoom tiles upload methods.

Administrator FTP account


AvantS3

Skip this task if the installation will not be using S3.

Follow these steps to install and configure AvantS3:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantS3

If you are not using the AvantCustom plugin, also follow these steps:

  • Go to the configuration options page for the AvantElements plugin
  • Add the code below to the end of the Custom Callback specifiers
Identifier, filter: DigitalArchive, filterIdentifierS3

AvantElasticsearch

Skip this task if the installation will not be using AvantElasticsearch.

Create AWS credentials

Before installing AvantElasticsearch, create the AWS credentials that you'll need to provide on the AvantElasticsearch configuration page.

  • Go to https://aws.amazon.com/
  • Click the Sign In to the Console button at upper right
  • Enter the Account ID ending in 4548
  • If the page says Sign is as IAM user, click the Sign-in using root user email link
  • Enter the root user email
  • Enter the root user password
  • Provide the Google Authenticator code
  • You should now be on the AWS Management Console page
  • In the top menu dropdown for the logged in user, choose Security Credentials (root user)
  • You should now be on the My Security Credentials page
  • Click Users in the left menu
  • Click the Create User button at the top right
  • For the User name type the organization abbreviation in lowercase e.g. swhpl
  • Leave the access to AWS Management Console option unchecked
  • Click the Next button
  • In the Permissions options section, choose Add user to group
  • In the User groups section, check the box for contributor group
  • Click the Next button
  • Click the Create user button
  • Click the new user in the list of users
  • In the Summary section, click Create access key
  • On the Access key best practices page choose Other
  • Click the Next button
  • On the Set description tag page click the Create access key button
  • You should now be on the Retrieve access keys page
  • Click the Show link for the Secret Access Key
  • Copy the Access Key ID and Secret Access Key to the AWS Keys tab of the Digital Archive Accounts Excel sheet
    This is the only opportunity to obtain the secret key
  • Click the Done button

Install the AvantElasticsearch plugin

Follow these steps to install and configure the AvantElasticsearch plugin:

Create a folder needed by the AvantElasticsearch plugin

  • Go to cPanel and choose File Manager
  • Navigate into the files folder of the site folder
  • Create this subfolder: files/elasticsearch

Install the AvantElasticsearch plugin

  • Go to the Omeka Plugins page
  • Click the Install button for AvantElasticsearch

Edit es.ini

Follow these steps to allow the installation to share its items with other Digital Archive installations via the shared AWS Elasticsearch index:

  • In cPanel, edit es.ini in the site folder
  • Set shared_index_name to the name of the shared index e.g. acadia

Shared Index

FOR ADMINISTRAOR ACCOUNT ONLY: If the account needs to be able to create a new local or shared index, add: new_local_index_allowed = true and/or new_shared_index_allowed = true to the es.ini file which is located in /digitalarchve (in the same root folder as db.ini). This will cause new radio buttons to appear on the Elasticsearch page to allow import into a new index. This is an especially dangerous operation for a shared index because it will destroy all the data for all sites in the shared index and therefore should only be performed when creating a shared index that does not already exist.

Configure the AvantElasticsearch plugin

  • Set Contributor Id e.g. swhpl
  • Set Contributor e.g. Southwest Harbor Public Libary
  • Set Host to the AWS Domain Endpoint which can be found in:
    • The AWS Keys tab of the Digital Archive Accounts Excel sheet and on AWS and in
    • Amazon OpenSearch Service > Domains > digitalarchive
    • Example: search-digitalarchive-6wn********************o4q.us-east-2.es.amazonaws.com
  • Set Region to us-east-2
  • Set Key and Secret to the keys obtained in the step above to create AWS credentials
  • Check Local Index
  • Check Shared Index

Enable Elasticsearch in AvantSearch

  • Go to the configuration options page for the AvantSearch plugin
  • Check the Elasticsearch checkbox

AvantVocabulary

Skip this task if the installation will not be using AvantVocabulary.

Follow these steps to install and configure AvantVocabulary:

  • Go to the Omeka Plugins page
  • Click the Install button for AvantVocabulary
  • On the Configure Plugin page, leave Delete Tables unchecked
  • Click the Save Changes button
  • Click Vocabulary Editor in the left admin menu
  • Click the Rebuild Common Terms table button and click OK on the confirmation dialog
  • Wait for the build to report that it has completed (it writes about 30,000 records)
  • Click the Rebuild Local Terms table button and click OK on the warning dialog
  • Wait for the build to say that it has completed and will reload the page (this will be very fast on a new installation)

Add vocabulary terms

At this stage the only vocabulary terms that will be set for the site are Places which is kind 4 in the site terms table. If you look at the table you'll see that those are the only kind of rows there.

You'll now need to add some Type and Subject terms so that the organization has something to work with.

Work Around

There is currently an issue with the AvantVocabulary plugin whereby you can't add a new term unless there is at least one term in the table.To work around this, manually add one Subject (Image, Photograph) and one Type (People) to the site terms table using MySql Workbench as shown below.

Site terms table

Note that to eliminate the default value of null, in the site_term column, you'll need to first add a value of one space, apply the changes, then delete the space and apply again.

Now go to the Vocabulary Editor, click the Rebuild Local Terms table button and click OK on the warning dialog.

The two terms should show and and you should now be able to add new terms.

Suggestions for an initial set of Types:

Document, Correspondence, Letter
Image, Photograph
Map
Object, Writing, Postcard
Publication, Clipping, Newspaper Clipping
Reference

Suggestions for an initial set of Subjects:

Nature, Animals
People
Places, Island
Structures, Commercial, Lodging, Hotel
Transportation, Automobile

Reindex the local Elasticsearch index

Skip this task if the installation is not using AvantElasticsearch.

  • Add a new item with just the minimal fields
  • If you check to see the site's search results, you'll see a No items found message and an Elasticsearch error
  • Click Elasticsearch in the left menu
  • Export all items from Omeka
  • Import into new local index
  • You should now be able to see the item with no errors

Test the Elasticsearch installation

  • Add a photo to the item
  • Make the item public
  • Test that the item appears on the other sites as shared
  • Test that the new site appears on the Contributing Organizations page

Site styling

Set navigation

  • Click Appearance in the top menu bar
  • Click Navigation on the Appearance page menu bar
  • Uncheck Browse Items
  • Uncheck Browse Collections
  • In the Add a Link to the Navigation section:
    • Type landing for the Label
    • For URL choose:
      • For a standalone site: https://<site-url>/digitalarchive/find?query=
      • For a subdomain site: https://<site-url>/find?query=
    • Click the Add Link button
    • Change Select a Homepage to landing
    • Leave the landing item unchecked
  • Click the Save Changes button

Test that the landing page works by clicking the site's name located at left in the admin header. Unless you've added items to the site, you'll get a No items found error which is okay. Change the Search dropdown at the bottom to All Sites to verify that results come up from other sites.

  • Edit the About Simple Page to add some information about the organization
  • Add any other menu items

Logo and styling

  • Create a logo JPEG image approximately 500px X 110px
  • Login to Omeka as a super user
  • Click Appearance in the top menu bar
  • Click the Configure Theme button for AvantTheme
  • For Logo File browse to the folder containing the logo file
  • Choose the logo file
  • Configure:
    • Set the CSS file name
    • Enter the footer text
  • Adjust the custom CSS as necessary.
  • Click the Save Changes button
  • Remove the CSS files for other organization’s theme customization e.g. swhpl.css

Subdomain installation

This section discusses installing the Digital Archive in public_html/digitalarchive versus installing it in a subdomain. A subdomain is a domain that is part of a larger domain. For example, west.example.com and east.example.com are subdomains of the example.com domain. Note that example.com is actually a subdomain of the top-level domain com.

Subdomains are different from folders. For instance, example.com/digitalarchive points to the digitalarchive folder within the example.com domain whereas digitalarchive.example.com is a subdomain of example.com.

Two cases

There are two cases to consider when installing the Digital Archive in a subdomain.

  1. The subdomain is hosted on the domain's web server
  2. The subdomain is hosted on a different web server

Case 1 - subdomain is hosted on the domain's web server

Examples:

    site1.avantlogic.net
    site2.avantlogic.net

This case applies when using subdomains for hosting multiple instances of the Digital Archive on the same web server for development and testing purposes. The following sections point out some things you should be aware of.

Learn how to create a subdomain.

Database name and user

When you install the Digital Archive in more than one subdomain on the same web server, the corresponding databases and user names will all share the same prefix that cPanel assigns automatically. As such, you'll need to use unique suffixes to indicate which installation a database belongs to.

For example, on the avantlogic web server where the prefix is avantlog, instead of following the recommendation to name the database avantlog_omeka, choose database names like avantlog_site1 and avantlog_site2.

Similarly, for the database user name, instead of following the recommendation to name the user avantlog_archivist, choose user names that match the database names such as avantlog_site1 and avantlog_site2.

FTP

You don't need to set up separate FTP connections for each subdomain. You access a subdomain's files via the domain's FTP connection. If for some reason you need a separate FTP connection for a subdomain, the connection cannot use the SSH protocol, but must instead use the FTP protocol. For related documentation on this see Filezilla FTP settings for uploading zoomable images.


Case 2 - subdomain is hosted on a different web server

Example:

    digitalarchive.somecollege.edu

In the example, the Digital Archive files are installed in the public_html folder on a web server that is different from the somecollege.edu web server. On that different web server, the files are installed in public_html instead of in a digitalarchive folder because if they were, the URL would need to be digitalarchive.somecollege.edu/digitalarchive which is redundant.

To make this work, that is, for the subdomain ending in edu to resolve to another server, the somecollege.edu web administrator must point an A record or CNAME for the subdomain to the web server that hosts the subdomain. (CNAME is recommended as future-proof against server migrations).

With this arrangement, you can perform the tasks to install a Digital Archive site with only one modification: Instead of installing into the digitalarchive folder, install into the public_html folder.

Because you will be installing into the public_html folder, the code to force HTTPS for all pages needs to go into the .htaccess file that ships with Omeka in its top-level folder. Add the code below near the top of the file after RewriteEngine on. Don't add code for redirecting root access.

    # Force all URLs to HTTPS
    RewriteCond %{HTTPS} off
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R,L]

Installing on a bare Linux server

This section provides a few tips for installing on a remote server that does not have cPanel.

First, see Linux server administration and pay particular attention to the places that provide information on how to perform operations using the command line and ignore the places that refer to WHM and cPanel.

SSH

You can perform command line operations using OpenSSH that is built into Windows 10 and 11. To connect to the remote server using SSH:

  • Open a Windows terminal window (Command Prompt)
  • Type ssh followed by the host name of the remote server
  • Enter the password (does not show anything as you type)
    C:\Users\username>ssh foo.bar.net
    username@foo.bar.net's password:
    Last login: Wed Mar  6 07:30:19 2024 from 74.75.232.104
    [username@foo ~]$

You can now type Linux commands the same as you would using a cPanel Terminal window.

Troubleshooting

404 error when trying to go to any Omeka page

This problem can occur if mod_rewrite is not installed. See 404 and Not Found in the Omeka Classic User Manual.

The problem could also occur if the .htaccess file is not getting executed. One reason this could happen is if you leave the . off the beginning of the file name. You could try introducing an error into the file to determine if it is being executed.

Destination directory is not writable error

You'll get this permissions error when you attempt to add an item with a file attachment.

See Setting Directory Permissions in the Omeka Classic User Manual.

The problem occurs if the web server process doesn't have write access to the files directory and everything under it. The solution will depend on your server, but assuming that the web server runs as user apache you could do chown -R apache on the files directory to get the result below.

[username@foo digitalarchive.bar.org]$ ls -l files
total 1180
drwxrwsr-x. 125 apache digarc    4096 Mar  6 13:12 fullsize
drwxrwsr-x.   2 apache digarc 1130496 Mar  6 13:02 import
drwxrwsr-x. 125 apache digarc    4096 Mar  6 13:12 original
drwxrwsr-x. 125 apache digarc    4096 Mar  6 13:12 square_thumbnails
drwxrwsr-x.   2 apache digarc      68 Mar  5 11:30 theme_uploads
drwxrwsr-x. 125 apache digarc    4096 Mar  6 13:12 thumbnails