{"id":44446307,"url":"https://github.com/brianbirir/flask-boilerplate","last_synced_at":"2026-02-12T15:36:49.890Z","repository":{"id":39841038,"uuid":"177741312","full_name":"brianbirir/flask-boilerplate","owner":"brianbirir","description":"A Flask boiler plate for kicking off Flask RESTful related development projects","archived":false,"fork":false,"pushed_at":"2024-04-16T23:56:02.000Z","size":124,"stargazers_count":0,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-17T04:53:42.122Z","etag":null,"topics":["docker","flask","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brianbirir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-03-26T08:03:56.000Z","updated_at":"2024-04-17T04:53:42.123Z","dependencies_parsed_at":"2024-01-31T19:28:46.999Z","dependency_job_id":"543e2f5d-3736-4d32-b718-d496a26af6d9","html_url":"https://github.com/brianbirir/flask-boilerplate","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/brianbirir/flask-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbirir%2Fflask-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbirir%2Fflask-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbirir%2Fflask-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbirir%2Fflask-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brianbirir","download_url":"https://codeload.github.com/brianbirir/flask-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brianbirir%2Fflask-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29370548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","flask","python3"],"created_at":"2026-02-12T15:36:48.975Z","updated_at":"2026-02-12T15:36:49.881Z","avatar_url":"https://github.com/brianbirir.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flask RESTFul Boilerplate\nA Flask boiler plate for kicking off Flask RESTful related development projects. The key features of this boilerplate include:\n\n* ORM implementation using `Flask-SQLalchemy` with connection to any preferred database technology\n* RESTful implementation using `Flask-Restful` module\n* Implementation of resource authentication using JWTs (JSON Web Tokens). JWTs usage has been implemented using `pyjwts` library\n* Implementation of database migrations using `Flask-Migrate` and Alembic. A base and user model have been added in the `model.py` module to allow the creation of the users table in a designated database\n* Unit and functional tests for the above features\n\nThough this boilerplate is the basis of building a RESTFul API application, it can be extended to include user facing web pages through **Jinja2** Templating and Flask views rendering if desired.\n\n\n## Requirements\n* Python 3\n* JWTs (JSON Web Tokens) implementation for Python\n* Flask and it's dependencies (all defined in the `requirements.txt` file)\n* dot env file of which can be derived from `.env.sample`\n\n## Dot Env\nThe dot env file contains environment variables used to run the application where required. \n\n* Create the dot env file from `env.sample` and save as `.env`\n* The file should contain the following, however, this should not be used in production:\n\n```\nDATABASE_URI=postgresql://api_user:BbYjg7wY@database:5432/api_db\nSECRET_KEY=\\xcf\\x92W\\x88w\\x85s\\xebiE\\xfe\\x13\\xb9\\x92\\xe3\\xee\nSQLALCHEMY_TRACK_MODIFICATIONS=False\n\n```\n* The `SECRET_KEY` can be generated using the `urandom()` function from Python `os` standard library:\n\n```\nimport os\nos.urandom(24)\n```\n\n## Setup (without Containers)\n* Virtualenv - install a Python virual environment i.e. `virtualenv env` and activate it `source env/bin/activate`. Virtualenv can be excluded for Docker deployment during development since we'll be utilizing containers to deploy the application.\n\n* Install Flask and dependencies and add them to `requirements.txt`\n\n```bash\n$ pip freeze \u003e requirements.rxt\n```\n* Install and configure PostgreSQL database. The following commands create a user and a database. The user is then granted access to the database with certain privileges. The user and database names are upto you (also password).\n\n```\ncreate role flask_bp with login password 'flask_bp';\n\nalter role flask_bp createdb;\n\ncreate database flask_bp;\n\ngrant all privileges on database flask_bp to flask_bp;\n\n```\n\n## Run Application\n\n### Development Mode:\n#### WSGI Server\nThe application is served using Gunicorn WSGI within the project's root folder. Pass the configuration type as an argument. In this case, the configuration is a module and loaded as an object.\n\n```bash\ngunicorn \"src:create_app('config.DevelopmentConfig')\"\n```\n\nHowever, before the application is executed, there's need to handle database migrations for SQLAlchemy. Flask-Migrate is used to the handle the migration of the database model objects to the PostgrSQL database. The following commands are executed in the shell to carry out the migration:\n\n```\npython manage.py db init\npython manage.py db migrate\npython manage.py db upgrade\n```\n\n#### Flask Debug Mode (Local Development Server)\nThe application can also be run by adding a Flask app entry point module and naming it as desired e.g. `app.py`. Then add the following code to the entry point module. \n\n```python\nfrom src import create_app\n\n\nif __name__ == \"__main__\":\n    \"\"\"\n    This module should only be used for development when running this application using the Flask web server.\n    Running this is in production is not recommended hence look at other production level WSGI like Gunicorn\n    \"\"\"\n    create_app('config.DevelopmentConfig').run('0.0.0.0')\n```\n\nThen run the app: `python app.py`\n\nYou could also check the quick start guide in the [Flask documentation](http://flask.pocoo.org/docs/1.0/quickstart/#debug-mode) on other methods of running the application using the local development server.\n\n\u003e\u003e **Note one:** Never use the Flask development web server in production. That's one big security risk and it's not scalable.\n\n\u003e\u003e **Note two:** When running this Flask application, ensure the virtual environment is activated.\n\n\n### Production Mode:\nTo-Do\n\n## Setup (with Docker Containers)\nIn this section, unlike the previous one, entails automation with use of Docker to carry out containerization. The use of Docker during developement reduces the time and effort it will take to setup and run the application. \n\nThe `Dockerfile` and `docker-compose.yml` files inside the `docker` folder contain configurations to automate the deployment of the application. `docker-compose` is used throught the management of the docker containers.\n\n\u003e\u003e Ensure Docker is installed in your development environment before continuing.\n\n### Steps to Setup with Docker\n* Clone the repository and change to the project folder\n* Run the following command within the project root to build the docker images:\n\n```bash\ndocker-compose -f docker/docker-compose.yml build --no-cache\n```\n\n* Then create and run the containers from the newly created containers\n\n```bash\ndocker-compose -f docker/docker-compose.yml up\n```\n\nThe Flask web application should now be accessible. Since it's an API driven application, make use of tools such as `curl`, PostMan or Insomnia to call the following end point:\n\n`GET /api/test`\n\nThe output will be a 200 HTTP response in JSON format to confirm the application is up and running:\n\n`curl -v http://localhost:8000/api/test`\n\nOutput:\n\n```bash\n*   Trying ::1...\n* TCP_NODELAY set\n* Connected to localhost (::1) port 8000 (#0)\n\u003e GET /api/test HTTP/1.1\n\u003e Host: localhost:8000\n\u003e User-Agent: curl/7.54.0\n\u003e Accept: */*\n\u003e\n\u003c HTTP/1.1 200 OK\n\u003c Server: gunicorn/19.9.0\n\u003c Date: Mon, 13 May 2019 12:28:36 GMT\n\u003c Connection: close\n\u003c Content-Type: application/json\n\u003c Content-Length: 53\n\u003c\n{\n    \"message\": \"The Flask API web service works\"\n}\n* Closing connection 0\n\n```\nOf note, is that the Flask application within the Docker container is run using Gunicorn. In a future implementation, there will be an option to run the docker containers using either `PRODUCTION` or `DEVELOPMENT` mode. \n\nWith development mode, the application will use the inbuilt Flask web server in order to get debugging messages and the production mode will use Gunicorn.\n\n\u003e\u003e A future automation implementation will see the use of a Makefile to further reduce the steps of deploying the application's Docker containers\n\n\n## To-Do\n* Document sample API using Swagger\n* Automatically create application user in PostgreSQL database during Docker image build\n* ~~Dockerize - Add capability to run the application using Docker~~\n* ~~Update application configuration input~~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianbirir%2Fflask-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrianbirir%2Fflask-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianbirir%2Fflask-boilerplate/lists"}