Metadata-Version: 2.0
Name: gitlab-registry-usage-rest
Version: 0.1.11
Summary: A restful web service for querying the image sizes of a GitLab registry.
Home-page: https://github.com/sciapp/gitlab-registry-usage-rest
Author: Ingo Heimbach
Author-email: i.heimbach@fz-juelich.de
License: MIT
Keywords: Git,GitLab,Docker,Registry,disk capacity,RESTful
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory :: LDAP
Requires-Dist: cheroot
Requires-Dist: Flask
Requires-Dist: Flask-Cors
Requires-Dist: Flask-HTTPAuth
Requires-Dist: Flask-JWT-Extended
Requires-Dist: Flask-RESTful
Requires-Dist: flask-restful-hal
Requires-Dist: gitlab-registry-usage
Requires-Dist: json2html
Requires-Dist: ldap3

GitLab-Registry-Usage-REST
==========================

Introduction
------------

*GitLab-Registry-Usage-REST* is a package that periodically collects
image information (name, tags, sizes) of a GitLab registry server and
offers the data via a secured `RESTful
HAL <http://stateless.co/hal_specification.html>`__ api. For the initial
authentication a LDAP server is needed. Subsequent queries are secured
by *JSON Web Tokens* (JWT).

Installation
------------

The latest version can be obtained from PyPI:

.. code:: bash

    pip install gitlab-registry-usage-rest
    gitlab-registry-usage-rest --help

or from DockerHub:

.. code:: bash

    docker run sciapp/gitlab-registry-usage-rest:latest --help

Usage
-----

*Gitlab-Registry-Usage-REST* needs a configuration file in order to run.
The default path is ``/etc/gitlab_registry_usage_rest.conf`` but can be
altered with the ``-c`` command line switch. To get started, you can run

.. code:: bash

    gitlab-registry-usage-rest --print-default-config

and edit this default configuration to fit your environment.

If you would like to use the docker image, you can bind mount a local
configuration file with the ``-v`` switch:

.. code:: bash

    docker run -v "$(pwd)/gitlab_registry_usage_rest.conf:/etc/gitlab_registry_usage_rest.conf" sciapp/gitlab-registry-usage-rest:latest

**Note**: Docker expects an absolute path for the local configuration
file.

The server offers these api endpoints:

-  ``/auth_token``: Accepts a request with basic auth (and valid LDAP
   credentials) and returns an auth token for further api usage. All
   other endpoints only accept requests with a valid ``Bearer``
   authorization header:

   .. code:: http

       Authorization: Bearer <token>

-  ``/images``: Lists attributes of the *images* collection. Currently,
   only the timestamp of the last data refresh is contained:

   .. code:: json

       {
           "timestamp": 1521796487.7021387
       }

-  ``/images/<image_name>``: Queries attributes of a specific image:

   .. code:: json

       {
           "name": "scientific-it-systems/administration/gitlab-registry-usage-rest",
           "size": 39899199,
           "disk_size": 39898911
       }

-  ``/images/<image_name>/tags``: Endpoint for the collection of image
   tags, currently without any content.

-  ``/images/<image_name>/tags/<tag_name>``: Lists attributes of an
   image tag:

   .. code:: json

       {
           "name": "latest",
           "size": 39899199,
           "disk_size": 39898911
       }

Additionally, all api endpoints (except ``/auth_token``) offer an
``_embedded`` and a ``_links`` attribute if requested with the query
string:

::

    ?embed=true&links=true

Instead of a boolean value, the embed key can also take an integer
number to only request a specific level of embedded resources.

Links can be used to easily navigate between related resources. Embedded
resources are convenient to query a complete hierarchy of resources with
one GET request. Accordingly, the request

::

    /images?embed=true

returns all resources at once.


