diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2c7997..7b5328e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,102 +1,95 @@ -# Contributing to phsyrisk-api +# Contributing to physrisk-api ## Getting started - To get set up, clone and enter the repo. +``` +git clone https://github.com/os-climate/physrisk-api.git +cd physrisk-api +``` - git clone git@github.com:os-climate/physrisk-api.git - cd physrisk-api - -We recommend using [pipenv](https://pipenv.pypa.io/en/latest/) for a -consistent working environment. +We recommend using [pdm](https://pdm-project.org/latest/) for a +consistent working environment. Install via, e.g.: +``` +pip install pdm +``` +For ease of using Jupyter notebooks (e.g. in VS Code) the config can be used: +``` +pdm config venv.with_pip True +``` - pip install pipenv - pipenv install - pipenv shell +The command: +``` +pdm install +``` +will create a virtual environment (typically .venv folder in the project folder) and install the dependencies. +We recommend that the IDE workspace uses this virtual environment when developing. When adding a package for use in new or improved functionality, -`pipenv install `. Or, when adding something helpful for -testing or development, `pipenv install -d `. +`pdm add `. Or, when adding something helpful for +testing or development, `pdm add -dG `. ## Development - Patches may be contributed via pull requests to -. +https://github.com/os-climate/physrisk-api. All changes must pass the automated test suite, along with various static checks. -[Black](https://black.readthedocs.io/) code style and -[isort](https://pycqa.github.io/isort/) import ordering are enforced -and enabling automatic formatting via [pre-commit](https://pre-commit.com/) -is recommended: - - pre-commit install - -This will ensure changes meet common best practice. - -E.g., - - # auto-sort imports - isort . - # auto-format code - black . - -Code can then be tested using tox. - -### run static checks and unit tests +Enabling automatic formatting via [pre-commit](https://pre-commit.com/) +is also recommended: +``` +pre-commit install +``` +or +``` +pre-commit run --all-files +``` - tox +To ensure compliance with automated checks, developers may wish to run formatting and test steps which can be done via: +``` +pdm run lint +pdm run test +``` -### run only tests +## IDE set-up +For those using VS Code, configure tests ('Python: Configure Tests') to use 'pytest' +to allow running of tests within the IDE. - tox -e py3 -### run only static checks +## Forking workflow +This is a useful clarification of the forking workflow: +https://gist.github.com/Chaser324/ce0505fbed06b947d962 +https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow - tox -e static -### run unit tests and produce an HTML code coverage report (/htmlcov) +## Running API in a Container +An image can be built and run via: +``` +docker build . -t physrisk-api-image +docker run -d --name physrisk-api -p 8081:8081 physrisk-api-image +``` +The API should then be accessible via: +http://localhost:8081 +and docs via: +http://localhost:8081/docs - tox -e cov -To run the application locally, run either of the following commands; +An example is also given of using Docker Compose to use nginx as a reverse proxy. To run the application locally, run either of the following commands; docker-compose up # or podman-compose up -One may then make requests of . +This is just an example and details of how the image are used in an Application are mostly beyond the scope of this repo. There is a useful introduction here: +https://fastapi.tiangolo.com/deployment/docker/. +The example 'physrisk' project is hosted on the [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift) Container platform. This is the 'One Load Balancer - Multiple Worker Containers' case where replication is done at the cluster level, which explains why the Dockerfile configures a single worker process. +https://physrisk-ui-physrisk.apps.odh-cl2.apps.os-climate.org/ +https://physrisk-api-physrisk.apps.odh-cl2.apps.os-climate.org/docs -## Releasing - -Currently, this service is released automatically to quay.io and manually -deployed onto OpenShift. - -## Debugging Flask (without Docker) - -The Flask app itself can be run via: -``` -cd src/physrisk_api -flask run -``` +## Releasing +Currently, this image is built and released automatically to quay.io and manually (/automatically for a test instance) deployed onto OpenShift. -For VS Code users, the launch.json configuration suitable for debugging is: -```json -{ - "name": "Python: Flask", - "type": "python", - "request": "launch", - "module": "flask", - "env": { - "FLASK_APP": "src/physrisk_api/app.py", - "FLASK_ENV": "development", - "FLASK_DEBUG": "1" - }, - "args": ["run", "--no-debugger", "--no-reload"], - "jinja": true, - "justMyCode": false -} -``` +## Debugging (without Docker) +We recommend the approach of https://fastapi.tiangolo.com/tutorial/debugging/. That is, the ```"Python Debugger: Current File"``` option can be selected, running file ```.\src\physrisk_api\app\main.py```. diff --git a/README.md b/README.md index f6d2024..e93ba67 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ API service for the OS-Climate physical risk tool ![Build Status](https://github.com/os-climate/physrisk-api/actions/workflows/ci.yml/badge.svg?branch=main) -- [Source](https://github.com/os-climate/physrisk-api) +- [Source](https://github.com/os-climate/physrisk-api) +- [Contributing](https://github.com/os-climate/physrisk-api/blob/main/CONTRIBUTING.md) ## License diff --git a/docker-compose.yml b/docker-compose.yml index 2429dd2..d587f02 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,4 @@ --- -version: "2" - services: web: restart: always diff --git a/nginx/Dockerfile b/nginx/Dockerfile index daf60a0..1b71e28 100644 --- a/nginx/Dockerfile +++ b/nginx/Dockerfile @@ -1,3 +1,3 @@ -FROM docker.io/library/nginx:1.20.2-alpine +FROM docker.io/library/nginx:1.27.3-alpine COPY physrisk-api.conf /etc/nginx/templates/nginx.conf.template