🚀 SAP BTP Flask Starter App

Build Production-Ready Flask Apps on SAP BTP with Ease!

---

🌟 Introduction

Welcome to the SAP BTP Flask Starter App! This repository is your one-stop solution for building and deploying production-grade Flask applications on SAP Business Technology Platform (BTP). With built-in support for XSUAA authentication & authorization, HANA database integration, and MTA deployment, this project is designed to help developers—both beginners and experts—hit the ground running. 🎉

---

✨ Features

• 🧑‍💻 Friendly Developer-Experience (DX) Developer Experience was the top goal of this project. Use Basic Auth for local development while using XSUAA Auth for production. Similarly, use SQLite for local development while using SAP HANA for production.

• 🔒 XSUAA Authentication & Authorization
  Secure your app with SAP's XSUAA service for seamless authentication and role-based access control.

• 🛠️ HANA Integration
  Leverage SAP HANA for robust database management with SQLAlchemy and @sap/cds-dk for HDI artifact generation.

• 📦 MTA Deployment
  Effortlessly deploy your app using the Multi-Target Application (MTA) framework.

• ⚡ Local & Production Configurations
  Automatically adapt to local or production environments with minimal setup by setting FLASK_ENV environment variable

• 📋 CF Logging
  Integrated Cloud Foundry logging for better observability using cf-python-logging-support

• 🚀 Gunicorn for Production
  Run your app with the high-performance Gunicorn WSGI server in production.

• 🩺 Health Check Endpoint
  Monitor app and database liveliness via the /health endpoint.

---

🤔 Why Use This Repository?

• Time-Saving: Pre-configured for SAP BTP, so you can focus on building features.
• Best Practices: Implements SAP standards for BTP apps.
• Scalable: Designed to grow with your application needs.
• Beginner-Friendly: Easy-to-follow setup and documentation.

---

🏁 How to Use This Repository

This repository is a template repository. To start your own project based on this starter app:

1. Click the green "Use this template" button at the top of the GitHub repository page.
2. Choose "Create a new repository" and fill in your desired repository name and settings.
3. Follow the Getting Started instructions below to set up your environment.

Tip

Using the template ensures you start with a clean commit history and can customize your project independently.

---

🛠️ Getting Started

Pre-requisites

1. Install NodeJS.
2. Install poetry for dependency management.
3. Install CF CLI.

Setup

1. Clone the Repository

   git clone https://github.com/anselm94/sapbtp-flask-bookstore.git
   cd sapbtp-flask-bookstore

2. Create and Activate a Virtual Environment

   python -m venv .venv
   source .venv/bin/activate

3. Install cds-dk & mbt tooling

   npm install

4. Deploy DB artefacts

   Deploy DB artefacts to local SQLite DB file.

   # in root project dir
   npm run deploy:sqlite

   [!NOTE]

   You must repeat the above command everytime for every CDS file change in db/ folder

5. Install Poetry Dependencies

   cd srv && poetry install

6. Start the Local Server

   The local server starts with SQLite as DB and Basic User (username: me & password: me)

   # in `srv` folder
   python -m flask run

7. Test the API

   • Health Check

   GET http://127.0.0.1:5000/health

   • Get books API

   GET http://127.0.0.1:5000/api/v1/books
   
   Authorization: Basic me:me

8. Run Tests

   # in `srv` folder
   python -m pytest

9. See Coverage Reports

   • Open generated HTML coverage reports in srv/htmlcov/ folder

Deploy to Cloud Foundry

1. Build the MTA Project

   # in project root dir
   mbt build

2. Push the Artefact

   # in project root dir
   cf deploy mta_archives/sapbtp-flask-bookstore_1.0.0.mtar

3. Test the API

   Check the BTP Cockpit for the URL.

   • Health Check

   GET https://<BTP_APP_DEPLOYMENT_URL>/health

   • Get books API

   Get an oauth2_token before running the following check

   GET http://<BTP_APP_DEPLOYMENT_URL>/api/v1/books
   
   Authorization: Bearer <oauth2_token>

