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.

Note for Apple Silicon users: if you are running this on an Apple M* (Silicon) CPU (as most recent Macs are), ensure that you have the DOCKER_DEFAULT_PLATFORM environment variable set to linux/arm64, or otherwise ensure that you build an ARM64 image. Otherwise, the Docker image will be extremely slow and may not support mmap() which is a precondition for Pocket Archive to run. The method described below uses pre-built images that are available for the x86_64 and ARM64 architectures.

Note: The main git and Docker image repository is temporarily disabled due to technical issues. Pre-built Docker images are not currently available. In order to build the Docker compose environment, build the Docker images from source files instead:

git clone https:codeberg.org/scossu/pocket_archive.git
cd pocket_archive/docker
docker build -f pkar.Dockerfile -t git.knowledgetx.com/ktx/pocket_archive:latest ..
docker compose up -d

THIS METHOD IS TEMPORARILY DISABLED. Use the commands above.

Create the project folders and download the Docker compose file:

mkdir -p pkar_test_drive/volumes/dropbox
cd pkar_test_drive
wget https://git.knowledgetx.com/ktx/pocket_archive/raw/branch/master/docker/docker-compose.yaml
# Alternatively:
#curl -O https://git.knowledgetx.com/ktx/pocket_archive/raw/branch/master/docker/docker-compose.yaml
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.

The Pocket Archive containers are the release images published on the Packages repository, which are tested and more stable than images built from the master branch.

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
pkar init
# Deposit a provided example
# Replace the parts in brackets with the current folders in your file system
cd /usr/local/lib/luarocks/rocks-[Lua version]/pocket_archive/[PKAR version]/examples/sip
pkar deposit 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

As a shortcut, if you are rebuilding the containers and re-initializing the archives often, and/or you don't want to interact with the CLI inside the container, you can pass the following command inside the docker directory to wipe the archive without having to enter the container:

docker-compose run submission 'echo "yes" | pkar init'

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.