Metadata-Version: 2.1
Name: minstrel
Version: 0.0.1
Summary: Instrumentation hardware orchestration platform.
License: BSD 3-Clause License
        
        Copyright (c) 2024, Michael Czigler
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: homepage, https://github.com/mcpcpc/minstrel
Project-URL: repository, https://github.com/mcpcpc/minstrel
Keywords: instrumentation,scpi
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyjwt
Requires-Dist: quart
Requires-Dist: uscpi>=0.3.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Provides-Extra: prod
Requires-Dist: uvicorn; extra == "prod"

# minstrel

An instrumentation hardware orchestration platform.

## Install

### PyPI

Install and update using pip:

```shell
pip install -U minstrel
```

### Repository

When using git, clone the repository and change your 
present working directory.

```shell
git clone http://github.com/mcpcpc/minstrel
cd minstrel/
```

Create and activate a virtual environment.

```shell
python -m venv venv
source venv/bin/activate
```

Install minstrel to the virtual environment.

```shell
pip install -e .
```

## Commands

### db-init

The backend database can be initialized or re-initialized 
with the following command.

```shell
quart --app minstrel init-db
```

### token

In order to prevent unauthorized or accidental backend
database manipulation, some API actions require a *token*
key argument. Token strings can be generated with the
following command.

```shell
quart --app minstrel token
```

The token command also accepts an integer argument that
defines the duration (in seconds) in which the generated
token is valid. The default argument value is `300`.

Note that changing the `SECRET_KEY` variable will
invalidate any previously generated tokens once the
application instance is restarted. 

## Docker Container

Pulling the latest container image from command line.

```shell
docker pull ghcr.io/mcpcpc/minstrel:latest
```

## Deployment

Before deployment, overriding the default `SECRET_KEY`
variable is *strongly* encourage. This can be done by
creating a `conf.py` file and placing it in the
same root as the instance (i.e. typically where the
backend database resides).

```python
SECRET_KEY = “192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf“
```

There are a number of ways to generate a secret key
value. The simplest would be to use the built-in secrets
Python library.

```shell
$ python -c ‘import secrets; print(secrets.token_hex())’
‘192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf’
```

### Quart

Non-production ASGI via quart for development and
debugging.

```shell
quart --debug --app minstrel run
```

### Uvicorn

Production ASGI via uvicorn.

```shell
pip install uvicorn
uvicorn --factory minstrel:create_app
```

## Test

```shell
python3 -m unittest
```

Run with coverage report.

```shell
coverage run -m unittest
coverage report
coverage html  # open htmlcov/index.html in a browser
```
