A Beginner's Guide to
CollectiveAccess

1. Introduction

// What is CollectiveAccess?

From the official CollectiveAccess website:

CollectiveAccess is free, open-source software for cataloguing and publishing museum and archival collections.

It consists of two components:

  • Providence - A core cataloging and data management application. This is the "back-end" of CollectiveAccess, where you can input, edit, and manage your collection.
  • Pawtucket2 - A public web-access application. This is the "front-end" of CollectiveAccess, a website that can be hosted online, allowing anyone to search and browse the collection.

For simplicity's sake, from here on out I will refer to Pawtucket2 as simply Pawtucket, and sometimes abbreviate CollectiveAccess to CA.

// About this guide

Hi there! So, big disclaimer, I'm not the most tech literate person out there. I barely know how to open Windows Command Prompt and download stuff off Github. This guide is called a "beginner's guide" because me, the author, is a complete beginner when it came to this sort of stuff LOL. Installing CollectiveAccess is daunting as hell, but somehow with the power of the internet I managed to get it running locally.

If you are an unfortunate soul like me who is trying to install CA on a Windows computer and have no idea what the heck they're doing, hopefully this guide will be helpful!

Some technical things to note:

  • My local machine (laptop) is running Windows 11.
  • Versions I used: Providence 2.0.11 and Pawtucket2 2.0.11.
  • I have PHP 8.3.32 built with Visual C++ 2019 Thread Safe x64.
  • The way that I managed to get CA working, it's only accessible on a single local computer. There is a way that you could get it set up on a server and make it accessible to anyone with a web browser, but that's way beyond the scope of my abilities.
  • CA is developed for Linux and is notoriously finicky for Windows, so brace yourself.

// Ready to go?

Before you proceed, the first thing you should do is download Providence and Pawtucket from the official page, and open up the documentation. IMPORTANT: This guide is meant to be read in conjunction with the official documentation. I also highly recommend that you follow my guide in order.

This page was last updated: 07/17/2026

2. System Requirements

Official CollectiveAccess Documentation: System Requirements.

// Installing Apache

Follow this YouTube tutorial.

  1. Install the latest version of Visual C++ Redistributable for Visual Studio 2017-2026 and download the Apache binaries from Apache Lounge.
  2. Unzip and move the folder named "Apache24" into the C: drive so that the folder path should be C:\Apache24.
  3. Go to Windows start menu by pressing the Win key, open Command Prompt (cmd) and run as administrator. Enter cd C:\Apache24\bin - this will change the directory to the "bin" folder.
  4. To install Apache, enter httpd.exe -k install.
  5. Windows Start → Services → find Apache24 and hit Start the service. Alternatively, open Services by entering services.msc into the cmd.
  6. Open your browser and go to 127.0.0.1. If it works, you should see a webpage that says "It works!".

// Installing MySQL

Follow this YouTube tutorial.

  1. Go to MySQL Community Downloads Windows Installer and download the second installer (the one that has a bigger file size).
  2. Double click the .msi file. Choose Custom setup. Navigate the drop downs and select these to be installed: MySQL Server 8.0.46 - X64, MySQL Workbench 8.0.47, X64, MySQL Shell 8.0.46 - X64 by clicking on it and moving it to the right using the green arrow. Click Next then Execute.
  3. Click Next and don't change anything until you get to Apply Configuration and click Execute. Do set your password at the Accounts and Roles page.
  4. Select Start the Workbench and Shell after setup then Finish, make sure that both actually opens.
  5. Locate this path in File Explorer: C:\Program Files\MySQL\MySQL Server 8.0\bin. Start → Edit the system environment variables → Environment Variables → System Variables → double click Path → Click New and paste the path, then OK.
  6. In cmd, enter mysql --version to verify that it's installed. Enter mysql -u root -p to run MySQL.

// Installing PHP

PHP

Follow this YouTube Tutorial.

  1. Go to PHP Downloads, select version 8.3, and under Current Stable click Windows downloads. Under VS17 x64 Thread Safe, select Zip.
  2. Extract the folder, rename it to php-8.3.32 (or whatever version you have) and move it to C: drive. NOTE: this is the PHP folder I will be referencing from now on. Whatever it is that you named your folder to be, you should replace all code containing php-8.3.32 with that.
  3. Copy the folder address C:\php-8.3.32. Start → Edit the system environment variables → Environment Variables → System Variables → double click Path → Click New and paste the path, then OK.
  4. To verify installation, open cmd and enter php --version.

PHP packages containing extensions

Official Documentation can be found here.
For windows, the extensions are .dll files located in the ext folder at C:\php-8.3.32\ext.