Tip

In order to replicate the PRODUCTION in the local by connecting to HANA DB and use oAuth2 authentication flow, you can replicate the VCAP_SERVICES in the local and set FLASK_ENV=PRODUCTION. See config.py for more info

1. Copy .env.example to .env
2. Run the setup script to populate VCAP_SERVICES

   sh setup-env.sh

3. Run the app locally

   cd srv
   FLASK_ENV=PRODUCTION python -m flask run

4. Test the API with oAuth2 credentials

---

📂 Project Structure

sapbtp-flask-bookstore/
├── db/                               # CDS schema and data files
│   ├── schema.cds                    # Core Data Services (CDS) schema definition
│   ├── data/                         # Sample data for the database
├── gen/                              # Generated HANA artifacts
├── srv/                              # Flask application source code
│   ├── app.py                        # Entry point for the Flask application
│   ├── config.py                     # Configuration management for different environments
│   ├── app/                          # Application modules
│   │   ├── database.py               # Database connection and setup logic
│   │   ├── models.py                 # ORM models for database tables
│   │   ├── routes/                   # API route definitions
│   │   │   ├── __init__.py           # Route initialization
│   │   ├── services/                 # Business logic and service layer
│   │   │   ├── books_service.py      # Service logic for book-related operations
│   │   ├── utils/                    # Utility functions for authentication and error handling
│   │   │    ├── auth_utils.py        # Authentication helper functions
|   │   │    ├── heathcheck_utils.py  # Healthcheck helper functions
│   ├── tests/                        # Unit Tests
├── mta.yaml                          # MTA deployment descriptor
├── setup-env.sh                      # Script to configure local environment
└── README.md                         # Project documentation

---

🔍 How It Works

1. Authentication & Authorization

   • Use @login_required for any route, which needs authentication
   • Use @roles_required(["role-1", "role-2"]) for any route, which needs necessary scope authorization

   Local Development

   • Uses Basic Auth for quick and easy development in the local - See srv/config.py, srv/app/routes/__init__.py & srv/app/utils/auth_utils.py
   • Validate Role-based access control as defined for mock users in srv/config.py
   • Configure default mock users and roles in srv/config.py

   Production

   • Uses SAP XSUAA for OAuth2-based authentication & authorization - See srv/config.py, srv/app/routes/__init__.py & srv/app/utils/auth_utils.py
   • Role-based access control is defined in xs-security.json.

2. Database Integration

   • All DB artefacts are modelled in SAP CDS - Conceptual Definition Language format - See db/schema.cds
   • Uses @sap/cds-dk CLI for compiling CDS CDL to target DB DDL format and deploy them at ease.
   • SQLAlchemy is used for ORM mapping in the Flask app (srv/app/models.py) using 'SQLite dialect' or 'SAP HANA dialect'.
   • Easily load default CSV data configurations - see db/data/
   • CDS models (db/schema.cds) are converted to HANA HDI artifacts using @sap/cds-dk.

   Local Development

   • Run npm run deploy:sqlite in the root project dir to deploy the latest CDS changes in db/ folder to the local SQLite DB files.

   Production

   • Use SAP HANA Deployer - @sap/hdi-deploy for automated HANA artefact migration and deployment

3. Health Checks

   • Checks for dependent services' availability for health check endpoint /health - see srv/app/utils/heathcheck_utils.py

4. Automated Tests

   • Uses pytest framework with pytest-flask for automated tests.
   • Uses pytest-cov for coverage reporting

5. Deployment

   • MTA framework bundles the app, database, and services for deployment.
   • cf deploy handles the deployment to SAP BTP.

---

🧑‍💻 Development Workflow

• Debugging: Use VS Code's built-in debugger with the provided launch.json.
• Extending:
  • Add new routes in srv/app/routes/
  • Add new services in srv/app/services/.
  • Add new models in db/schema.cds and srv/app/models.py

---

📜 License

This project is licensed under the MIT License.

---

🙌 Acknowledgments

Special thanks to the SAP BTP community and contributors for their support and inspiration!