Package: django-minio-backend
django-minio-backendThedjango-minio-backendprovides a wrapper around theMinIO Python SDK.
Seeminio/minio-pyfor the source.IntegrationGet and install the package:pipinstalldjango-minio-backendAdddjango_minio_backendtoINSTALLED_APPS:INSTALLED_APPS=[# '...''django_minio_backend',# https://github.com/theriverman/django-minio-backend]If you would like to enable on-start consistency check, install viaDjangoMinioBackendConfig:INSTALLED_APPS=[# '...''django_minio_backend.apps.DjangoMinioBackendConfig',# https://github.com/theriverman/django-minio-backend]Then add the following parameter to your settings file:MINIO_CONSISTENCY_CHECK_ON_START=TrueNote:The on-start consistency check equals to manually callingpython manage.py initialize_buckets.It is recommended to turnoffthis feature during development by settingMINIO_CONSISTENCY_CHECK_ON_STARTtoFalse,
because this operation can noticeably slow down Django's boot time when many buckets are configured.Add the following parameters to yoursettings.py:fromdatetimeimporttimedeltafromtypingimportList,TupleMINIO_ENDPOINT='minio.your-company.co.uk'MINIO_EXTERNAL_ENDPOINT="external-minio.your-company.co.uk"# Default is same as MINIO_ENDPOINTMINIO_EXTERNAL_ENDPOINT_USE_HTTPS=True# Default is same as MINIO_USE_HTTPSMINIO_REGION='us-east-1'# Default is set to NoneMINIO_ACCESS_KEY='yourMinioAccessKey'MINIO_SECRET_KEY='yourVeryS3cr3tP4ssw0rd'MINIO_USE_HTTPS=TrueMINIO_URL_EXPIRY_HOURS=timedelta(days=1)# Default is 7 days (longest) if not definedMINIO_CONSISTENCY_CHECK_ON_START=TrueMINIO_PRIVATE_BUCKETS=['django-backend-dev-private',]MINIO_PUBLIC_BUCKETS=['django-backend-dev-public',]MINIO_POLICY_HOOKS:List[Tuple[str,dict]]=[]# MINIO_MEDIA_FILES_BUCKET = 'my-media-files-bucket'  # replacement for MEDIA_ROOT# MINIO_STATIC_FILES_BUCKET = 'my-static-files-bucket'  # replacement for STATIC_ROOTMINIO_BUCKET_CHECK_ON_SAVE=True# Default: True // Creates bucket if missing, then save# Custom HTTP Client (OPTIONAL)importosimportcertifiimporturllib3timeout=timedelta(minutes=5).secondsca_certs=os.environ.get('SSL_CERT_FILE')orcertifi.where()MINIO_HTTP_CLIENT:urllib3.poolmanager.PoolManager=urllib3.PoolManager(timeout=urllib3.util.Timeout(connect=timeout,read=timeout),maxsize=10,cert_reqs='CERT_REQUIRED',ca_certs=ca_certs,retries=urllib3.Retry(total=5,backoff_factor=0.2,status_forcelist=[500,502,503,504]))Implement your own Attachment handler and integratedjango-minio-backend:fromdjango.dbimportmodelsfromdjango_minio_backendimportMinioBackend,iso_date_prefixclassPrivateAttachment(models.Model):file=models.FileField(verbose_name="Object Upload",storage=MinioBackend(bucket_name='django-backend-dev-private'),upload_to=iso_date_prefix)Initialize the buckets & set their public policy (OPTIONAL):Thisdjango-admincommand creates both the private and public buckets in case one of them does not exists,
and sets thepublicbucket's privacy policy fromprivate(default) topublic.pythonmanage.pyinitialize_bucketsCode reference:initialize_buckets.py.Static Files Supportdjango-minio-backendallows serving static files from MinIO.
To learn more about Django static files, seeManaging static files, andSTATICFILES_STORAGE.To enable static files support, update yoursettings.py:STATICFILES_STORAGE='django_minio_backend.models.MinioBackendStatic'MINIO_STATIC_FILES_BUCKET='my-static-files-bucket'# replacement for STATIC_ROOT# Add the value of MINIO_STATIC_FILES_BUCKET to one of the pre-configured bucket lists. eg.:# MINIO_PRIVATE_BUCKETS.append(MINIO_STATIC_FILES_BUCKET)# MINIO_PUBLIC_BUCKETS.append(MINIO_STATIC_FILES_BUCKET)The value ofSTATIC_URLis ignored, but it must be defined otherwise Django will throw an error.IMPORTANTThe value set inMINIO_STATIC_FILES_BUCKETmust be added either toMINIO_PRIVATE_BUCKETSorMINIO_PUBLIC_BUCKETS,
otherwisedjango-minio-backendwill raise an exception. This setting determines the privacy of generated file URLs which can be unsigned public or signed private.Note:IfMINIO_STATIC_FILES_BUCKETis not set, the default value (auto-generated-bucket-static-files) will be used. Policy setting for default buckets isprivate.Default File Storage Supportdjango-minio-backendcan be configured as a default file storage.
To learn more, seeDEFAULT_FILE_STORAGE.To configuredjango-minio-backendas the default file storage, update yoursettings.py:DEFAULT_FILE_STORAGE='django_minio_backend.models.MinioBackend'MINIO_MEDIA_FILES_BUCKET='my-media-files-bucket'# replacement for MEDIA_ROOT# Add the value of MINIO_STATIC_FILES_BUCKET to one of the pre-configured bucket lists. eg.:# MINIO_PRIVATE_BUCKETS.append(MINIO_STATIC_FILES_BUCKET)# MINIO_PUBLIC_BUCKETS.append(MINIO_STATIC_FILES_BUCKET)The value ofMEDIA_URLis ignored, but it must be defined otherwise Django will throw an error.IMPORTANTThe value set inMINIO_MEDIA_FILES_BUCKETmust be added either toMINIO_PRIVATE_BUCKETSorMINIO_PUBLIC_BUCKETS,
otherwisedjango-minio-backendwill raise an exception. This setting determines the privacy of generated file URLs which can be unsigned public or signed private.Note:IfMINIO_MEDIA_FILES_BUCKETis not set, the default value (auto-generated-bucket-media-files) will be used. Policy setting for default buckets isprivate.Health CheckTo check the connection link between Django and MinIO, use the providedMinioBackend.is_minio_available()method.It returns aMinioServerStatusinstance which can be quickly evaluated as boolean.Example:fromdjango_minio_backendimportMinioBackendminio_available=MinioBackend().is_minio_available()# An empty string is fine this timeifminio_available:print("OK")else:print("NOK")print(minio_available.details)Policy HooksYou can configuredjango-minio-backendto automatically execute a set of pre-defined policy hooks.Policy hooks can be defined insettings.pyby addingMINIO_POLICY_HOOKSwhich must be a list of tuples.Policy hooks are automatically picked up by theinitialize_bucketsmanagement command.For an exemplary policy, see the implementation ofdef set_bucket_to_public(self)indjango_minio_backend/models.pyor the contents
ofexamples/policy_hook.example.py.Consistency Check On StartWhen enabled, theinitialize_bucketsmanagement command gets called automatically when Django starts.This command connects to the configured minIO server and checks if all buckets defined insettings.py.In case a bucket is missing or its configuration differs, it gets created and corrected.Reference ImplementationFor a reference implementation, seeExamples.BehaviourThe following list summarises the key characteristics ofdjango-minio-backend:Bucket existence isnotchecked on a save by default.
To enable this guard, setMINIO_BUCKET_CHECK_ON_SAVE = Truein yoursettings.py.Bucket existences arenotchecked on Django start by default.
To enable this guard, setMINIO_CONSISTENCY_CHECK_ON_START = Truein yoursettings.py.Many configuration errors are validated throughAppConfigbut not every error can be captured there.Files with the same name in the same bucket arenotreplaced on save by default. Django will store the newer file with an altered file name
To allow replacing existing files, pass thereplace_existing=Truekwarg toMinioBackend.
For example:image = models.ImageField(storage=MinioBackend(bucket_name='images-public', replace_existing=True))Depending on your configuration,django-minio-backendmay communicate over two kind of interfaces: internal and external.
If yoursettings.pydefines a different value forMINIO_ENDPOINTandMINIO_EXTERNAL_ENDPOINT, then the former will be used for internal communication
between Django and MinIO, and the latter for generating URLs for users. This behaviour optimises the network communication.
SeeNetworkingbelow for a thorough explanationThe uploaded object's content-type is guessed during save. Ifmimetypes.guess_typefails to determine the correct content-type, then it falls back toapplication/octet-stream.Networking and DockerIf your Django application is running on a shared host with your MinIO instance, you should consider using theMINIO_EXTERNAL_ENDPOINTandMINIO_EXTERNAL_ENDPOINT_USE_HTTPSparameters.
This way most traffic will happen internally between Django and MinIO. The external endpoint parameters are required for external pre-signed URL generation.If your Django application and MinIO instance are running on different hosts, you can omit theMINIO_EXTERNAL_ENDPOINTandMINIO_EXTERNAL_ENDPOINT_USE_HTTPSparameters,
anddjango-minio-backendwill default to the value ofMINIO_ENDPOINT.Setting up and configuring custom networks in Docker is not in the scope of this document.To learn more about Docker networking, seeNetworking overviewandNetworking in Compose.SeeREADME.Docker.mdfor a real-life Docker Compose demonstration.CompatibilityDjango 2.2 or laterPython 3.8.0 or laterMinIO SDK 7.0.2 or laterContributionPlease find the details inCONTRIBUTE.mdCopyrighttheriverman/django-minio-backend licensed under the MIT Licenseminio/minio-py is licensed under the Apache License 2.0