Configuration Internals

This setting describes the internals of Camelot’s data storage locations and configuration files. This is intended as a resource for very specialised use cases and for IT professionals.

Camelot has two directories: one for configuration, and one for data storage. The location of these directories depends on the OS.

Data locations

By default, Camelot stores all data under the current user’s home folder for the operating system.

Data

  • Windows: %LOCALAPPDATA%\camelot

  • MacOS: $HOME/Library/Application Support/camelot

  • Linux: $HOME/.local/share/camelot

Configuration

  • Windows: %APPDATA%\camelot

  • MacOS: $HOME/Library/Preferences/camelot

  • Linux: $HOME/.config/camelot

Data directory

The data directory will, by default, contain three subdirectories: Database, Media and FileStore. Database is an Apache Derby database. Imported media is not stored in the database, but in the Media folder. Finally, the FileStore contains files for the Survey’s “Related files” feature.

A custom data directory can be set using the CAMELOT_DATADIR environment variable. The Database and Media directories will be created (if necessary) and stored within that nominated directory. If CAMELOT_DATADIR is not set, Camelot will fall-back to using the standard locations (as above). The usage of CAMELOT_DATADIR can be selectively overridden by specifying paths to alternate directories, as described below.

Each of the Database, Media and FileStore directories should be backed up routinely.

Config directory

config.json

config.json is the global camelot configuration file. Some values in this file can be set via the administration interface in Camelot. Care should be taken if editing this file manually.

config.json supports the following properties:

  • datasets: describes the datasets configured. Each key is the dataset name, whose value is a dataset object. A dataset object has two keys:

    • name: the display name of the dataset. This value is a string.

    • paths: the paths for the dataset. The value of paths is an object. The following dataset-level paths are supported:

      • media: the folder path to the directory where media is to be stored.

      • database: the base to the folder which is to contain a Database directory.

      • filestore-base: the folder path to where Camelot should keep its uploaded survey files.

      • backup: the folder path to where Camelot stores backups.

  • paths: describes the various application-level paths to be used by Camelot. The following paths are supported:

    • log: the folder path to where Camelot should store its logs.

    • application: the folder path to where Camelot can find a Camelot .jar file.

    • root: the root folder which Camelot can search for external data. For example, for scanning for bulk import

  • server: an object describing Camelot server-specific configuration

    • http-port: a number describing the port to run Camelot’s HTTP server on (default: 5341)

    • media-importers: the number of concurrent threads for importing media (default: 4)

    • max-heap-size: a number representing the desired maximum heap size (in MB) for the Camelot server JVM (default: <blank>)

    • jvm-extra-args: additional arguments you wish to pass to java when starting the Camelot server. (default: <blank>)

  • java-command: the path to the java executable on this system (default: java)

  • open-browser-on-startup: whether the Camelot administration software should automatically view Camelot after startup (default: true)

  • send-usage-data: whether to publish anonymous usage data to the Camelot team for helping to improve the software (default: false)

  • species-name-style: the style to show species names in the Camelot user interface; options are scientific or common-name (default: scientific)

All of the above properties are optional and default values will be used where not specified.

In practice, a simple config.json might look as follows:

{
  "datasets": {
    "default": {
      "name": "Default",
      "paths": {
        "media": "/path/to/ext-hdd/Media"
      }
    }
  },
  "paths": {
    "log": "/path/to/ext-hdd/Logs"
  }
}