How it works

Boxitory currently implements just filesystem box provider that reads all data from filesystem and thus requires strict folder structure.

Box files on filesystem

There must be one home folder for all boxes with subfolders for each box type. Individial box versions must be named {name}_{version}_{provider}.box.

See example below:

$ tree test_repository/
test_repository/
├── f25
│   ├── f25_1_virtualbox.box
│   └── f25_2_virtualbox.box
│   └── f25_3_virtualbox.box
├── f26
│   ├── f26_1_virtualbox.box
│   ├── f26_2_virtualbox.box

Http interface

Server starts on port 8083(default) and boxes can be requested on /{box_name} for example:

$ curl http://localhost:8083/f26
{
  "name": "f26",
  "description": "f26",
  "versions": [
    {
      "version": "1",
      "providers": [
        {
          "url": "sftp://my_box_server:/tmp/test_repository/f26/f26_1_virtualbox.box",
          "name": "virtualbox"
        }
      ]
    },
    {
      "version": "2",
      "providers": [
        {
          "url": "sftp://my_box_server:/tmp/test_repository/f26/f26_2_virtualbox.box",
          "name": "virtualbox"
        }
      ]
    }
  ]
}

Latest version (since v1.3.x)

Latest version number for given box can be requested on /{box_name}/latestVersion. This returns just number of latest version:

$ curl http://localhost:8083/f25/latestVersion
3

Box version descriptions (since v1.3.x)

Each box version can have it's own description, which is then returned on HTTP API. Descriptions are stored in file descriptions.csv, which has to be placed beside .box files.

$ tree test_repository/
test_repository/
├── f25
│   ├── descriptions.csv
│   ├── f25_1_virtualbox.box
│   ├── f25_1_virtualbox.box

Content of the file is in CSV format with ;;; used as separator.

version;;;description
1;;;this is description of version 1
2;;;this is description of version 2

Then resulting JSON will look like this:

$ curl http://localhost:8083/f25
{
  "name": "f25",
  "description": "f25",
  "versions": [
    {
      "version": "1",
      "description: "this is description of version 1",
      "providers": [
        {
          "url": "sftp://my_box_server:/tmp/test_repository/f26/f26_1_virtualbox.box",
          "name": "virtualbox"
        }
      ]
    }
    ...
  ]
}