# ows-permissions

## Overview

This microservice manages permissions of our users across our different applications (Mobile
Analytics, OA, and Workstation, Podcasts, etc). This microservice is responsible for handling
access, removal, and information about user access to resources and data.

## Getting Started

### Requirements

* Python3.11

### Installation

The installation process is very straightforward. The first step you have to do
is install Python 3.11, then get the source from github and start playing!


* #### Install Python 3.11 (on Mac)
  How-to at pydocs: [https://docs.python-guide.org/starting/install3/osx/](https://docs.python-guide.org/starting/install3/osx/)
  ```bash
  brew install python3 uv
  ```
  If you are using [pyenv](https://github.com/pyenv/pyenv) to manage Python versions on your Mac, please make sure
to install the **exact 3.11 version** of Python.

* #### Get the code
  ```bash
  # clone the repo
  git clone git@github.com:theorchard/ows-permissions.git
  cd ows-permissions/

  # add your fork as a remote
  git remote add <YOUR USERNAME> git@github.com:<YOUR USERNAME>/ows-permissions.git
  ```

* #### Install dependencies / Updating
  ```bash
  uv sync
  ```

* #### Setup local environment variables
  ```bash
  cp .env.shadow .env
  ```
  You can leave all variables untouched to run the linter and unit tests.
For the integration tests or running the project locally you may need to
  specify database connection settings, split_io and auth0 API keys.

* ### Developing (Docker)

1. Make sure you've set up your `.env` file:

```
cp .env.shadow .env
```

FILL out `.env` accordingly

2. Load your environment:

```bash
awsume prod
source .env
```

3. Run the hot-reload version of the ows-permissions Docker image - it watches for changes on your volume/laptop:

```bash
make up
```

You can make requests against it at http://localhost:8888.

4. If you feel the need to run the deploy-version of the ows-permissions Docker image (it's uwsgi):

```bash
make up_deploy
```

You can make requests against it at http://localhost:8889.

5. When you're done, bring down your Docker containers:

```bash
make down
```

* #### Running linter

  We use [flake8](http://flake8.pycqa.org/en/latest/) as the linter, rules can be seen in `.flake8`.

  ```bash
  flake8 permissions/ tests/
  ```

  make command: `make lint`

* #### Testing

  We use [Pytest](http://pytest.org/) to run our tests.

    ```bash
    uv run pytest tests
    ```
  **Important:** Please, make sure that you've exported (or defined in .env file) `Environment=dev` env variable.
  Otherwise you may see some weird errors while running the unit tests.


  [Pydebug](https://docs.python.org/2/library/pdb.html) is useful for debugging

    ```bash
    import pdb; pdb.set_trace()
    ```
    Place that anywhere in the code and it will pause there during the test and you can inspect variables

* #### Running integration tests locally

 To run unit tests: `make test`
 To run integration tests: `make test_integration`

 If `make test_integration` fails with a python ImportError about a module not found, try running `pytest tests/integration/api` to run Python integration tests with the repo's main virtual env rather than the env in tests/integration.

* #### Adding Handlers to Swagger Registry

  Our API documentation is held in https://swagger.theorchard.io/. When creating a new handler or updating functionality, please try to remember to update the `ows-permissions-1.0.0.yaml` file in `/spec` to keep our docs up to date.

  Use an editor like [https://editor.swagger.io/](https://editor.swagger.io/) to check the syntax for issues before pushing.

  After the update, run the [docs-swagger-ui-pipeline](https://pipeline.theorchard.io/job/docs-swagger-ui-pipeline/) to see the changes in the actual registry.