Installation and set up

This has been tested on Linux only. It's not guaranteed to work on other systems at the moment.

System prerequisites

  • A build environment (at least Git, libc, a C compiler, and Make)
  • UUID library (uuid/uuid.h - util-linux or linux-headers in most distros)
  • xxhash development package
  • lmdb development package
  • libvips development package
  • Lua 5.4 development package (lua-dev in some distros)
  • Luarocks 5.4

If using Arch Linux:

pacman -Syu
pacman -S base-devel util-linux-libs git xxhash lmdb libvips lua luarocks

Install Volksdata & Pocket Archive

Pocket Archive and Volksdata are still alpha and not in the Luarocks artifact repo yet, so the rocks must be installed manually for the time being.

Installing locally or in a dedicated container is strongly recommended at this stage.

When Pocket Archive will get into beta status and be published on Luarocks, the commands below will be replaced by a one-line command. Until then...

# Note: tested on Archlinux. Other distros (especially Alpine) may need tweaks.
eval $(luarocks path)
luarocks install --local debugger  # Not in dependencies file but temporarily required
git clone --recurse-submodules https://git.knowledgetx.com/scossu/volksdata_lua.git
cd volksdata_lua
luarocks build --local
lua test.lua  # optional
cd ../
git clone --recurse-submodules https://git.knowledgetx.com/scossu/pocket_archive.git
cd pocket_archive
luarocks build --local
# Add Luarocks paths to your login script
luarocks path >> ~/.bashrc
# Penlight.clonetree is not working properly. A pull request is in progress:
# https://github.com/lunarmodules/Penlight/pull/496
# In the meantime, clone the fork and install from the local repo:
cd ../
git clone https://github.com/scossu/Penlight.git
cd Penlight
git checkout clonetree
luarocks build --local
cd ../pocket_archive

Run demo submission

Initialize the archive first:

pkar init

This, after user confirmation, will create the required folders and database file in the archive root (a temporary folder by default). Then:

pkar submission test/sample_submission/pkar_submission.csv

Generate static site from archive

pkar gen-site

Will generate the static site in out/http/. These files can be viewed on a local machine with only a browser (point to index.html), packaged and sent to someone else to browse on their own machine, or served remotely with a very simple static HTTP server. darkhttpd is provided here for convenience:

cd ext/darkhttpd/
make
cd -

Serve the site:

./ext/darkhttpd/darkhttpd out/html

(see more options with darkhttpd --help)

Point your browser to localhost:8080 and enjoy.

Setup

Configuration

The configuration directory provided by the Luarocks package and in the Git repo (config folder) should be copied to a user-defined location and pointed to when running Pocket Archive (see "Environment variables" below). The configuration can thus be modified without being overwritten by a Pocket Archive update.

The Configuration guide describes the configuration details.

Environment variables

The following environment variables are available to modify the application behavior:

  • PKAR_ROOT: Root of Pocket Archive data. It defaults to ..
  • PKAR_ORES: Directory of opaque resources (content files). It defaults to ${PKAR_ROOT}/data/ores.
  • PKAR_DRES: Directory of descriptive resources (metadata). It defaults to ${PKAR_ROOT}/data/dres.
  • PKAR_CONFIG_DIR: configuration directory. This should be a directory containing the model directory with the content mode configuration and app.lua with general application configuration. It defaults to the config directory installed by Luarocks.