Connect

LinuxForHealth Connectors for Inbound Data Processing

Where to Contribute

Getting Started

Read the Documentation

The LinuxForHealth documentation includes architectural overviews, development guidelines, and deployment options.

Required Software

The LinuxForHealth Connect development environment requires the following:

• git for project version control
• mkcert for local trusted certificates
• Python 3.8 or higher for runtime/coding support
• Pipenv for Python dependency management
• Docker Compose 1.28.6 or higher for a local container runtime

For Windows 10 users, we suggest using Windows Subsystem for Linux.
For s390x users, please read these instructions before beginning.
For arm64 users, please read these instructions before beginning.

Set Up A Local Environment

Clone the project and navigate to the root directory

git clone https://github.com/LinuxForHealth/connect
cd connect

Confirm that Python build tooling, pip and pipenv are installed

pip --version
pipenv --version

Install core and dev dependencies

pip install --upgrade pip
pipenv sync --dev

Run tests

pipenv run pytest

Start connect and supporting services

docker-compose up -d
docker-compose ps
pipenv run connect

For s390x users, please follow these instructions to run connect.

Browse to https://localhost:5000/docs to view the Open API documentation

Generate new trusted local certs for connect and supporting services (optional)

Perform this step to create new certificates for connect and connect services. The creation of new certificates is not required, as connect contains a set of default certificates for SSL. If you do create new certificates, you must rebuild the connect docker image, as described in the next section.

./local-config/install-certificates.sh

For more information on connect and HTTPS/TLS support, please refer to the local cert readme.
For s390x users, please read these instructions.
For arm64 users, please read these instructions.

Docker Image

The connect docker image is an "incubating" feature and is subject to change. The image is associated with the "deployment" profile to provide separation from core services.

Build the image

The connect image build integrates the application's x509 certificate (PEM encoded) into the image.

The APPLICATION_CERT_PATH build argument is used to specify the location of the certificate on the host machine. If the APPLICATION_CERT_PATH build argument is not provided, a default value of ./local-certs/lfh.pem is used.

Build the image with Docker CLI

docker build --build-arg APPLICATION_BUILD_CERT_PATH=./local-config/ -t linuxforhealth/connect:0.42.0 .

Build the image with Docker-Compose

The docker-compose command below parses the build context, arguments, and image tag from the docker-compose.yaml file.

docker-compose build connect

Run connect and Supporting Services

docker-compose --profile deployment up -d

Developing for connect: Black code formatting integration

LinuxForHealth Connect utilizes the black library to provide standard code formatting. Code formatting and style are validated as part of the LinuxForHealth connect ci process. LinuxForHealth connect provides developers with an option of formatting using pipenv scripts, or a git pre-commit hook.

Pipenv Scripts

Check for formatting errors

pipenv run check-format

Format code

pipenv run format

Git pre-commit hook integration

Install git pre-commit hooks (initial setup)

pipenv run pre-commit install

Commit Output - No Python Source Committed

black................................................(no files to check)Skipped
[black-formatter 95bb1c6] settings black version to latest release
 1 file changed, 1 insertion(+), 1 deletion(-)

Commit Output - Python Source is Correctly Formatted

black....................................................................Passed
[format-test c3e1b4a] test commit
 1 file changed, 1 insertion(+)

Commit Output - Black Updates Python Source

black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted connect/routes/api.py
All done! ✨ 🍰 ✨
1 file reformatted.

Build the Multi-arch Docker Image

LinuxForHealth connect runs on amd64, arm64 & s390x platforms. From the top-level connect directory, use this command to build, tag and push the multi-arch image that supports all these platforms:

docker buildx build --pull --push --platform linux/amd64,linux/arm64,linux/s390x --build-arg APPLICATION_BUILD_CERT_PATH=./local-config/ -t linuxforhealth/connect:0.42.0 .

That's it - you can now run docker pull linuxforhealth/connect:0.42.0 on all 3 LinuxForHealth connect platforms.

Links and Resources