Creating a repository#

Preparing the Repository#

In order for the tools to parse the repository correctly, the repository must have a certain structure. This is what you need to do:

Go to this page to get information about the expected structure.
Create correct metadata for the repository (consult this page).
When you have prepared your repository, you can check if the repository is all good by trying it using the file system handler.

In the plugin, go to the Settings tab and add a new repository pointing to the root of the repository in your local file system. The repository URL looks like this:

Linux: file:///home/pointing/to/repository_root
Windows: file://C:/home/pointing/to/repository_root

Where can you share it?#

These are the options for sharing: on Github, GitLab, Bitbucket (they need to be public repositories), Gogs (Go Git Service), local file system (if you want to share the collections with your colleagues on the network), or in your own server with the HTTP(S) protocol.

Github, GitLab and Bitbucket#

There is nothing complicated here if you are already familiar with git.

After preparing the repository on your local machine, you can make it into a git repository as usual. In general, you can do:

cd <repository root>
git init
git add .
git commit -m "Created a cool repository for cool users."
git remote add origin <remote repository URL>
git push origin master

Note that you currently need to use the master branch for your repository.

Local File System#

This is even simpler.

After preparing the repository, you can use it right away.

In the Settings tab, you add a repository with URL pointing to the repository root in your local machine (absolute path, example: file:/home/user/QGIS-collections/mycollection).

It’s as simple as that.

If there is a problem with metadata or other issues when adding the repository, you will be told.

Your Own Server#

This option could be useful in some cases, e.g. if you want to make private collections available for your customers.

There are some additional requirements that you need to be aware of if you choose this option:

The URL structure of the repository. If your repository URL is http://www.mydomain.com/qgisrepository/, you must make the metadata available on: http://www.mydomain.com/qgisrepository/metadata.ini
Each collection must be zipped. The zip file of a collection must be named <name of collection>.zip, and the zip shall combine the subdirectories of the collection (one or more of checklists, expressions, image, models, processing, rscripts, svg and symbol), in addition to a preview subdirectory for preview images.

For example, if you have a collection named test_collection, the collection must be present as: http://www.mydomain.com/qgisrepository/collections/test_collection.zip, and the structure of this zip file must be (only include directories that contain resources you would like to share):

test_collection.zip
    ├── checklists
    ├── expressions
    ├── image
    ├── models
    ├── preview
    ├── processing
    ├── rscripts
    ├── svg
    ├── symbol

Preview images that illustrates the collection should be included. If you define preview images for collection test_collection in metadata (preview=preview/prev1.png,prev2.png), you have to place these preview images in the zip-file in a separate directory. preview is the recommended name for that directory.

An example server directory setup for the repository myfirstrepository with one collection (test_collection) that contains resources to share in a lot of resource categories:

qgisrepository
    ├── metadata.ini
    └── collections
        └── test_collection.zip
            ├── checlists
            |   ├── checklist1.json
            |   ├── ...
            |   └── lastchecklist.json
            ├── expressions
            |   ├── expressions1.json
            |   ├── ...
            |   └── lastexpressions.json
            ├── image
            |   ├── image1.png
            |   ├── ...
            |   └── lastimage.png
            ├── models
            |   ├── firstmodel.model3
            |   ├── ...
            |   └── testmodel.model3
            ├── preview
            |   ├── prev1.png
            |   └── prev2.png
            ├── processing
            |   ├── firstscript.py
            |   ├── ...
            |   └── testscript.py
            ├── rscripts
            |   ├── firstRscript.rsx
            |   └──firstRscript.rsx.help
            |   ├── ...
            |   ├── testRscript.rsx
            |   └── testRscript.rsx.help
            ├── style
            |   ├── firstlayerstyle.qml
            |   ├── ...
            |   └── testlayerstyle.qml
            ├── svg
            |   ├── firstmodel.model3
            |   ├── ...
            |   └── testmodel.model3
            └── symbol
                ├── firststyle.xml
                ├── ...
                └── teststyle.xml

The repository URL to be used when adding the repository (in the QGIS Resource Sharing plugin): http://www.mydomain.com/qgisrepository/.

You can also use authentication for this repository.

Users can configure authentication details in the plugin, so that they will be able to fetch the repository and the collections inside.