Skip to main content

System Requirements

Getting Started​

Providence is a web-based application that runs on a server. Users access the server from their own computers over a network using standard web browser software. As with any web-based application, Providence is designed to be accessed via the internet, enabling collaborative cataloguing of collections by widely dispersed teams. However, you do not have to make your Providence installation accessible on the internet. It will function just as well on a local network with no internet connectivity, or even on a single machine with no network connectivity at all. Who gets to access your system is entirely up to you.

Before attempting an installation verify that your server meets the basic requirements for running Providence:

Server RequirementsNotes
Operating SystemLinux, Mac OS X, or Windows Server
Server Memory4 gb of RAM minimum. If you intend to have CA handle large image files then your server should ideally have three times the size of the largest image when uncompressed. In general more memory is always better, and 8 gb of RAM is a good baseline if possible.
Data StorageA simple formula for estimating storage requirements requires an expected number of media items to be catalogued and an average size for those media items. Once these quantities are known an estimate can be derived using some simple arithmetic: <storage required in mb> = (<# of media items> * <average storage requirements per media item in mb>) + (<# of media items> * 5mb). 5mb is estimated overhead of storing derivatives (small JPEG, TilePic pan-and-zoom version, etc.) It is recommended to double the calculated storage requirements when acquiring hardware if practical. Storage requirements for your metadata and database indices, even if your database is quite large, are usually negligible compared to the storage required for media.
ProcessorMultiprocessor/multicore architectures are desirable for the improved scalability they provide, and well as the capability to speed the processing of uploaded media. Media processing is often CPU-bound (as opposed to database operations which are often I/O bound) and lends itself to multiprocessing. It is advisable to obtain a machine with at least 2 cores and, if possible, 4+ cores.

Core Software Requirements​

Providence requires three core open-source software packages be installed prior to installation. Without these packages Providence cannot run:

Software PackageNotes
WebserverApache version 2.4.43, nginx 1.30 or later are recommended.
MySQLVersions 8.4 and 9.7 are supported. Equivalent versions of MariaDB should also work but are not extensively tested.
PHPPHP version 8.2 or later is required; 8.4 or 8.5 are advised

The following PHP packages containing extensions are required:

  • php-cli
  • php-gd
  • php-curl
  • php-mysql
  • php-zip
  • php-xml
  • php-mbstring
  • php-intl
  • php-bcmath
  • php-gmp
  • php-opcache

These extensions are often (but not always) installed by default.

The following PHP extensions are recommended:

  • php-process
  • php-posix
  • php-gmagick (if GraphicsMagick is installed)
  • php-imagick (if ImageMagick is installed)
  • php-redis (if REDIS caching server is installed)
  • php-memcached (if memcached caching server is installed)

All of these should be available as pre-compiled packages for most Linux distributions and as installer packages for Windows. For Macs, Brew is a highly recommended way to get all of CA's prerequisites quickly up and running.

If setting up Apache, MySQL or PHP is daunting, you may want to consider pre-configured Apache/MySQL/PHP environments available for Windows and Macintosh such as MAMP and XAMPP. These can greatly simplify setup of CollectiveAccess and its requirements and are useful tools for experimentation and prototyping. They are not recommended for hosting live systems.

Required and Suggested Software Packages for Linux​

Ubuntu 24.04LTS or 26.04LTS​

Required:

  • mysql-server
  • apache2
  • php php-cli php-common + required and suggested PHP extensions

Suggested:

  • redis-server or memcached [Caching]
  • graphicsmagick & libgraphicsmagick-dev or imagemagick & libmagickwand-dev [Image processing]
  • ffmpeg [Audio and video processing]
  • ghostscript [PDF processing]
  • libreoffice [Microsoft Office file processing]
  • dcraw [RAW image format support]
  • poppler [Media metadata and text extraction]
  • mediainfo [Audio-visual media metadata extraction]
  • perl-Image-ExifTool [Image metadata extraction]
  • weasyprint or chromium-browser or wkhtmltopdf [PDF output]
  • OpenAI Whisper [Transcription of audio and video files]

Software requirements for installing development versions from Github​

If you are installing CollectiveAccess from a development branch on GitHub the following software is required:

  • composer The PHP package manager. getcomposer
  • git Version control software. Git is installed by default on many Linux distributions.

Caching​

CollectiveAccess makes heavy use of caching. By default cached data is written to disk, which r equires no additional configuration or software but can be slow and may cause spikes in server load when the cache fills and must be purged. Use of an in-memory cache such as REDIS (https://redis.io/) or Memcached (https://memcached.org) can provide significantly improved performance. To use REDIS you must connect a working REDIS instance to CollectiveAccess by setting the relevant configuration entries in the installation's setup.php file. You must also have the php-redis extension installed. For Memcached you must have Memcached installed and running; the PHP Memcached extensions installed; and the relevant configuration settings configured in setup.php.

Software requirements for media processing​

Depending upon the types of media you intend to use with CollectiveAccess you will also need to install various supporting software libraries and tools. None of these is absolutely required for CA to install and operate but without them specific types of media may not be supported (as noted below).

Software PackageMedia TypesNotes
GraphicsMagickImagesVersion 1.3.41 or better is required. GraphicsMagick is the preferred option for processing image files on all platforms and is better performing than any other option. Be sure to compile or obtain a version of GraphicsMagick with support for the formats you need. Support for some image formats is contingent upon other libraries being present on your server (eg. libTiff must be present for TIFF support). Some less common formats, such as PSD, may require special configuration and/or compilation.
ImageMagickImagesVersion 6.9 or better is required. ImageMagick can handle more image formats than any other option but is significantly slower than GraphicsMagick in most situations. Be sure to compile or obtain a version of ImageMagick with support for the formats you need! Support for some image formats is contingent upon other libraries being present on your server (eg. libTiff must be present for TIFF support).
libGDImagesA simple library for processing JPEG, GIF and PNG format images, GD is a fall-back for image processing when ImageMagick is not available. This library is typically bundled with PHP so you should not need to install it separately. In some cases you may need to perform a manual install or use a package provided by your operating system provider. In addition to supporting a limited set of image formats, GD is typically slows than ImageMagick or GraphicsMagick for many operations. If at all possible install GraphicsMagick on your server.
ffmpegAudio, VideoRequired if you want to handle video or audio media. Be sure to compile to support the file formats and codecs you require.
GhostscriptPDF DocumentsGhostscript 10 or better is required to generate preview images of uploaded PDF documents. PDF uploads will still work, but without preview images, if Ghostscript is not installed.
dcrawImagesRequired to support upload of proprietary CameraRAW formats produced by various higher-end digital cameras. Note that that AdobeDNG format, a newer RAW format, is supported by GraphicsMagick and ImageMagick.
PdfToTextPDF DocumentsA utility to extract text from uploaded PDF files. If present CA will use PdfToText to extract text for indexing. If PdfToText is not installed on your server CA will not be able to search the content of uploaded PDF documents. This utility is part of the Poppler package available in many Linux distributions.
MediaInfoImages, Audio, Video, PDF DocumentsA library for extraction of technical metadata from various audio and video file formats. If present CA can use MediaInfo to extract technical metadata, otherwise it will fall back to using various built-in methods such as GetID3.
ExifToolImagesA library for extraction of embedded metadata from many image file formats. If present CA can use it to extract metadata for display and import.
LibreOfficeOffice DocumentsLibreOffice is an open-source alternative to Microsoft Office. CollectiveAccess can use it to index and create previews for Microsoft Word, Excel and Powerpoint document. LibreOffice 24 or better is supported.
WeasyprintPDF OutputWeasyprint is an application that can perform high quality conversion of HTML encoded content to PDF format. If present CollectiveAccess can use Weasyprint to generate PDF-format labels and reports. (See https://weasyprint.org)
ChromiumPDF OutputGoogle Chromium is a popular web browser that can also be used to convert HTML encoded content to PDF format. If present CollectiveAccess can use Chromium to generate PDF-format labels and reports.
WkHTMLToPDFPDF OutputWkHTMLToPDF is an application that can perform high quality conversion of HTML content to PDF format. If present CollectiveAccess can use WkHTMLToPDF to generate PDF-format labels and reports. Version 0.12.1 or better is supported. However, do not use version 0.12.2, which has bugs that prevent valid formatting of output.
OpenAI WhisperAudio transcriptionWhisper is an open-source audio speech recognition system from OpenAI. When installed, CollectiveAccess can employ Whisper to automatically generate transcripts for audio and video content. See https://github.com/openai/whisper for installation instructions.

Most users will want at a minimum GraphicsMagick installed on their server, and should install other packages as needed. For image processing you need only one of the following: GraphicsMagick, ImageMagick, libGD.

For PDF report and label output you need only one of the following: Weasyprint, Chromium or WkHTMLToPDF. WkHTMLToPDF provides good rendering capabilities and high performance, but can be difficult to install and is no longer actively supported by its developers. As of CollectiveAccess version 2.0.11 support for PDF output using Weasyprint and Chromium is supported. Weasyprint is easy to set up and provides quality rendering, but can be slow for large or complex documents. Chromium provides good rendering and high performance but can be tricky to set up due to file permission requirements. If none of the PDF output options is installed, CollectiveAccess will fall back to a built-in PDF converter (domPDF) that provides limited rendering and relatively poor performance.

CA supports two different mechanisms to employ GraphicsMagick or ImageMagick. The preferred option is a PHP extension that when installed provides a fast and efficient way for CollectiveAccess to access GraphicsMagick or ImageMagick functionality. Alternatively GraphicsMagick or ImageMagick can be invoked as a command-line program directly without any PHP extension.

In general you should try to use a PHP extension rather than the command-line mechanism. The extensions provide much better performance. Unfortunately, the extensions have proven to be unstable in some environments and can be difficult to install on Windows systems. If you are running the PHP GMagick (for GraphicsMagick) or IMagick (for ImageMagick) extension and are seeing segmentation faults or incorrect image encoding such as blank images you should remove the extension, let the command-line mechanism take over and see if that improves things. Avoid installing both GMagick and IMagick on the same server. Simultaneous installation of both extensions has been associated with crashes and general instability.

Both Gmagick and Imagick are available in the PHP PECL repository and often available as packages for various operating systems. They should be straightforward to install on Unix-y operating systems like Linux and Mac OS X. Installation on Windows may be challenging.

HEIC image format support​

High Efficiency Image Container, or HEIC, is an Apple-proprietary image format which may provide higher quality and better compression than open standards such as JPEG. Many open-source tools, including GraphicsMagick, do not support this format due to patent licensing issues. If support for HEIC images in CollectiveAccess is required you must install a version of ImageMagick compiled to support HEIC. This may require installation of additional software libraries, including libde265 and libheif. If both GraphicsMagick and ImageMagick are installed, GraphicsMagick will be used for all image processing, as it is generally the most performant option, with all HEIC support delegated to ImageMagick.