adop 0.0.1

Automatic deployment on-prem from zip archives

• 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 deployable zip-files.

• Listens for webhook requests, to continuously deploy zip-files on commits.

• Includes a primitive package manager for uploading and installing zip-files.

Warning

• This is a beta version. Not ready for production.

• Documentation is outdated at the moment.

Installation

Open command line and and install using pip:

$ pip install adop

Usage

adop is available as console script and library module

$ adop -h
$ python -m adop -h

Server

Serve rest api:

$ adop serve-api -b 127.0.0.1 -p 8000

Find the generated authorization token

• Windows

  > type %USERPROFILE%\.adop\adop.ini | findstr token

• Linux

  $ cat ~/.adop/adop.ini | grep token

Test the REST-API with curl

$ curl -H "Token: paste-token-here" http://127.0.0.1:8000/api/v1/test

Upload and deploy a zip-library:

$ curl \
  -H "Content-Type: application/zip" \
  -H "Token: paste-token-here" \
  --data-binary "@work/mylib.zip" \
  http://127.0.0.1:8000/api/v1/deploy/zip/mylib

Client

Define requirements in a requires.ini file

[requires]
mylib = tag:0.1.1

And then install:

$ adop zip install requires.ini --remote local

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:

/mylib/
    /README.rst
    /main.py
    /mypackage1/
        /__init__.py
        /__main__.py
    /mypackage2/
        /__init__.py
        /__main__.py

Following example is not valid:

/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>
Start auto-fetch routine if enabled.	GET	/api/v1/trigger/fetch
Download zip-file with given root.	GET	/api/v1/download/zip/<root>
Upload a zip-file without deploying it.	POST	/api/v1/upload/zip/<root>
Upload and deploy a zip-file.	POST	/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 deploy.	GET /api/v1/deploy/zip
Zip-Tag	Tag the Shasum. Optional.	POST /api/v1/upload/zip GET/POST /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.

$ 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.

$ curl \
  -H "Content-Type: application/zip" \
  -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.

$ curl \
  -H "Content-Type: application/zip" \
  -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