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)
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

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/html/. 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

PKAR_CONFIG_DIR should be set to point to the configuration directory. If not set, the examples/conf directory installed with Pocket Archive by Luarocks is used. This is never a good choice except for testing and quick evaluation, because the file is overwritten, and any changes to it reverted to the stock setup, every time Pocket Archive is installed or updated. See the configuration section for further instructions.