# ows-abacus-worksheet

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

### 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 abacus-worksheet-mysql-mysql
```

And to manually run the MySQL migrations use:

```bash
$ docker-compose up abacus-worksheet-mysql-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.