Test drive

The quick and leazy way to test Pocket Archive is to use the provided Docker Compose setup in the source code:

Setting up the container

Note: this setup uses ports 5000 and 9000 on your host machine. If those are already in use, stop the existing processes or modify the compose file before starting it.

git clone --depth=1 https://git.knowledgetx.com/scossu/pocket_archive.git
cd pocket_archive/docker
docker compose build
docker compose up -d

This starts three containers:

  • A pkar-submission container, that accepts submissions from command line and remotely via drop box;
  • A pkar-admin container, that runs the admin interface;
  • A pkar-pres container, running an HTTP server for viewing the generated presentation site.

These containers mimic a typical production setup, with three separate services deployed to different machines with different access permissions. (It is NOT a production-grade setup, though!)

Using the command line tool

Enter the submission container:

docker exec -it pkar-submission /bin/sh  # Note: there is no bash.

Then:

# Initialize the archive if this is your first run or if you wanna start over
# NOTE: it looks like some terminals don't display the confirmation prompt
# immediately. Just type `yes` and hit enter in any case.
pkar init
# Deposit a provided example
# Replace the parts in brackets with the current folders in your file system
pkar deposit /usr/local/lib/luarocks/rocks-[Lua version]/pocket_archive/[PKAR version]/examples/sip/pkar_submission-postcard.csv
# Show a list of resource IDs of a certain type
pkar list -t document
# Dump RDF for one resource
# [resource ID] is the resource ID shown by previous command, without the
# `par:` prefix
pkar dump-res [resource ID]

# Generate static site from archived data
pkar gen-site

See the Utilities page for more information on the CLI tool.

Browsing the generated presentation

Exit the container and point your browser to http://localhost:9000 to view the generated presentation site.

In the current setup, which is aimed at simplicity for demonstration's sake, the files are locked in the Docker volume and not easily accessible from the host. In a different setup, where Pocket Archive writes directly to the filesystem, the site can be viewed without an HTTP server by pointing the browser directly at the files.

Using the drop box feature

Next, test the drop box from the host system.

The volumes/dropbox directory relative to the docker directory you are in is a "hot folder" that accepts submissions. This is likely the preferred way for your archive's depositors to deposit submissions.

Download the example SIP file, unpack it, and look into the sip directory. Drop the demo directory into the drop box. Then, drop the pkar_submission-demo.csv too. Note that these two steps must be done separately and in this sequence. The laundry list file always comes last in a submission.

The CSV file will disappear after a moment. That is because the drop box monitor was instructed to clean up the SIPs that it successfully completes.

It was also instructed to rebuild the site for every new submission. In fact, if you return to your browser back to the http://localhost:9000 page, you should notice the new resources and the new collections section from the second submission.

Accessing the admin interface

Pocket Archive comes with a simple admin interface to inspect submissions and perform one-off updates on resources. Visit http://localhost:5000/admin/ to access the interface.