Python Flask Ariadne API Starter

A GraphQL API that serves data from a PostgreSQL Database. This is built in Python with Flask and Ariadne and developed and deployed in Docker.

Status

Staging

Dependencies

• Git To clone this repo!
• Bash There are included scripts to run that were written for bash. There are a number of popular shells, zsh, ash, fish, ksh, etc. Of course these script could be adjusted for other shells to execute.
• Docker Desktop (docker)
• Visual Studio Code (code) - this is optional, but sure makes everything a lot easier.
• A PostgreSQL server. See Running PostgreSQL in Docker for more info.

Development

The instructions below assume that there is a PostgreSQL server running locally with the Database installed. If this is not the case, please see information on running PostgreSQL in Docker below.

To change any of the environment variables used by the app see Environment Variables below.

The first time you checkout the project, after the database has been set up, run the following command to build the docker image, start the container, and start the API:

bash ./start.sh

This will build the Docker image and run the container. Once the container is created, the Flask server will be started. Then a command prompt should open from within the container (looks like: bash-5.0#).

The GraphiQL playground interface should open automatically in your browser.

Note: If you get 'Version in "./docker-compose.yml" is unsupported.', please update your version of Docker Desktop.

Optional: If you choose to use VS Code, you can use the Remote-Containers extension to develop from within the container itself. Using this approach, you don't need to install Python or any dependencies (besides Docker and VS Code itself) as everything is already installed inside the container. There is a volume mapped to your user .ssh folder so that your ssh keys are available inside the container as well as your user .gitconfig file. The user folder inside the container is also mapped to a volume so that it persists between starts and stops of the container. This means you may create a .bashrc and .profile or similar for yourself within the container and it will persist between container starts and stops.

To exit the container's command prompt, type exit and enter. This will bring you back to your local command prompt.

The following command will stop the server and container:

bash ./stop.sh

Restart the container with the following command:

bash ./start.sh

If there are changes made to the container or image, first, stop the container ./stop.sh, then rebuild it and restarted it with bash ./start.sh --build or bash ./start.sh -b.

Non-Dockerized

If you choose NOT to use the dockerized development method above, please ensure the following are installed:

• Python - version 3.10 (the latest version that ChatGPT is aware of)
• All the packages in the requirements-main.txt file at the versions specified.
• All the packages in the requirements-dev.txt file at the versions specified.

See https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/ for information on installing Python packages for a specific project.

Start the app with the following called from the root of the project:

bash ./set_env_variables.sh && python run.py

Running PostgreSQL in Docker

A simple way to get PostgreSQL running locally is to use Docker. Here is a simple Dockerized PostgreSQL server with pgAdmin:

"postgres_docker" on Github

Linux ONLY

If you are running on a Linux operating system the default connection to the docker container host.docker.internal will not work. To connect to the local dockerized PostgreSQL DB, ensure there is a .env-dev file (.env-SAMPLE can be used as a reference.) In the .env-dev file, ensure the POSTGRES_HOST variable is set to 172.17.0.1

POSTGRES_HOST=172.17.0.1

Connecting to a different Database

Alternatively, the app may be set up to connect to the existing staging database or another database.

To connect to a different database (ie staging), the .env-dev file must also be used with values similar to:

POSTGRES_DB={get_the_database_name}
POSTGRES_HOST={get_the_database_host}
POSTGRES_PASSWORD={get_the_database_password}
POSTGRES_USER={get_the_database_user}

Environment Variables

All the environment variables used by the app have defaults. To set the environment variables, simply run the following bash script from the root of the project folder:

bash ./set_env_variables.sh

The default environment variables' values may be over-written by adding the value to a .env-dev file in the root of the project folder. This file is not versioned in the repository.

The .env-SAMPLE file is an example of what the .env-dev could be like and may be used as a reference.

To reset the environment variables to the defaults (still using the values in the .env-dev file), run the following bash script in the root of the project folder:

bash ./reset_env_variables.sh

Building the Database

The app uses Flask-Migrate to manage migrations.

Once the PostgreSQL server is set up, a database must be created. Before Flask-Migrate can be used, the database MUST already be created. Miguel Grinberg, the creator of Flask-Migrate explains why here

Locally, there should be a dev database and a test database. Like:

• my_db_dev - for development
• my_db_test - for testing

This repo has already been set up with an initial migration that creates an addresses table and a users table. To get started right away, from the root of the app simply run

flask db upgrade

There is an alembic_version table in the database to track migrations. The migration files are in the migrations folder. NOTE The migration files are executed in alphabetical order from the versions folder but the files are not necessarily created in order. Sometimes, changing the beginning of the hash name on the migration files to get them in the proper order is necessary.

If models are changed or created, create a new migration by running

flask db migrate -m "Some message that describes the database change."

This will create a new migration file.

Once again, run

flask db upgrade

to execute any new migrations.

Testing

All tests are in the tests/ folder.

See: TESTING.md in the tests/ folder

Performance Profiling

See: PROFILING.md in the api/telemetry/ folder

Logging

See: LOGGING.md in the api/logger/ folder