This is a Python microservice created using FastAPI that provides a REST API to upload and download attachments and images to and from an S3 object store.
This microservice requires a MongoDB and S3 object storage instance to run against.
- Docker and Docker Compose installed (if you want to run the microservice inside Docker)
- Python 3.12, MongoDB 7.0 and MinIO installed on your machine (if you are not using Docker)
- Public key (must be OpenSSH encoded) to decode JWT access tokens (if JWT authentication/authorization is enabled)
- MongoDB Compass installed (if you want to interact with the database using a GUI)
- This repository cloned
Ensure that Docker is installed and running on your machine before proceeding.
-
Create a
.env
file alongside the.env.example
file. Use the example file as a reference and modify the values accordingly.cp object_storage_api/.env.example object_storage_api/.env
-
Create a
logging.ini
file alongside thelogging.example.ini
file. Use the example file as a reference and modify it accordingly:cp object_storage_api/logging.example.ini object_storage_api/logging.ini
The easiest way to run the application with Docker for local development is using the docker-compose.yml
file. It is
configured to start
- A MongoDB instance that can be accessed at
localhost:27018
usingroot
as the username andexample
as the password - A MinIO instance at
localhost:9000
with a console that can be accessed atlocalhost:9001
usingroot
as the username andexample_password
as the password - The application in a reload mode using the
Dockerfile
.
-
Build and start the Docker containers:
docker-compose up
The microservice should now be running inside Docker at http://localhost:8000 and its Swagger UI could be accessed at http://localhost:8000/docs. A MongoDB instance should also be running at http://localhost:27018.
Use the Dockerfile
to run just the application itself in a container. Use this only for local development (not
production)!
-
Build an image using the
Dockerfile
from the root of the project directory:docker build -f Dockerfile -t object_storage_api_image .
-
Start the container using the image built and map it to port
8000
locally):docker run -p 8000:8000 --name object_storage_api_container object_storage_api_image
or with values for the environment variables:
docker run -p 8000:8000 --name object_storage_api_container --env DATABASE__NAME=ims object-storage_api_image
The microservice should now be running inside Docker at http://localhost:8000 and its Swagger UI could be accessed at http://localhost:8000/docs.
Ensure that Python is installed on your machine before proceeding.
-
Create a Python virtual environment and activate it in the root of the project directory:
python -m venv venv source venv/bin/activate
-
Install the required dependencies using pip:
pip install .[dev] pip install -r requirements.txt
-
Create a
.env
file alongside the.env.example
file. Use the example file as a reference and modify the values accordingly. You may need to update the port inDATABASE__HOST_AND_OPTIONS
if running the database outside of docker.cp object_storage_api/.env.example object_storage_api/.env
-
Create a
logging.ini
file alongside thelogging.example.ini
file. Use the example file as a reference and modify it accordingly:cp object_storage_api/logging.example.ini object_storage_api/logging.ini
-
Start the microservice using FastAPI's CLI:
fastapi dev object_storage_api/main.py
The microservice should now be running locally at http://localhost:8000. The Swagger UI can be accessed at http://localhost:8000/docs.
The configuration for the application is handled
using Pydantic Settings. It allows for loading config
values from environment variables or the .env
file. Please note that even when using the .env
file, Pydantic will
still read environment variables as well as the .env
file, environment variables will always take priority over
values loaded from the .env
file.
Listed below are the environment variables supported by the application.
Environment Variable | Description | Mandatory | Default Value |
---|---|---|---|
API__TITLE |
The title of the API which is added to the generated OpenAPI. | No | Object Storage Service API |
API__DESCRIPTION |
The description of the API which is added to the generated OpenAPI. | No | This is the API for the Object Storage Service |
API__ROOT_PATH |
(If using a proxy) The path prefix handled by a proxy that is not seen by the app. | No | |
API__ALLOWED_CORS_HEADERS |
The list of headers that are allowed to be included in cross-origin requests. | Yes | |
API__ALLOWED_CORS_ORIGINS |
The list of origins (domains) that are allowed to make cross-origin requests. | Yes | |
API__ALLOWED_CORS_METHODS |
The list of methods that are allowed to be used to make cross-origin requests. | Yes | |
DATABASE__PROTOCOL |
The protocol component (i.e. mongodb ) to use for the connection string for the MongoClient to connect to the database. |
Yes | |
DATABASE__USERNAME |
The database username to use for the connection string for the MongoClient to connect to the database. |
Yes | |
DATABASE__PASSWORD |
The database password to use for the connection string for the MongoClient to connect to the database. |
Yes | |
DATABASE__HOST_AND_OPTIONS |
The host (and optional port number) component as well specific options (if any) to use for the connection string for the MongoClient to connect to the database. The host component is the name or IP address of the host where the mongod instance is running, whereas the options are <name>=<value> pairs (i.e. ?authMechanism=SCRAM-SHA-256&authSource=admin ) specific to the connection.
|
Yes | |
DATABASE__NAME |
The name of the database to use for the MongoClient to connect to the database. |
Yes | |
OBJECT_STORAGE__ENDPOINT_URL |
The URL of the object storage S3 endpoint. | Yes | |
OBJECT_STORAGE__ACCESS_KEY |
The access key to use to authenticate with the S3 object storage. | Yes | |
OBJECT_STORAGE__SECRET_ACCESS_KEY |
The secret access key to use to authenticate with the S3 object storage. | Yes | |
OBJECT_STORAGE__BUCKET_NAME |
The name of the S3 bucket to use for object storage. | Yes | |
OBJECT_STORAGE__PRESIGNED_URL_EXPIRY_SECONDS |
The expiry time of presigned URLs. | Yes | |
ATTACHMENT__MAX_SIZE_BYTES |
The maximum file size of an attachment given in bytes. | Yes | |
IMAGE__THUMBNAIL_MAX_SIZE_BYTES |
The maximum width/height of generated image thumbnails. The actual width and height should maintain the original aspect ratio but neither the width nor height will exceed this value. | Yes |