Narwhal: Fast & Secure Python Microservices

Narwhal is a framework to speed up development and deployment of Python microservices.

Narwhal is based on FastAPI application written in Python that can be easily deployed as an ultra-lightweight Docker container, making it ideal for deploying your app on AWS Lambda, AWS Fargate, Kubernetes, Google Cloud Run or your favorite container runtime environment.

Main Features

• Uses FastAPI as server framework. 🚀️

• Pre-configured to use uvicorn and uvloop for lightning-fast performance. ⚡️

• Uses Poetry for simple dependency management. ✨️

• Hot reloading for fast development. 🪄️

• Super lightweight container images thanks to multi-stage Docker build and Alpine Linux (starts at ~70MiB). 🪶️

• Docker image pre-configured to run as a non-root user by default for extra safety. 🔒️

Dependencies

Make sure you have the following dependencies installed to run in development mode:

• Poetry
• Docker
• Make (for running various pre-configured commands)

Getting started

Clone the project

$ git clone git@github.com:ApsisTechnologies/narwhal.git

Run in development mode

$ cd narwhal

# start local server on localhost, port 8000
$ make dev

Run as a Docker container

# run container, also on localhost, port 8000
$ make serve

Notes

Application source code

The src directory contains the application code which is deployed onto the container image.

You'll need to modify Dockerfile if you wanted to include other source code locations in your app.

Automatically-generated OpenAPI documentation

FastAPI provides several OpenAPI doc endpoints at the following routes:

• /docs: OpenAPI/Swagger docs.
• /redoc: Redoc docs.
• /openapi.json: OpenAPI .json spec file.

You can disable these endpoints by passing NARWHAL_DISABLE_DOCS=true as an environment variable.

When building the container via make build command, these endpoints are disabled by default.

Docker image naming

The name of the Docker image is derived from the name and version fields inside pyproject.toml. The Makefile configuration extracts these fields automatically and passes them to Docker to tag the image as "<project name>:<project version>".

CORS support

The application is pre-configured to support CORS headers.

Header proxying

The Docker image passes --proxy-headers as a uvicorn parameter so that your app can run behind a server that takes care of HTTPS. If this is not the case for your app you'll need to modify Dockerfile to remove this flag.

Non-root image user

Most Linux images run as root by default which is a dangerous practice. The image comes pre-configured to run as a non-root user, only using root user access during the build stages.

See Dockerfile for more details.

Modifying Python version

This project uses Python v3.9 by default. To modify this you can modify the line ARG PYTHON_VERSION=3.9 inside Dockerfile.