============
File Storage
============

When a document is imported into Mayan EDMS the files are placed under Mayan EDMS
"control" and stored in a dedicated location. This prevents filename clashes and
allows Mayan EDMS to store multible Versions of the same Document without the
user having to manually resolve filename conflicts.

As part of the upload process, each file gets renamed to its ``UUID`` (Universally
Unique ID), saved without an extension, and stored in a simple flat arrangement
in a directory.

This process doesn't prevent manual access to the files and preserves the integrity
of stored documents.

   .. warning::

       Avoid renaming, moving or updating documents directly on the
       filesystem. Manual changes can cause the database to become
       out of sync with the actual state of the files and break the system.


Mayan EDMS components are decoupled from each other as much as possible, as such
storage within Mayan EDMS is also decoupled, and storage behavior is controlled
not by the project, but by the ``Storage`` module class. All other
modules make no assumptions about how the actual document files are
stored. This way, files can be saved locally, over the network or even across
the Internet and everything will be transparant to Mayan EDMS itself as well
as users working on the system.

The default file storage backend ``storage.backends.filebasedstorage.FileBasedStorage``
is a simple storage backend that only supports paths on the local filesystem, rather than
remote or shared storage (such as SMB/NFS).
If you are interested in using remote storage to store documents (NFS, SMB), first
mount these volumes so that they appear as standard filesystem directories to Mayan EDMS.

For direct support of remote volumes, a different storage backend would be needed,
such as those provided by the Django Storages project
(https://django-storages.readthedocs.org/en/latest/).

A supported example of this is S3 :doc:`object_storage`
