# ows-ledger

## 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
```

Install `uv` if missing. See [Installing uv](https://docs.astral.sh/uv/getting-started/installation/) for details.

  - Homebrew: ```brew install uv```

  - Curl: ```curl -LsSf https://astral.sh/uv/install.sh | sh```

#### (Optional) Setting up Split.io localhost mode

If you're working with feature flags locally or in the integration tests, you might want to setup the Split.io localhost mode:

- Create a `.split` file based on the `split.shadow` template: `make create_split_file`
- Add your feature flag to the `.split` file in form of: `my_feature_flag on|off`
- If the integration tests require your feature flag to be enabled, add it to the `.split.shadow` template as well.

### 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 ledger-mysql
```

And to manually run the MySQL migrations use:

```bash
$ docker-compose up ledger-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

  - Regular packages: ```uv add <pkg>```

  - Dev packages: ```uv add <pkg> --dev```

  - Integration packages: ```uv add <pkg> --group integration```

### Upgrading packages

  - All packages: ```uv sync --upgrade```
  
  - A specific package: ```uv sync --upgrade-package <pkg>```

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

### Notes

Windows users will not be able to use the `make` commands as Make is a Unix util.
Windows users can attempt to install [GNUWin](http://gnuwin32.sourceforge.net/packages/make.htm) to get this functionality.