Skip to main content

A django widget library for direct S3 uploads

Project description

joist

PyPI version shields.io

Joist is a Django Widget library for providing a direct S3 bucket upload via the browser instead of going through the server. It extends the django-storages library for the S3 file storage

Installation

pip install django-storages joist

by source:

pip install -e 'git+https://github.com/danlamanna/joist.git#egg=joist'

Configuration

Joist depends on the django-storages S3 config (see https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html), following settings are used

Key Description
AWS_ACCESS_KEY_ID Your Amazon Web Services access key, as a string.
AWS_SECRET_ACCESS_KEY Your Amazon Web Services secret access key, as a string.
AWS_S3_REGION_NAME Name of the AWS S3 region to use (eg. eu-west-1)
AWS_STORAGE_BUCKET_NAME Your Amazon Web Services storage bucket name, as a string. (required)

Additional settings

Key Description
JOIST_UPLOAD_STS_ARN The STS Arn Role to use (required)
JOIST_UPLOAD_DURATION The duration the upload token should be valid in seconds (default: 60*60*12 = 12h)
JOIST_UPLOAD_PREFIX Prefix where files should be stored (default: '')
JOIST_API_BASE_URL API prefix where the server urls are hosted (default: /api/joist)

Usage

Setup

Add joist to the list of installed apps:

settings.py:

INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework.authtoken',
    'joist',
]

Moreover, since the field requires additional REST endpoints one has to use add them to the urlpatterns:

urls.py

urlpatterns = [
    ...
    path('api/joist/', include('joist.urls')),
]

Model Definition:

instead of

photo = models.FileField()

use

from joist.models import S3FileField

photo = S3FileField()

The result is that once the user select a file in the file chooser, it will be automatically uploaded to S3 on the client side.

Signals

Joist sends out two signals when its REST api is called:

joist_upload_prepare(name: str, object_key: str)
joist_upload_finalize(name: str, object_key: str, status: string)

Development Environment

Requirements

  • Terraform
  • AWS CLI
  • Python 3.7
  • node

Init AWS

login to AWS Concole and create an API access key

aws configure

Run Terraform

cd terraform
terraform init
terraform workspace new <NAME>
terraform apply

Create env File

cd terraform
terraform output > ../example/.env

Note:

  • edit the .env file and remove the whitespaces around the = characters

Init Django and Python Repo

pipenv --python=3
pipenv install -r requirements.txt example/requirements.txt
pip install -e .

cd example
./manage.py migrate
./manage.py createsuperuser

Init Repo Pre Commits

pipenv shell
pip install pre-commit
pre-commit install

Init Widget Client

cd client
npm install
npm run dev

Init Test Vue Client

cd example-client
npm install

TODO

cd example
./manager.py runserver

--> run at http://localhost:8000 and http://localhost:8000/admin

Example blob forms:

cd example-client
npm run serve

--> run at http://localhost:8080

Release

pipenv shell
pip install bumpversion
bumpversion minor

TODO: npm release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

joist-0.0.2.tar.gz (106.1 kB view hashes)

Uploaded Source

Built Distribution

joist-0.0.2-py2.py3-none-any.whl (102.3 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page