# 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:

```bash
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...

```bash
# 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:

```bash
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

```bash
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:

```bash
cd ext/darkhttpd/
make
cd -
```

Serve the site:

```bash
./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](./config.md) 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.