# ows-royalties

## Getting Started

### Requirements

- Python 3.13
- Docker
- uv

### Installation

Create a `.env` file based on the `.env.shadow` and fill in the values:

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

Create a virtual env and install the requirements:

```bash
make dev_env
```

### Running the Local Database with Docker

You can use `docker-compose` to setup and migrate a local database:

- Authenticate with the Orchard's AWS QA/Prod account: `awsume <prod_profile>`
- Login to Docker: `make docker_login`
- Start the database: `make start_db`
- Stop the database: `make stop_db`

**Note:**
To run only the database use:

```bash
docker-compose up -d royalties-mysql
```

And to manually run the MySQL migrations use:

```bash
docker-compose up royalties-liquibase-runner
```

### Running the application

You can run the flask application locally as follows:

```bash
make dev
```

By using the development server, you will have access to specific features that
are not necessarily available in production, such as the exception tracer.

### Linting and Formatting

Run the linter and show errors: `make lint`

Run the linter and fix errors: `make lint_fix`

Run the formatter and show diffs: `make format`

Run the formatter and apply diffs: `make format_fix`

### Testing

To run the tests, you must have a test database running. By default, the name of database is the name of your development database (the one you specify in your `.env` file) with `_test` appended at the end.
The migration script creates this for you automatically when it first runs.
So for example, if your development database is called `royalties_db`, your test database will be called
`royalties_db_test`. You can override this by setting the env variable `MYSQL_TEST_DB_NAME`.

Run the unit and functional tests: `make test`

#### Testing with Docker

You can run the tests inside Docker using the commands that are used in the pipeline.

You'll first need to login to Docker with the shared AWS account:

```bash
awsume <shared_profile>
make docker_login
```

Run the unit and functional tests: `make ci_unit_lint`

Run the integration tests: `make ci_test_integration`

### Adding new packages

- For dev packages, add them normally to `requirements-dev.txt`
- For regular packages, add the new top level package name
  and optionally version constraints to `requirements-to-freeze.txt`
- Run `make pip_lock_versions`


### Generating OpenAPI specification.

After adding new endpoint or modifying existing one, run ```make openapi``` command to generate a new spec file.

Some more info about the spec generation is in https://github.com/theorchard/python-common-apispec.


### Some of the libraries we're using:

- [`flask-sqlalchemy`](https://flask-sqlalchemy.palletsprojects.com/en/2.x/) for integrating with our ORM framework, [SQLAlchemy](https://www.sqlalchemy.org/).
- [`flask-marshmallow`](https://flask-marshmallow.readthedocs.io/en/latest/) for integrating with [Marshmallow](https://marshmallow.readthedocs.io/en/3.0/),
  our object serialization/deserialization tool.

### Activating feature flags
- By default the feature flags are disabled on your local machine if you don't have a `.split` file present.
- To enable them, run ```cp.split.shadow .split``` and activate the desired flags.