Metadata-Version: 2.1
Name: orchestrator-lso
Version: 1.0.1
Summary: LSO, an API for remotely running Ansible playbooks.
Author-email: GÉANT Orchestration and Automation Team <goat@geant.org>
Requires-Python: >=3.11,<3.13
Description-Content-Type: text/markdown
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: ansible-runner~=2.3.4
Requires-Dist: ansible~=9.3.0
Requires-Dist: fastapi~=0.110.0
Requires-Dist: httpx~=0.27.0
Requires-Dist: jsonschema~=4.21.1
Requires-Dist: uvicorn[standard]~=0.28.0
Requires-Dist: types-setuptools ; extra == "dev"
Requires-Dist: types-requests ; extra == "dev"
Requires-Dist: toml ; extra == "dev"
Requires-Dist: types-toml ; extra == "dev"
Requires-Dist: mypy_extensions ; extra == "dev"
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: sphinx ; extra == "doc"
Requires-Dist: sphinx-rtd-theme ; extra == "doc"
Requires-Dist: docutils ; extra == "doc"
Requires-Dist: pytest ; extra == "test"
Requires-Dist: Faker ; extra == "test"
Requires-Dist: responses ; extra == "test"
Requires-Dist: mypy ; extra == "test"
Requires-Dist: ruff ; extra == "test"
Requires-Dist: jsonschema ; extra == "test"
Requires-Dist: starlette ; extra == "test"
Project-URL: Documentation, https://workfloworchestrator.org/lso/
Project-URL: Source, https://github.com/workfloworchestrator/lso
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: test

# Lightweight Service Orchestrator

LSO: an API that allows for remotely executing Ansible playbooks.

## Code documentation

Code documentation can be found at <https://workfloworchestrator.org/lso>

## Quick start

This is a quick setup guide for running on your local machine.

### As a Docker container

To run LSO as a Docker container, build an image using the `Dockerfile.example` as an example. Be sure to update
`requirements.txt` and `ansible-galaxy-requirements.yaml` accordingly, depending on your specific Ansible collection and
-role needs.

Use the Docker image to then spin up an environment. An example Docker compose file is presented below:

```yaml
  version: "3.5"
  services:
   lso:
     image: my-lso:latest
     environment:
       SETTINGS_FILENAME: /app/config.json
       ANSIBLE_ROLES_PATH: /app/lso/ansible_roles
     volumes:
       - "/home/user/config.json:/app/config.json:ro"
       - "/home/user/ansible_inventory:/opt/ansible_inventory:ro"
       - "~/.ssh/id_ed25519.pub:/root/.ssh/id_ed25519.pub:ro"
       - "~/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro"
```

This will expose the API on port 8000. The container requires some more files to be mounted:

* A `config.json` that references to the location where the Ansible playbooks are stored **inside the container**.
* An Ansible inventory for all host and group variables that are used in the playbooks
* A public/private key pair for SSH authentication on external machines that are targeted by Ansible playbooks.
* Any Ansible-specific configuration (such as `collections_path`, `roles_path`, etc.) should be set using
  environment variables. `ANSIBLE_ROLES_PATH` is given as an example in the Docker compose snippet above.

### Install the module


As an alternative, below are a set of instructions for installing and running LSO directly on a machine.

*One of these should be what you're looking for:*

* Install the latest release

```bash
  python3 -m venv my-venv-directory
  . my-venv-directory/bin/activate

  pip install orchestrator-lso
```

* Install the source code

```bash
  git clone https://github.com/workfloworchestrator/lso.git && cd lso
  python3 -m venv my-venv-directory
  . my-venv-directory/bin/activate
  
  pip install flit
  flit install --deps production
  
  # Or, for the full development environment
  flit install --deps develop
```

### Running the app

* Create a settings file, see `config.json.example` for an example.
* If necessary, set the environment variable `ANSIBLE_HOME` to a custom path.
* Run the app like this (`app.py` starts the server on port 44444):

```bash
  SETTINGS_FILENAME=/absolute/path/to/config.json python -m lso.app
```