// Media Processing Software

Composer

Official documentation here. Follow this YouTube tutorial.

  1. Download and run Composer-Setup.exe. Install for all users.
  2. No need to change anything, just Click Next until you get to Finish.
  3. To verify installation is successful, open cmd and enter composer.

Git

Official documentation here.

  1. Download Git from here and run it.
  2. Follow the set up wizard to finish installation but you don't have to change anything. I personally use VS Code so I chose that as the default editor. I went with MinTTY (which is the default) instead cmd because supposed it has a better user experience but I don't think it really matters which one you pick.
3. Installing Providence

Official Collective Access Documentation: Installation.
I find that the official guide is written pretty clearly for the most part, so I'd say just try your best to follow it. Below are some notes for parts that may be confusing.

// Configuring PHP

  • Open C:\php-8.3.32. Rename php.ini-development to php.ini. This is the file that you will be editing.
  • Open php.ini and follow the official guide to make changes as needed. For upload_max_filesize, the default is 2M meaning 2 Megabytes. Per php.net, the available options are K (for Kilobytes), M (for Megabytes) and G (for Gigabytes), and are all case-insensitive.
  • In php.ini, find ;extension_dir = "ext" and replace with extension_dir = "C:\php-8.3.32\ext".
  • Remember that long list of PHP packages with extensions found under System Requirements? Now find them in php.ini and remove the semicolons in the front to activate them.

// Installing Providence

  • For step 1 setting up an empty MySQL database, use the MySQL Workbench.
    • In MySQL Workbench, open the local instance. From the top, click Create a new schema in the connected server. Give the schema a name; I chose providence_database.
    • You can skip all the login information stuff since that was already done when installing Apache.
    • The Apache local server index.html can be found here: C:\Apache24\htdocs. (To see it running in your browser, type 127.0.0.1 into the browser address bar.) Inside the folder, move the both the unzipped Providence and Pawtucket folders there. I renamed them to providence and pawtucket, respectively.
  • You can skip step 2.
  • Before doing step 3, make sure Apache is linked with PHP. Open C:\Apache24\conf\httpd.conf. (See Stack Overflow Reference.)
    • Under the servername section, put ServerName localhost. Change DirectoryIndex index.html to DirectoryIndex index.php index.html.
    • At the very end of the file, add these each as its own line: LoadModule php_module "C:\php-8.3.32\php8apache2_4.dll", <IfModule php_module>, AddHandler application/x-httpd-php .php, AddType application/x-httpd-php .php .html, PHPIniDir "C:\php-8.3.32", </IfModule>
  • For step 3, open the providence folder, which should be located at C:\Apache24\htdocs\providence.
    • Inside the folder, find setup.php-dist and rename it to setup.php.
    • Then, open setup.php in Notepad (or VS Code or whatever program of your choosing) and make changes as needed. Be sure to change the following: my_database_user to the default username root, my_database_password to whatever your MySQL password is, name_of_my_database to the name of the database you made in step 1. Add your admin email too.
    • At the end of all the __CA_DB_ stuff, add this: define('__CA_URL_ROOT__', '/providence');. You need to do this because all the providence files are located inside the providence folder, which is inside the C:\Apache24\htdocs root folder.
  • You can skip step 4 because that's a Linux thing I think. Don't worry about it for Windows.
  • For step 5, make sure that Apache is running by going into the cmd, enter services.msc, and click on Apache and Start the service. In your browser, go to http://localhost/providence/install/. If luck is on your side it should just work. I recommended restarting Apache after you make changes to multiple files.
    • So unfortunately the first time I tried to go to http://localhost/providence/install/ I got this error:
      Fatal error: Uncaught RuntimeException: Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.4.0". You are running 8.3.32.
    • I think this is because the latest version of CollectiveAccess 2.0.11 somehow forces you to use PHP 8.4, even though the official documentation said it's not fully validated yet and imply that 8.2 and 8.3 should be compatible as well.
    • A workaround is to open C:\Apache24\htdocs\providence\vendor\composer\platform_check.php and add return; right under <?php, forcing it to run. Not the best practice but it works...
  • Anyways that fixes it. For installation profile, I went with PastPerfect 5.0 because it's the only one I've heard of lol. Make sure you do research on which profile you want, because once you installed it, there is no way to change it.
  • To access Providence, you have to first start running Apache, which can be accessed by entering services.msc into cmd. Then, in your browser, go to http://localhost/providence. You can bookmark this link for easier access.
  • NOTE: All this is to get Providence working, which is the back-end of CollectiveAccess. The front-end, Pawtucket, is its own separate thing.

// Troubleshooting Providence

