Development¶

Developer Quick Start Guide¶

Follow the instructions below to get a flask-ligand development environment up and running quickly!

Prerequisites¶

Python 3.10+
virtualenvwrapper
Docker (with Compose V2)

Make Targets¶

Execute the following command to get a full list of make targets:

$ make help

Setup Python Environment¶

Create a Python virtual environment:
```
$ mkvirtualenv -p py310 flask-ligand
```
Setup develop environment:
```
$ make develop-venv
```
Setup git pre-commit hooks:
```
$ make setup-pre-commit
```
Verify that environment is ready for development:
```
$ make test-tox
```

Configuration Settings¶

The following environment variables are available to configure behavior of services that use this library when utilizing the built-in ‘local’ and ‘dev’ and ‘prod’ Flask environments. (See flask_environments.rst for more details about the available built-in Flask environments)

(Note: this project does support the use of ‘.env’ files for loading environment variables)

**Environment Variable Settings**¶
ENV	Default Value for ‘local’ Flask Environment	Description
`SERVICE_PUBLIC_URL`	`http://localhost:5000`	The public URL for this service. (Also used for generating OpenAPI clients)
`SERVICE_PRIVATE_URL`	`http://localhost:5000`	The private URL for this service. (Also used for generating OpenAPI clients)
`ALLOWED_ROLES`	`user,admin`	A comma separated list of user roles that are allowed for endpoint protection. (e.g. ‘user,admin’)
`OIDC_DISCOVERY_URL`	Not set (must be provided)	The OpenID Connect Provider Configuration Request URL.
`SQLALCHEMY_DATABASE_URI`	`sqlite:///:memory:`	The URI for a PostgreSQL database to use for persistent storage. (See database_configuration.rst for more information)
`OPENAPI_GEN_SERVER_URL`	`http://api.openapi-generator.tech`	The OpenAPI online generator server URL to use for creating clients.

Python Black Support¶

This repo utilizes Python Black for automatic code formatting using the make format task. However, this is not very convenient to use on a regular basis and instead it is recommended to integrate Python Black into your IDE workflow. Checkout these editor integration guides for integrating Python Black with popular IDEs and text editors.

Integration Testing¶

This repo contains Docker compose scripts and associated make targets for setting up and executing integration tests against a PostgreSQL + Keycloak environment.

Utilize Docker Environment¶

It can be quite useful to experiment while developing new features by manually exploring with a production like environment. This can be easily accomplished by leveraging the integration testing environment!

Simply execute steps 1-4 from the following section to get an operational integration test environment then execute the make target:

$ make gen-local-env-file

The make gen-local-env-file will create a new .env file that contains the environment variables necessary to access the integration environment.

Once the .env file has been generated you can start a local Flask server by executing the make target:

$ make run

Simple navigate to http:://localhost:5000/apidocs to access the local environment via SwaggerUI.

Release Process¶

Automated Process¶

This repo utilizes python-semantic-release in conjunction with GitHub Actions to create releases automatically.

Manually Process¶

ONLY UNDER LIMITED CIRCUMSTANCES SHOULD THIS PROCESS BE USED!

Configuring Environment Variables¶

The following environment variables are necessary for creating a full production release:

**Environment Variables**¶
ENV	Description
`GH_TOKEN`	A personal access token from GitHub. This is used for authenticating when pushing tags, publishing releases etc. See Configuring push to Github for usage. To generate a token go to https://github.com/settings/tokens and click on Personal access token.
`REPOSITORY_USERNAME`	Used together with REPOSITORY_PASSWORD when publishing artifact. Note: If you use token authentication with pypi set this to __token__.
`REPOSITORY_PASSWORD`	Used together with REPOSITORY_USERNAME when publishing artifact. Also used for token when using token authentication.

Publish the Release¶

Simply execute the following make target:

$ make publish