Configuration
Configuration directory
Each running instance of Pocket Archive must refer to a configuration
directory. This is a directory containing configuration files for various
aspects of the application. The Pocket Archive process looks for the
PKAR_CONFIG_DIR environment variable which should point to the configuration
directory intended for the purpose. If that is not set, Pocket Archive will use
the stock configuration that comes with the installation package. That is fine
only for an initial test of the software.
To properly setup Pocket Archive, copy the examples/conf directory from the
installation location (look at luarocks show pocket_archive to get the
base install directory) to a writable location, and set the PKAR_CONFIG_DIR
environment variable to that location.
Multiple instances and configurations
A "running instance" of Pocket Archive is intended as an operating system
process running any part of the Pocket Archive suite. Pocket Archive has
several executable components, all of which use the same configuration
framework. That applies to commands entered with the pkar CLI
utility, the admin interface running on HTTP, the
submission watchdog, the Lua API, etc.
It is possible to run multiple instances of Pocket Archive from the same code base and point them to different configurations. This allows to run multiple archives on the same machine without installing multiple copies of the software.
Example configuration
The examples/ directory in the Pocket Archive installation contains a
complete and functional configuration. This is the stock configuration that
is used if the PKAR_CONFIG_DIR variable is not set. It strives to be a good
starting point for an initial Pocket Archive installation, but repository
managers can choose to alter it radically, or start from scratch.
One thing to note is that some app.lua configuration options depend on the
content model, and vice versa, so, when modifying configuration files one must
take care of cross-checking schema names, etc.
Configuration sections
The configuration folder expects to find several files and folders in specific locations. These are key to running the software.
All configuration files are Lua data files. All of the Lua features can be used in these files, however, one should avoid writing complex logic or admitting untrusted external content into these files, which can pose a security threat. Sticking to plain, scalar values is a safe option.
app.lua
This is where the core application options are set. The stock file contains all the used options, either commented out or explicitly set, accompanied by a brief description.
Some options can be left unset, in which case Pocket Archive will use a system default. The non-mandatory options are commented out in the example schema and some information about their default behavior is included in the comments.
The most important value to set here is the ROOT variable towards the top of
the file. This sets the directory for all Pocket Archive data. Other options,
such as core.root and pres_gen.out_dir, may use this variable as a base, or
can be set to entirely different paths.
Content model
The content model is configured in the schema/ directory under
$PKAR_CONFIG_DIR, which contains one Lua data file for each schema
definition. The file names are critical because they are used by Pocket Archive
to discover the defined schemata. For example, the video schema should be
defined in $PKAR_CONFIG_DIR/schema/video.lua.
The schema configuration file is documented in the Content model setup page.