====
adop
====
* PyPI: https://pypi.org/project/adop/
* Downloads: https://gitlab.com/fholmer/adop/-/packages
* Documentation: https://fholmer.gitlab.io/adop
* Source Code: https://gitlab.com/fholmer/adop
* License: BSD License
Summary
=======
Automatic deployment on-prem from zip archives.
Features
========
* A REST API to upload, download and deploy zip-files.
* Listens for webhook requests, to continuously deploy zip-files on commits.
* Includes "package manager" like commands to upload and installing zip-files.
Warning
=======
* This is a beta version. Not ready for production.
Installation
============
Open command line and and install using pip:
.. code-block:: console
$ pip install adop[server]
Usage
=====
adop is available as console script and library module
.. code-block:: console
$ adop -h
$ python -m adop -h
Serve the REST-API:
.. code-block:: console
$ adop serve-api
Serving on http://127.0.0.1:8000
Find the generated authorization token
* Windows
.. code-block:: doscon
> type %USERPROFILE%\.adop\adop.ini | findstr write_token
* Linux
.. code-block:: console
$ cat ~/.adop/adop.ini | grep write_token
Test the REST-API with ``curl``
* Windows
.. code-block:: doscon
> set ADOP_TOKEN=copy-paste-token-here
> curl -H "Token: %ADOP_TOKEN%" "http://127.0.0.1:8000/api/v1/test"
* Linux
.. code-block:: console
$ export ADOP_TOKEN=copy-paste-token-here
$ curl -H "Token: $ADOP_TOKEN" "http://127.0.0.1:8000/api/v1/test"
Upload and deploy a zip-library:
.. code-block:: console
$ curl \
-H "Token: $ADOP_TOKEN" \
-H "Zip-Tag: 0.1.0" \
--data-binary "@work/mylib.zip" \
"http://127.0.0.1:8000/api/v1/deploy/zip/mylib"
Zip file layout
===============
Zip files with exactly one root directory are valid and can be distributed.
The root directory name must be unique if many zip files are to be distributed.
Example of a valid zip file layout:
.. code-block:: kal
/mylib/
/README.rst
/main.py
/mypackage1/
/__init__.py
/__main__.py
/mypackage2/
/__init__.py
/__main__.py
Following example is **not** valid:
.. code-block:: kal
/README.rst
/mylib1/
/__init__.py
/__main__.py
/mylib2/
/__init__.py
/__main__.py
API
===
Endpoints
---------
========================================= ========= =============================
Description Method Endpoint
========================================= ========= =============================
Check that the API is available. GET /api/v1/test
Shasum for all deployed zip-files. GET /api/v1/state
Shasum for given deployed root. GET /api/v1/state/<root>
Known tags for given root. GET /api/v1/tags/<root>
Check specific tag for given root. GET /api/v1/tags/<root>/<tag>
List available zip-files. GET /api/v1/list/zip
List available zip-files for given root. GET /api/v1/list/zip/<root>
Start auto-fetch routine if enabled. GET /api/v1/trigger/fetch
Start auto-fetch routine if enabled. POST /api/v1/trigger/fetch/<root>
Download zip-file with given root. GET /api/v1/download/zip/<root>
Upload a zip-file without deploying it. POST/PUT /api/v1/upload/zip/<root>
Upload and deploy a zip-file. POST/PUT /api/v1/deploy/zip/<root>
Deploy a preloaded zip-file. GET /api/v1/deploy/zip/<root>
Zip-file unpacking progress. GET /api/v1/progress
========================================= ========= =============================
**<root>**
Name of the root directory in the zip-file.
Headers
-------
=========== ====================================== ============================
Header Description Endpoint
=========== ====================================== ============================
Token The authorization token for this API. - All
Zip-Sha256 content hash of the zip-file to - GET /api/v1/deploy/zip
deploy.
Zip-Tag Tag the Shasum. Optional. - POST/PUT /api/v1/upload/zip
- GET/POST/PUT /api/v1/deploy/zip
Zip-Root Name of root directory in zip-file - POST/PUT /api/v1/upload/zip
Optional. - POST/PUT /api/v1/deploy/zip
=========== ====================================== ============================
Result
------
The result is encoded as a json object. Most endpoints will return an object
with ``result`` and ``result_code`` as keywords.
.. code-block:: console
$ curl \
-H "Token: paste-token-here" \
http://127.0.0.1:8000/api/v1/test
{
"result": "It works",
"result_code": 0
}
Endpoints that take a long time will stream a progress log until
the result is returned.
.. code-block:: console
$ curl \
-H "Token: paste-token-here" \
--data-binary "@work/mylib.zip" \
http://127.0.0.1:8000/api/v1/deploy/zip/mylib
// root: mylib
// store data
// verify data
// verify root dir
// verify zip data
// zip root: 'mylib'
// unpack zip data
// remove untracked files
{"root": "mylib", "result": "Success", "result_code": 0}
The Json specification does not support comments,
so the client must ignore lines prefixed with ``//`` before decoding.
.. code-block:: console
$ curl \
-H "Token: paste-token-here" \
--data-binary "@work/mylib.zip" \
http://127.0.0.1:8000/api/v1/deploy/zip/mylib \
| grep -v // \
| python -m json.tool
{
"root": "mylib",
"result": "Success",
"result_code": 0
}
Status and result codes
-----------------------
=========== ============ =================================================
HTTP status result_code Descripton
=========== ============ =================================================
200 0 OK. Indicates that the request has succeeded.
200 1 Fail. The request has succeeded but result was
unsuccessful.
200 2 In progress. The request as been interrupted and
returned to early to give the final result code.
401 4 Unauthorized. Invalid token.
500 5 Internal Error
=========== ============ =================================================
Client side
===========
Define requirements in a ``requires.ini`` file
.. code-block:: text
[requires]
mylib = tag:0.1.0
Define the remote and install locations:
.. code-block:: console
$ export ADOP_TOKEN=copy-paste-token-here
$ adop config add-remote myserver http://127.0.0.1:8000/api/v1 -e ADOP_TOKEN
$ adop config add-install mylibs ./lib/auto ./lib/.cache
And then install:
.. code-block:: console
$ adop zip install requires.ini --remote myserver --install mylibs
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/fholmer/adop",
"name": "adop",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "rest,api,post,zip,auto,deploy,on-prem",
"author": "Frode Holmer",
"author_email": "fholmer+adop@gmail.com",
"download_url": "",
"platform": null,
"description": "====\nadop\n====\n\n* PyPI: https://pypi.org/project/adop/\n* Downloads: https://gitlab.com/fholmer/adop/-/packages\n* Documentation: https://fholmer.gitlab.io/adop\n* Source Code: https://gitlab.com/fholmer/adop\n* License: BSD License\n\nSummary\n=======\n\nAutomatic deployment on-prem from zip archives.\n\nFeatures\n========\n\n* A REST API to upload, download and deploy zip-files.\n* Listens for webhook requests, to continuously deploy zip-files on commits.\n* Includes \"package manager\" like commands to upload and installing zip-files.\n\nWarning\n=======\n\n* This is a beta version. Not ready for production.\n\n\nInstallation\n============\n\nOpen command line and and install using pip:\n\n.. code-block:: console\n\n $ pip install adop[server]\n\n\nUsage\n=====\n\nadop is available as console script and library module\n\n.. code-block:: console\n\n $ adop -h\n $ python -m adop -h\n\nServe the REST-API:\n\n.. code-block:: console\n\n $ adop serve-api\n Serving on http://127.0.0.1:8000\n\nFind the generated authorization token\n\n* Windows\n\n .. code-block:: doscon\n\n > type %USERPROFILE%\\.adop\\adop.ini | findstr write_token\n\n* Linux\n\n .. code-block:: console\n\n $ cat ~/.adop/adop.ini | grep write_token\n\nTest the REST-API with ``curl``\n\n\n* Windows\n\n .. code-block:: doscon\n\n > set ADOP_TOKEN=copy-paste-token-here\n > curl -H \"Token: %ADOP_TOKEN%\" \"http://127.0.0.1:8000/api/v1/test\"\n\n* Linux\n\n .. code-block:: console\n\n $ export ADOP_TOKEN=copy-paste-token-here\n $ curl -H \"Token: $ADOP_TOKEN\" \"http://127.0.0.1:8000/api/v1/test\"\n\nUpload and deploy a zip-library:\n\n.. code-block:: console\n\n $ curl \\\n -H \"Token: $ADOP_TOKEN\" \\\n -H \"Zip-Tag: 0.1.0\" \\\n --data-binary \"@work/mylib.zip\" \\\n \"http://127.0.0.1:8000/api/v1/deploy/zip/mylib\"\n\n\nZip file layout\n===============\n\nZip files with exactly one root directory are valid and can be distributed.\nThe root directory name must be unique if many zip files are to be distributed.\n\nExample of a valid zip file layout:\n\n.. code-block:: kal\n\n /mylib/\n /README.rst\n /main.py\n /mypackage1/\n /__init__.py\n /__main__.py\n /mypackage2/\n /__init__.py\n /__main__.py\n\nFollowing example is **not** valid:\n\n.. code-block:: kal\n\n /README.rst\n /mylib1/\n /__init__.py\n /__main__.py\n /mylib2/\n /__init__.py\n /__main__.py\n\nAPI\n===\n\nEndpoints\n---------\n\n========================================= ========= =============================\nDescription Method Endpoint\n========================================= ========= =============================\nCheck that the API is available. GET /api/v1/test\nShasum for all deployed zip-files. GET /api/v1/state\nShasum for given deployed root. GET /api/v1/state/<root>\nKnown tags for given root. GET /api/v1/tags/<root>\nCheck specific tag for given root. GET /api/v1/tags/<root>/<tag>\nList available zip-files. GET /api/v1/list/zip\nList available zip-files for given root. GET /api/v1/list/zip/<root>\nStart auto-fetch routine if enabled. GET /api/v1/trigger/fetch\nStart auto-fetch routine if enabled. POST /api/v1/trigger/fetch/<root>\nDownload zip-file with given root. GET /api/v1/download/zip/<root>\nUpload a zip-file without deploying it. POST/PUT /api/v1/upload/zip/<root>\nUpload and deploy a zip-file. POST/PUT /api/v1/deploy/zip/<root>\nDeploy a preloaded zip-file. GET /api/v1/deploy/zip/<root>\nZip-file unpacking progress. GET /api/v1/progress\n========================================= ========= =============================\n\n**<root>**\n Name of the root directory in the zip-file.\n\nHeaders\n-------\n\n=========== ====================================== ============================\nHeader Description Endpoint\n=========== ====================================== ============================\nToken The authorization token for this API. - All\nZip-Sha256 content hash of the zip-file to - GET /api/v1/deploy/zip\n deploy.\nZip-Tag Tag the Shasum. Optional. - POST/PUT /api/v1/upload/zip\n - GET/POST/PUT /api/v1/deploy/zip\nZip-Root Name of root directory in zip-file - POST/PUT /api/v1/upload/zip\n Optional. - POST/PUT /api/v1/deploy/zip\n=========== ====================================== ============================\n\nResult\n------\n\nThe result is encoded as a json object. Most endpoints will return an object\nwith ``result`` and ``result_code`` as keywords.\n\n.. code-block:: console\n\n $ curl \\\n -H \"Token: paste-token-here\" \\\n http://127.0.0.1:8000/api/v1/test\n {\n \"result\": \"It works\", \n \"result_code\": 0\n }\n\nEndpoints that take a long time will stream a progress log until\nthe result is returned.\n\n.. code-block:: console\n\n $ curl \\\n -H \"Token: paste-token-here\" \\\n --data-binary \"@work/mylib.zip\" \\\n http://127.0.0.1:8000/api/v1/deploy/zip/mylib\n // root: mylib\n // store data\n // verify data\n // verify root dir\n // verify zip data\n // zip root: 'mylib'\n // unpack zip data\n // remove untracked files\n {\"root\": \"mylib\", \"result\": \"Success\", \"result_code\": 0}\n\n\nThe Json specification does not support comments,\nso the client must ignore lines prefixed with ``//`` before decoding.\n\n.. code-block:: console\n\n $ curl \\\n -H \"Token: paste-token-here\" \\\n --data-binary \"@work/mylib.zip\" \\\n http://127.0.0.1:8000/api/v1/deploy/zip/mylib \\\n | grep -v // \\\n | python -m json.tool\n {\n \"root\": \"mylib\",\n \"result\": \"Success\",\n \"result_code\": 0\n }\n\n\nStatus and result codes\n-----------------------\n\n=========== ============ =================================================\nHTTP status result_code Descripton\n=========== ============ =================================================\n200 0 OK. Indicates that the request has succeeded.\n200 1 Fail. The request has succeeded but result was\n unsuccessful.\n200 2 In progress. The request as been interrupted and\n returned to early to give the final result code.\n401 4 Unauthorized. Invalid token.\n500 5 Internal Error\n=========== ============ =================================================\n\nClient side\n===========\n\nDefine requirements in a ``requires.ini`` file\n\n.. code-block:: text\n\n [requires]\n mylib = tag:0.1.0\n\n\nDefine the remote and install locations:\n\n.. code-block:: console\n\n $\u00a0export ADOP_TOKEN=copy-paste-token-here\n $ adop config add-remote myserver http://127.0.0.1:8000/api/v1 -e ADOP_TOKEN\n $ adop config add-install mylibs ./lib/auto ./lib/.cache\n\nAnd then install:\n\n.. code-block:: console\n\n $ adop zip install requires.ini --remote myserver --install mylibs\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Automatic deployment on-prem from zip archives",
"version": "0.0.9",
"project_urls": {
"Documentation": "https://fholmer.gitlab.io/adop",
"Homepage": "https://gitlab.com/fholmer/adop",
"Source Code": "https://gitlab.com/fholmer/adop"
},
"split_keywords": [
"rest",
"api",
"post",
"zip",
"auto",
"deploy",
"on-prem"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a671060614c4419c2bab98a7b7a4fed0c4da9daf002422226e4db110e3dcc03",
"md5": "b42c7f1782a875cb867f7270984623ee",
"sha256": "ca71c4526b846acd858cca4de37c53905f81d3b8f841f31373ffe116b7e7e1a7"
},
"downloads": -1,
"filename": "adop-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b42c7f1782a875cb867f7270984623ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 42946,
"upload_time": "2024-03-16T07:17:36",
"upload_time_iso_8601": "2024-03-16T07:17:36.805753Z",
"url": "https://files.pythonhosted.org/packages/1a/67/1060614c4419c2bab98a7b7a4fed0c4da9daf002422226e4db110e3dcc03/adop-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 07:17:36",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "fholmer",
"gitlab_project": "adop",
"lcname": "adop"
}
JSON