So, ideally, after all that trouble, Providence should be working just fine. Unfortunately that wasn't the case for me. The issue I encountered was that when I create a new object and try to upload a media representation, the image never gets processed. When I try to upload an image, it shows that the image is uploaded, but there's no thumbnail preview. And when I click save, it just turns blank, as if the image was never uploaded. From what I gathered from the CA forum, it seems like this might be a Windows issue. (Remember, CA isn't developed for Windows.) I haven't been able to figure out how to fix the issue, but I did find a workaround.

The Issue

  • So, when I try to upload an image, a copy is successfully created in C:\Apache24\htdocs\providence\uploads\~admin. Note that the last folder, ~admin, is based on your username. I changed my username from the default administrator to admin; so if your username is blue, the folder should be called ~blue.
  • When I click save, what should've happened was that a copy* of the image should've been created in C:\Apache24\htdocs\providence\media\collectiveaccess\images as well. Instead, nothing happens. That folder remains blank. (* Note that when I say copy, it's not really an accurate description. Whatever image processor you're using should've made copies of the image and chopped it up into a bunch of different ones for the zoomable viewer built into CA.)
  • Some relevant files to investigate include: setup.php, media_processing.conf, php.ini, and app.config.
  • Again, I haven't figured out how to fix this. Someone take on the mantle from me PLEASE.

The Workaround

Thankfully, there's a pretty convenient workaround.

  • Open up C:\Apache24\htdocs\providence\uploads. Inside the folder titled ~admin, copy and paste the images you want to upload there. (Again, the folder name depends on your username; mine is admin.)
  • Inside CollectiveAccess, when you go to IMPORT → Media, you should see the images listed under Directory to import. Select the images you want to upload, and voilà, it works!
4. Extensions/Plugins

NOTE: You should finish installing CollectiveAccess BEFORE PROCEEDING WITH THE FOLLOWING STEPS. The PHP set ups will only make sense once you've completed the Install Providence section.

// GraphicsMagick - I COULDN'T GET THIS TO WORK THIS IS AS FAR AS I GOT

Official documentation here.

  1. Get GraphicsMagick here. Go into graphicsmagick-binaries and download the newest release. I went with GraphicsMagick-1.3.46-Q16-win64-dll.exe. Run the installer; you don't need to change any of the default settings.
  2. To verify successful installation, open cmd and enter gm. You can also try entering gm convert logo.jpg win:, which should display the GraphicsMagick logo in a window.
  3. Now to install php-gmagick, as far as I know the only way to get it is from PECL. It would seem like the latest Windows version is version 1.1.6RC1 from 2013. I went with 5.6 Thread Safe (TS) x64 so let's just hope and pray that it works.
  4. Unzip the folder and copy php_gmagick.dll into the C:\php-8.3.32\ext folder.
  5. Locate wherever you installed GMagick and copy the path. For me, it's located at: C:\Program Files\GraphicsMagick-1.3.46-Q16. Go to Start → Edit the system environment variables → Environment Variables → System Variables → double click Path → Click New and paste the path, then OK.
  6. Open C:\Apache24\htdocs\providence\app\conf\external_applications.conf. Find and replace graphicsmagick_app = [/usr/bin/gm, /usr/local/bin/gm] with graphicsmagick_app = C:/Program Files/GraphicsMagick-1.3.46-Q16/gm.exe. (Reference.)
  7. Open C:\Apache24\htdocs\providence\app\helpers\mediaPluginHelpers.php. In any function pertaining to GraphicsMagick, change /dev/null to /$null.
  8. Open up php.ini in the PHP folder and add this: extension=gmagick. In the file you'll find a big section of extension=, I added it there.
  9. Yeahhhh so I couldn't get this to work. My theory is that the windows php package is just way too old.

// ImageMagick - Works but Slower than GD

Tips:

  • Without any additional extensions or plugins, CollectiveAccess should still be able to process still images with the native libGD plugin. It's just really slow.
  • In "C:\Apache24\htdocs\providence\app\conf\app.conf", you can change dont_use_imagick = 0 to be equal to 1 to force CollectiveAccess to stop using imagick. This is a good way to troubleshoot and make sure that the media-processing-process itself is working fine.
  • You can see the status of your plugins by going MANAGE → Administration → CONFIGURATION CHECK.

How to Imagick

  1. There are two components: ImageMagick and its PHP plugin Imagick. Get ImageMagick here and the PHP package here. Since I have PHP 8.3.32 built with Visual C++ 2019 Thread Safe x64, I went with ImageMagick-7.1.2-27-Q16-HDRI-x64-dll.exe and php_imagick-3.8.1-8.3-ts-vs16-x64.
  2. Run the ImageMagick installer. After installation, locate where it was downloaded at (probably C:\Program Files) and move folder to C: drive. Rename the folder to ImageMagick. The final file path should be C:/ImageMagick.
  3. Go to C:/ImageMagick/module. Inside, you should see two more folders: coders and filters. Move ALL contents of coders and filters into the main C:/ImageMagick folder. The modules folder should now be empty and you can delete it.
  4. Go to Start → Edit the system environment variables → Environment Variables → System Variables → New → set variable name to MAGICK_CODER_MODULE_PATH and value to C:\ImageMagick. (See this for reference.) Under System Variables, open Path → New → enter the same path C:\ImageMagick.
  5. Open C:\Apache24\htdocs\providence\app\conf\external_applications.conf. Find and replace imagemagick_path = [/usr/bin, /usr/local/bin, /opt/homebrew/bin] with imagemagick_path = C:/ImageMagick. (See this for reference.)
  6. Unzip and open the PHP package. Find php_imagick.dll and copy it into the C:\php-8.3.32\extfolder.
  7. Open C:\php-8.3.32\php.ini and add extension=imagick.
  8. That should be it. Open CollectiveAccess and go to MANAGE → Administration → CONFIGURATION CHECK. For me, ImageMagick still shows Didn't load because ImageMagick executables cannot be found. No idea what's up with that. Here's the thing, Imagick takes really long to process an image. Like, 3 minutes and 34 seconds to process a 1.05 MB image. For a file about the size of 450 KB, GD only took 4 seconds whereas Imagick took 24 seconds. Apparently this is normal for Windows: "ImageMagick process is very slow and libGD is preferred for speed, but it requires much more memory."
  9. To determine if an image is processed by GD, you can check the metadata. Go to C:\Apache24\htdocs\providence\media\collectiveaccess\images\0. Find an image that ends with thumbnail, right click it, and open with Notepad. You'll see a bunch of gibberish which is normal. If the image is indeed processed by GD, then at the top of the file you should see something like GD-JPEG. If you don't see it and you have Imagick available, then most likely the image was processed by Imagick.

NOTE: So I found this Stack Overflow tutorial. When I followed it and replaced the original ImageMagick CORE files with the PHP ones, it didn't work. When I copied ALL .dll files from the PHP package and replaced the original ImageMagick files, it worked. That didn't make any difference in image processing speed and I honestly don't know what difference it made at all. So to play it safe, I reverted all this. So basically what I'm saying is you probably shouldn't try this.

5. Setting Up Pawtucket

Official documentation can be found here. Reference this tutorial from the CA forum.

  1. At this point you should have Providence fully functional. Make sure that your Pawtucket files are inside of a folder named pawtucket located at C:\Apache24\htdocs\pawtucket.
  2. Inside the pawtucket folder, locate setup.php-dist and rename it to setup.php.
  3. Open C:\Apache24\htdocs\pawtucket\setup.php and make changes as needed, identical to what you have done when installing Providence. Be sure to change the following: my_database_user to the default username root, my_database_password to whatever your MySQL password is, and name_of_my_database to the name of the database you made back in step 1 of Installing Providence. Add your admin email too.
  4. At the end of all the __CA_DB__ stuff, add this: define('__CA_URL_ROOT__', '/pawtucket');. You need to do this because all the Pawtucket files are located inside the pawtucket folder, which is inside the C:\Apache24\htdocs root folder.
  5. Open C:\Apache24\htdocs\pawtucket\app\conf\global.conf. Locate ca_media_url_root = <ca_url_root>/media/<app_name> and change it to ca_media_url_root = /providence/media/<app_name>. Next, change ca_media_root_dir = <ca_base_dir>/media/<app_name> to ca_media_root_dir = C:/Apache24/htdocs/providence/media/<app_name>. IMPORTANT: To understand why this step is necessary, please read the bullet points regarding global.config in the "Troubleshooting Pawtucket" subsection.
  6. To access Pawtucket, first start running Apache, which can be accessed by entering services.msc into cmd. Then, in your browser, go to http://localhost/pawtucket. You can bookmark this link for easier access. If luck is on your side it should just work.

Troubleshooting Pawtucket

  • After you make changes to setup.php or global.conf, make sure to clear cache by deleting everything in C:\Apache24\htdocs\pawtucket\app\tmp before accessing pawtucket again.
  • Two errors you might encounter:
    It looks like the log directory is not writable by the webserver. Please change the permissions of __CA_APP_DIR__./log (or create it if it doesn't exist already) and enable the user which runs the webserver to write to this directory.

    It looks like the media directory is not writable by the webserver. Please change the permissions of C:/Apache24/htdocs/pawtucket/providence/media/collectiveaccess (or create it if it doesn't exist already) and enable the user which runs the webserver to write to this directory.
  • To fix the first error: Open C:\Apache24\htdocs\pawtucket\setup.php. Locate the function if (!defined("__CA_LOG_DIR__")). Comment out the entire thing by adding // in front of each line. (This worked for me and I have no idea why.)
  • If you followed step 5 of this section, the second error shouldn't occur. However, if that didn't fix it, the issue concerns this file: C:\Apache24\htdocs\pawtucket\app\conf\global.config. Open this file and look for the variables mentioned in the following bullet points.
    • ca_media_url_root - This is the URL that the browser uses. It's what fills in the <img> tag in HTML; you can right click and inspect the page to look at the code.
    • ca_media_root_dir - This is where the files exist on your local machine. In this case, C:\Apache24\htdocs\providence\media.
    • <app_name> - when pawtucket runs, this basically tells the system to access all the stuff stored in the collectiveaccess folder.
    • The default value for __CA_BASE_DIR__ seems to be directing to C:/Apache24/htdocs/pawtucket. The comments in global.config says that __CA_BASE_DIR__ is imported from setup.php. However, when I look inside setup.php — checking both the one associated with pawtucket and the one with providence — __CA_BASE_DIR__ is nowhere to be found. I have absolutely no idea why it's like this.
    • From what I understand, setting ca_media_root_dir to be equal to C:/Apache24/htdocs/providence/media/<app_name> merely provides a temporary fix. It gets Pawtucket running locally, but will most likely cause trouble when you try to actually host the website online, since it's directly linking to your local machine's C:Drive. (I don't plan to host my CollectiveAccess project any time soon, so I'm just not gonna worry about this for now.)

Objects not showing up in Pawtucket?

  • In Providence, open an object. Click on ADMIN INFO. Make sure that the Access is set to "accessible to public". Open the MEDIA tab, click Edit, and make sure that the media representation is set to "accessible to public" as well.
  • The default option for an object is set to "not accessible to public". If you wanna change it, go to MANAGE → Lists & vocabularies. Search for access_statuses and you should see three identifiers: internal_only, restricted_public_access, and public_access. To set whichever one you want as the default option, click the Edit icon and change "Is default?"" to Yes.
6. General Tips

// Some tips and tricks when using CollectiveAccess

  • There is a demo at https://demo.collectiveaccess.org/
  • Here's a tutorial on how to use CollectiveAccess made by the Association of Nova Scotia Museums.
  • After creating new entities, if they're not showing up in "related entities" when editing objects, go to Manage → Administration → Maintenance and select "rebuild search indices".
  • When you edit an object, you can add a date and choose date type. To change the default type, do this:
    • Go to Manage → Administration → Metadata Elements. Click the Edit icon of the Dates label. Scroll all the way down to the "Sub-elements" section. Edit Type (date_types) [List]. Find "Use list default when value is null?", check the box, and save the change.
    • Go to Manage → Lists & vocabularies. In the Hierarchy viewer, find Date Types (date_types). Open whichever one you want to set as the default (e.g., Date published) and change "Is default?" to Yes.
    • The changes most likely won't be immediately reflected. You might need to do Manage → Administration → Maintenance → Rebuild hierarchical indices.

How to implement an object identifier naming system when mass importing media

  • Reference this. For my specific project, I wanted to create a naming scheme where the object identifier is word.NUMBER. Example: When I import two images, I want the object identifiers to be automatically named image.1 and image.2. Don't ask me how the incrementing number code works I stole it from here.
  • Open C:\Apache24\htdocs\providence\app\conf\multipart_id_numbering.conf. Save the default ca_objects by commenting it out, then add this:
    click to expand code 
    ca_objects = {
    __default__ = {
        separator =,

        elements = {
            prefix = {
                type = CONSTANT,
                # value is set equal to whatever phrase you want to appear before the incrementing numbers
                # replace word with your desired phrase each time before importing media
                value = word,

                editable = 0
            },

            num = {
                type = SERIAL,
                width = 6,
                description = _(Object number),
                
                # supposedly you shouldn't need the following three when using providence version 2.0 and above
                # but it doesn't work when I delete this so IDK man
                table = ca_objects,
                field = idno,
                sort_field = idno_sort

                editable = 1
            }
        }
    }
},
  • For some reason, when the above code is active, it prevents you from manually editing the object identifier. To fix this, comment out the new code and uncomment the original one. A bit of a hassle, but I rather do this than manually naming 50 images every time I mass import media LOL.