Create A New Repository¶

Queenbee repositories are essential to store and share Plugins and Recipes that can be executed as Jobs.

A Repository is a folder that consists of an index.json index file and a series of packaged Plugins and Recipes. It is used to manage Recipe dependencies (which can be Plugins or other Recipes).

In this section we will show you how to create a repository folder on your machine. You can then use this folder to develop multiple Plugins and Recipes that depend on each other.

Getting Started¶

We will need a plugin stored in folder for this tutorial. You can follow the Plugin Guide if you do not have a plugin folder at hand.

Folder Structure¶

We will create a new queenbee repository in a folder called local-queenbee-repo. To do so run the following command:

queenbee repo init local-queenbee-repo

This command will create the folders and initialize an empty index.json file. Here is what the folder should look like:

local-queenbee-repo
├── recipes
├── plugins
└── index.json

You will notice that the recipes and plugins folders are empty. This is where we will save the packaged recipes and plugins. You will also notice that the index.json file also doesn’t show much information yet:

{
    "generated": "2020-05-19T07:32:02.599910",
    "plugin": {},
    "recipe": {}
}

Adding Packages¶

Let’s add some packages to our repository. To do so we will package the Plugin we created in the Plugin Guide (or any other plugin you might have created).

queenbee plugin package path/to/plugin --destination local-queenbee-repo/plugins

If you are using the Plugin we created in the Plugin Guide the path/to/plugin is the energy-plus Plugin folder.

You should now see a new file has been added to your repository.

local-queenbee-repo
├── plugins
│   └── energy-plus-0.1.0.tgz # Name will change if you used another plugin
├── recipes
└── index.json

Repository Indexing¶

The repository index file (index.json) is the “brain” of the repository. This is where package names, versions and other basic metadata is exposed for clients (ie: queenbee cli) to search for packages and find their download paths.

The repository index is created by crawling the repository folders for packages and updating the package information in the index as needed. Let’s give it a try:

queenbee repo index local-queenbee-repo

If you open your index.json file you will see that is has changed to something like this

Note

Package name, version etc… will change according to the plugin packaged in the previous step.

{
"generated": "2020-05-19T07:46:49.803320",
"metadata": {
    "name": "local-queenbee-repo",
    "description": "A Queenbee package repository",
    "source": null,
    "plugin_count": 1,
    "recipe_count": 0
},
"plugin": {
    "energy-plus": [
    {
        "name": "energy-plus",
        "tag": "0.1.0",
        "app_version": "9.0.1",
        "keywords": [
            "energyplus"
        ],
        "maintainers": null,
        "home": "https://energyplus.net",
        "sources": [
            "https://github.com/nrel/energyplus"
        ],
        "icon": "https://energyplus.net/sites/default/files/eplus_logo.png",
        "deprecated": null,
        "description": "A plugin to run EnergyPlus functions",
        "url": "plugins/energy-plus-0.1.0.tgz",
        "created": "2020-05-19T07:42:20.496003",
        "digest": "bff20aae42e62aa084f0f08bf3833674e2bfccd0c6309f65848f089f402716f5",
        "slug": "local-queenbee-repo/energy-plus",
        "type": "plugin"
    }
    ]
},
"recipe": {}
}

There are a few interesting things going on here:

The plugin package is nested under the plugin key
The plugin name key points to a list of Plugin Versions. In this example the key is energy-plus.
The Plugin Version url key points to the package file relative to the index.json file
A digest is generated for each Plugin Version This is used to handle version overwrites

Overwriting/Deleting Existing Package Versions¶

By default Queenbee makes it difficult to overwrite existing package versions. This is to avoid causing issues to any downstream Recipes using your package.

Warning

Don’t read any further unless you know what you are doing and accept the never ending slew of emails you will receive from angry people after overwriting or deleting a package version.

You can force the repository index process to overwrite any new packages added to the index:

queenbee repo index local-queenbee-repo --force

You can remove a package version from an index by deleting the package file from the folder and then running the following command:

queenbee repo index local-queenbee-repo --new