matthias/mayan-edms
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Reorganize documentation into topics and chapters. Add new material from Wiki.

Browse Source 
Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>
This commit is contained in:
Roberto Rosario
2018-10-15 06:03:04 -04:00
parent 7cd62b5a85
commit e6c43bebf5
59 changed files with 1377 additions and 895 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/chapters/acls.rst
+83
View File
@@ -0,0 +1,83 @@
********************
Access control lists
********************
Besides the permissions system explained in :doc:`permissions`, Mayan EDMS
provides per object permission granting. This feature is used to grant a
permission to a role, but this permission can only be executed for a limited
number of objects (documents, folders, tags) instead of being effective
system-wide.
.. blockdiag::
blockdiag {
default_shape = roundedbox
document [ label = 'Document' ];
role [ label = 'Role' ];
permission [ label = 'Permission' ];
role -> permission -> document;
}
Example:
.. blockdiag::
blockdiag {
default_shape = roundedbox
document [ label = '2015 Payroll report.txt', width=200 ];
role [ label = 'Accountants' ];
permission [ label = 'View document' ];
role -> permission -> document;
}
In this scenario only users in groups belonging to the ``Accountants`` role
would be able to view the ``2015 Payroll report.txt`` document.
Inherited access control
========================
It is also possible to grant a permission to a role for a specific document type (:doc:`document_types`).
Under this scheme all users in groups belonging to that role will inherit that
permission for all documents of that type.
.. blockdiag::
blockdiag {
default_shape = roundedbox
document_type [ label = 'Document type' ];
role [ label = 'Role' ];
permission [ label = 'Permission' ];
documents [shape = "note", stacked];
role -> permission -> document_type ;
document_type -> documents [folded, label = "inherit" ];
}
Example:
.. blockdiag::
blockdiag {
default_shape = roundedbox
document_type [ label = 'Payroll reports', width=200 ];
role [ label = 'Accountants' ];
permission [ label = 'View document' ];
documents [shape = "note", stacked, label="payroll_report*.pdf" ];
role -> permission -> document_type ;
document_type -> documents [folded, label = "inherit" ];
}
The role ``Accountants`` is given the permission ``document view`` for the
document type ``Payroll reports``. Now all users in groups belonging to the
``Accountants`` role can view all documents of the type ``Payroll reports``
without needing to have that permissions granted for each particular
``Payroll reports`` type document.
If access control for the ``Payroll reports`` documents needs to be updated it
only needs to be done for the document type and not for each document of the type
``Payroll reports``.
docs/chapters/app_creation.rst
+143
View File
@@ -0,0 +1,143 @@
************
App creation
************
Mayan EDMS apps are essentially Django app with some extra code to register
navigation, permissions and other relationships.
App modules
===========
- __init__.py
Should be empty if possible. No initialization code should be here, use the
ready() method of the MayanAppConfig class in the apps.py module.
- admin.py
Standard Django app module to define how models are to be presented in the
admin interface.
- api_views.py
REST API views go here. Mayan EDMS uses Django REST Framework API view
classes.
- apps.py
Contains the MayanAppConfig subclass as required by Django 1.7 and up. This
is a place to define the app name and translatable verbose name as well as
code to be execute when the modules of the app are ready.
- classes.py
Hold python classes to be used internally or externally. Any class defined by
the app that is not a model.
- events.py
Define event class instances that are later committed to a log by custom
code.
- exceptions.py
Custom exceptions defined by the app.
- fields.py
Place any custom form field classed you define here.
- forms.py
Standard Django app module that hold custom form classes.
- handlers.py
Contains the signal handlers, functions that will process a given signal
emitted from this or other apps. Connect the handler functions to the
corresponding signal in the ready() method of the MayanAppConfig subclass in
apps.py
- links.py
Defines the links to be used by the app. Import only from the navigation app
and the local permissions.py file.
- literals.py
Stores magic numbers, module choices (if static), settings defaults, and
constants. Should contain all capital case variables. Must not import from
any other module.
- managers.py
Standard Django app module that hold custom model managers. These act as
model class method to performs actions in a series of model instances or
utilitarian actions on external models instances.
- models.py
Standard Django app module that defines ORM persistent data schema.
- permissions.py
Defines the permissions to be used to validate user access by links and views.
Imports only from the permissions app. Link or view conditions such as
testing for is_staff or is_super_user flag are defined in this same module.
- runtime.py
Use this module when you need the same instance of a class for the entire app.
This module acts as a shared memory space for the other modules of the app or
other apps.
- serializers.py
Hold Django REST Framework serializers used by the api_views.py module.
- settings.py
Define the configuration settings instances that the app will use.
- signals.py
Any custom defined signal goes here.
- statistics.py
Provides functions that will compute any sort of statistical information on
the app’s data.
- tasks.py
Code to be execute in the background or as an out-of-process action.
- tests/ directory
Hold test modules. There should be one test_*.py module for each aspect being
tested, examples: test_api.py, test_views.py, test_parsers.py, test_permissions.py
Any shared constant data used by the tests should be added to tests/literals.py
- utils.py
Holds utilitarian code that doesn't fit on any other app module or that is
used by several modules in the app. Anything used internally by the app that
is not a class or a literal (should be as little as possible)
- widgets.py
HTML widgets go here. This should be the only place with presentation
directives in the app (aside the templates).
Views
=====
The module common.generics provides custom generic class based views to be used.
The basic views used to create, edit, view and delete objects in Mayan EDMS
are: SingleObjectCreateView, SingleObjectDetailView, SingleObjectEditView,
and SingleObjectListView
These views handle aspects relating to view permissions, object permissions,
post action redirection and template context generation.
docs/chapters/backups.rst
+70
View File
@@ -0,0 +1,70 @@
*******
Backups
*******
To backup your install of Mayan EDMS just copy the actual document files and
the database content. If you are using the default storage backend, the
document files should be found in the ``media`` folder of your installation.
To dump the content of your database manager refer to the documentation chapter
regarding database data "dumping".
Here is an example of how to perform a backup and a restore of a PostgreSQL
database.
To dump the database into an SQL text file::
pg_dump -h <host> -U <database user> -c <database name> -W > `date +%Y-%m-%d"_"%H-%M-%S`.sql
Example::
pg_dump -h 127.0.0.1 -U mayan -c mayan -W > `date +%Y-%m-%d"_"%H-%M-%S`.sql
To restore the database from the SQL text file::
psql -h <host> -U <database user> -d <database name> -W -f <sql dump file>
Example::
psql -h 127.0.0.1 -U mayan -d mayan -W -f 2018-06-07_18-10-56.sql
Here is an example of how to perform a backup and a restore of a PostgreSQL
Docker container using a compressed dump file. A dump file is not compatible or
can be used interchangeable with an SQL text file.
To backup a PostgreSQL Docker container::
docker exec <container name> pg_dump -U <database user> -Fc -c <database name> > `date +%Y-%m-%d"_"%H-%M-%S`.dump
Example::
docker exec mayan-edms-db pg_dump -U mayan -Fc -c mayan > `date +%Y-%m-%d"_"%H-%M-%S`.dump
This will produce a compressed dump file with the current date and time as the filename.
To restore a PostgreSQL Docker container::
docker exec -i <container name> pg_restore -U <database user> -d <database name> < <dump file>
Since it is not possible to drop a currently open PostgreSQL database, this
command must be used on a new and empty PostsgreSQL container.
Example::
docker run -d \
--name mayan-edms-pg-new \
--restart=always \
-p 5432:5432 \
-e POSTGRES_USER=mayan \
-e POSTGRES_DB=mayan \
-e POSTGRES_PASSWORD=mayanuserpass \
-v /docker-volumes/mayan-edms/postgres-new:/var/lib/postgresql/data \
-d postgres:9.5
docker exec -i mayan-edms-pg-new pg_restore -U mayan -d mayan < 2018-06-07_17-09-34.dump
More information at:
- Postgresl: http://www.postgresql.org/docs/current/static/backup.html
- MySQL: https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html
- SQLite: Just copy the file ``mayan/media/db.sqlite3``
docs/chapters/caa_entity.rst
+233
View File
@@ -0,0 +1,233 @@
**************************************************
Mayan EDMS Entity Contributor Assignment Agreement
**************************************************
Thank you for your interest in contributing to Mayan EDMS ("We" or "Us").
This contributor agreement ("Agreement") documents the rights granted by
contributors to Us. To make this document effective, please print it, sign it
(by copyright holder or authorized party) and send it to Us by email to
caa@mayan-edms.com. This is a legally binding document, so please read it
carefully before agreeing to it. The Agreement may cover more than one
software project managed by Us.
1. Definitions
==============
"You" means any Legal Entity on behalf of whom a Contribution has been received
by Us. "Legal Entity" means an entity which is not a natural person.
"Affiliates" means other Legal Entities that control, are controlled by, or
under common control with that Legal Entity. For the purposes of this
definition, "control" means (i) the power, direct or indirect, to cause the
direction or management of such Legal Entity, whether by contract or otherwise,
(ii) ownership of fifty percent (50%) or more of the outstanding shares or
securities which vote to elect the management or other persons who direct such
Legal Entity or (iii) beneficial ownership of such entity.
"Contribution" means any work of authorship that is Submitted by You to Us in
which You own or assert ownership of the Copyright. We cannot accept
contributions for which you do not own the Copyright or for which you don't
have the necesary legal power to transfer.
"Copyright" means all rights protecting works of authorship owned or controlled
by You or Your Affiliates, including copyright, moral and neighboring rights,
as appropriate, for the full term of their existence including any extensions
by You.
"Material" means the work of authorship which is made available by Us to third
parties. When this Agreement covers more than one software project, the
Material means the work of authorship to which the Contribution was Submitted.
After You Submit the Contribution, it may be included in the Material.
"Submit" means any form of electronic, verbal, or written communication sent
to Us or our representatives, including but not limited to electronic mailing
lists, source code control systems, and issue tracking systems that are managed
by, or on behalf of, Us for the purpose of discussing and improving the
Material, but excluding communication that is conspicuously marked or otherwise
designated in writing by You as "Not a Contribution."
"Submission Date" means the date on which You Submit a Contribution to Us.
"Effective Date" means the date You execute this Agreement or the date You
first Submit a Contribution to Us, whichever is earlier.
2. Grant of Rights
==================
2.1 Copyright Assignment
------------------------
a. At the time the Contribution is Submitted, You assign to Us all right, title,
and interest worldwide in all Copyright covering the Contribution; provided
that this transfer is conditioned upon compliance with Section 2.3.
b. To the extent that any of the rights in Section 2.1(a) cannot be assigned by
You to Us, You grant to Us a perpetual, worldwide, exclusive, royalty-free,
transferable, irrevocable license under such non-assigned rights, with rights
to sublicense through multiple tiers of sublicensees, to practice such
non-assigned rights, including, but not limited to, the right to reproduce,
modify, display, perform and distribute the Contribution; provided that this
license is conditioned upon compliance with Section 2.3.
c. To the extent that any of the rights in Section 2.1(a) can neither be
assigned nor licensed by You to Us, You irrevocably waive and agree never to
assert such rights against Us, any of our successors in interest, or any of
our licensees, either direct or indirect; provided that this agreement not
to assert is conditioned upon compliance with Section 2.3.
d. Upon such transfer of rights to Us, the Contribution will be licenses under
the terms of the Material.
2.2 Patent License
------------------
For patent claims including, without limitation, method, process, and apparatus
claims which You or Your Affiliates own, control or have the right to grant,
now or in the future, You grant to Us a perpetual, worldwide, non-exclusive,
transferable, royalty-free, irrevocable patent license, with the right to
sublicense these rights to multiple tiers of sublicensees, to make, have made,
use, sell, offer for sale, import and otherwise transfer the Contribution and
the Contribution in combination with the Material (and portions of such
combination). This license is granted only to the extent that the exercise of
the licensed rights infringes such patent claims; and provided that this license
is conditioned upon compliance with Section 2.3.
2.3 Outbound License
--------------------
As a condition on the grant of rights in Sections 2.1 and 2.2, We agree to
license the Contribution only under the terms of the license or licenses which
We are using on the Submission Date for the Material (including any rights to
adopt any future version of a license if permitted).
2.4 Moral Rights
----------------
If moral rights apply to the Contribution, to the maximum extent permitted by
law, You waive and agree not to assert such moral rights against Us or our
successors in interest, or any of our licensees, either direct or indirect.
2.5 Our Rights
--------------
You acknowledge that We are not obligated to use Your Contribution as part of
the Material and may decide to include any Contribution We consider appropriate.
2.6 Reservation of Rights
-------------------------
Any rights not expressly assigned or licensed under this section are expressly
reserved by You.
3. Agreement
============
You confirm that:
a. You have the legal authority to enter into this Agreement.
b. You or Your Affiliates own the Copyright and patent claims covering the
Contribution which are required to grant the rights under Section 2.
c. The grant of rights under Section 2 does not violate any grant of rights
which You or Your Affiliates have made to third parties.
4. Disclaimer
=============
EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED
"AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING,
WITHOUT LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US
AND BY US TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED,
SUCH WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
5. Consequential Damage Waiver
==============================
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US
BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA,
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT
OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT
OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
6. Miscellaneous
================
6.1 Jurisdiction
----------------
This Agreement will be governed by and construed in accordance with the laws of
Puerto Rico excluding its conflicts of law provisions. Under certain circumstances,
the governing law in this section might be superseded by the United Nations
Convention on Contracts for the International Sale of Goods ("UN Convention")
and the parties intend to avoid the application of the UN Convention to this
Agreement and, thus, exclude the application of the UN Convention in its
entirety to this Agreement.
6.2 Acceptance
--------------
This Agreement sets out the entire agreement between You and Us for Your
Contributions to Us and overrides all other agreements or understandings.
6.3 Third parties
-----------------
If You or We assign the rights or obligations received through this Agreement
to a third party, as a condition of the assignment, that third party must
agree in writing to abide by all the rights and obligations in the Agreement.
6.4 Unmet responsibilities
--------------------------
The failure of either party to require performance by the other party of any
provision of this Agreement in one situation shall not affect the right of a
party to require such performance at any time in the future. A waiver of
performance under a provision in one situation shall not be considered a
waiver of the performance of the provision in the future or a waiver of the
provision in its entirety.
6.5 Continuation
----------------
If any provision of this Agreement is found void and unenforceable, such
provision will be replaced to the extent possible with a provision that comes
closest to the meaning of the original provision and which is enforceable.
The terms and conditions set forth in this Agreement shall apply
notwithstanding any failure of essential purpose of this Agreement or any
limited remedy to the maximum extent possible under law.
::
Name: _________________________________________________
Email: ________________________________________________
Address: ______________________________________________
Address (cont): _______________________________________
Country: ______________________________________________
Phone number: _________________________________________
Fax number: ___________________________________________
_______________________________________________________
Signature
Mayan EDMS Entity CAA Version 1.0 April 8, 2018
docs/chapters/caa_individual.rst
+234
View File
@@ -0,0 +1,234 @@
******************************************************
Mayan EDMS Individual Contributor Assignment Agreement
******************************************************
Thank you for your interest in contributing to Mayan EDMS ("We" or "Us").
This contributor agreement ("Agreement") documents the rights granted by
contributors to Us. To make this document effective, please print it, sign it
(by copyright holder or authorized party) and send it to Us by email to
caa@mayan-edms.com. This is a legally binding document, so please read it
carefully before agreeing to it. The Agreement may cover more than one
software project managed by Us.
1. Definitions
==============
"You" means the individual who Submits a Contribution to Us.
"Contribution" means any work of authorship that is Submitted by You to Us
in which You own or assert ownership of the Copyright. We cannot accept
contributions for which you do not own the Copyright or for which you don't
have the necesary legal power to transfer.
"Copyright" means all rights protecting works of authorship owned or
controlled by You, including copyright, moral and neighboring rights,
as appropriate, for the full term of their existence including any extensions
by You.
"Material" means the work of authorship which is made available by Us to third
parties. When this Agreement covers more than one software project, the Material
means the work of authorship to which the Contribution was Submitted. After
You Submit the Contribution, it may be included in the Material.
"Submit" means any form of electronic, verbal, or written communication
sent to Us or our representatives, including but not limited to
electronic mailing lists, source code control systems, and issue tracking systems
that are managed by, or on behalf of, Us for the purpose of discussing and
improving the Material, but excluding communication that is conspicuously marked
or otherwise designated in writing by You as "Not a Contribution."
"Submission Date" means the date on which You Submit a Contribution to Us.
"Effective Date" means the date You execute this Agreement or the date You first
Submit a Contribution to Us, whichever is earlier.
2. Grant of Rights
==================
2.1 Copyright Assignment
------------------------
a. At the time the Contribution is Submitted, You assign to Us all right,
title, and interest worldwide in all Copyright covering the Contribution;
provided that this transfer is conditioned upon compliance with Section 2.3.
b. To the extent that any of the rights in Section 2.1(a) cannot be assigned
by You to Us, You grant to Us a perpetual, worldwide, exclusive, royalty-free,
transferable, irrevocable license under such non-assigned rights, with rights
to sublicense through multiple tiers of sublicensees, to practice such
non-assigned rights, including, but not limited to, the right to reproduce,
modify, display, perform and distribute the Contribution; provided that
this license is conditioned upon compliance with Section 2.3.
c. To the extent that any of the rights in Section 2.1(a) can neither be
assigned nor licensed by You to Us, You irrevocably waive and agree never to
assert such rights against Us, any of our successors in interest, or any of
our licensees, either direct or indirect; provided that this agreement not
to assert is conditioned upon compliance with Section 2.3.
d. Upon such transfer of rights to Us, the Contribution will be licenses under
the terms of the Material.
2.2 Patent License
------------------
For patent claims including, without limitation, method, process, and apparatus
claims which You own, control or have the right to grant, now or in the future,
You grant to Us a perpetual, worldwide, non-exclusive, transferable, royalty-free,
irrevocable patent license, with the right to sublicense these rights to multiple
tiers of sublicensees, to make, have made, use, sell, offer for sale, import and
otherwise transfer the Contribution and the Contribution in combination with
the Material (and portions of such combination). This license is granted only
to the extent that the exercise of the licensed rights infringes such patent claims;
and provided that this license is conditioned upon compliance with Section 2.3.
2.3 Outbound License
--------------------
As a condition on the grant of rights in Sections 2.1 and 2.2, We agree to
license the Contribution only under the terms of the license or licenses which
We are using on the Submission Date for the Material (including any rights to
adopt any future version of a license if permitted).
2.4 Moral Rights
----------------
If moral rights apply to the Contribution, to the maximum extent permitted by law,
You waive and agree not to assert such moral rights against Us or our successors
in interest, or any of our licensees, either direct or indirect.
2.5 Our Rights
--------------
You acknowledge that We are not obligated to use Your Contribution as part of
the Material and may decide to include any Contribution We consider appropriate.
2.6 Reservation of Rights
-------------------------
Any rights not expressly assigned or licensed under this section are expressly
reserved by You.
3. Agreement
============
You confirm that:
a. You have the legal authority to enter into this Agreement.
b. You own the Copyright and patent claims covering the Contribution which are
required to grant the rights under Section 2.
c. The grant of rights under Section 2 does not violate any grant of rights
which You have made to third parties, including Your employer. If You are an
employee, You have had Your employer approve this Agreement or sign the Entity
version of this document. If You are less than eighteen years old, please have
Your parents or guardian sign the Agreement.
4. Disclaimer
=============
EXCEPT FOR THE EXPRESS WARRANTIES IN SECTION 3, THE CONTRIBUTION IS PROVIDED
"AS IS". MORE PARTICULARLY, ALL EXPRESS OR IMPLIED WARRANTIES INCLUDING, WITHOUT
LIMITATION, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED BY YOU TO US AND BY US
TO YOU. TO THE EXTENT THAT ANY SUCH WARRANTIES CANNOT BE DISCLAIMED, SUCH
WARRANTY IS LIMITED IN DURATION TO THE MINIMUM PERIOD PERMITTED BY LAW.
5. Consequential Damage Waiver
==============================
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL YOU OR US
BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF ANTICIPATED SAVINGS, LOSS OF DATA,
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL AND EXEMPLARY DAMAGES ARISING OUT
OF THIS AGREEMENT REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT
OR OTHERWISE) UPON WHICH THE CLAIM IS BASED.
6. Miscellaneous
================
6.1 Jurisdiction
----------------
This Agreement will be governed by and construed in accordance with the laws of
Puerto Rico excluding its conflicts of law provisions. Under certain circumstances,
the governing law in this section might be superseded by the United Nations
Convention on Contracts for the International Sale of Goods ("UN Convention")
and the parties intend to avoid the application of the UN Convention to this
Agreement and, thus, exclude the application of the UN Convention in its
entirety to this Agreement.
6.2 Acceptance
--------------
This Agreement sets out the entire agreement between You and Us for Your
Contributions to Us and overrides all other agreements or understandings.
6.3 Third parties
-----------------
If You or We assign the rights or obligations received through this Agreement
to a third party, as a condition of the assignment, that third party must
agree in writing to abide by all the rights and obligations in the Agreement.
6.4 Unmet responsibilities
--------------------------
The failure of either party to require performance by the other party of any
provision of this Agreement in one situation shall not affect the right of a
party to require such performance at any time in the future. A waiver of
performance under a provision in one situation shall not be considered a
waiver of the performance of the provision in the future or a waiver of the
provision in its entirety.
6.5 Continuation
----------------
If any provision of this Agreement is found void and unenforceable,
such provision will be replaced to the extent possible with a provision that
comes closest to the meaning of the original provision and which is enforceable.
The terms and conditions set forth in this Agreement shall apply notwithstanding
any failure of essential purpose of this Agreement or any limited remedy to
the maximum extent possible under law.
::
Name: _________________________________________________
Email: ________________________________________________
Address: ______________________________________________
Address (cont): _______________________________________
Country: ______________________________________________
Phone number: _________________________________________
Fax number: ___________________________________________
_______________________________________________________
Signature
Mayan EDMS Individual CAA Version 1.0 April 8, 2018
docs/chapters/cabinets.rst
+14
View File
@@ -0,0 +1,14 @@
Cabinets
========
Cabinets are a multi-level method to organize documents. Each cabinet can
contain documents as well as other sub level cabinets. Cabinets can
be added from the :menuselection:`Cabinets --> Add new` menu.
With a cabinet structure created, the next step is to add documents to them.
To add documents to a cabinet, select the cabinet tab of a document, and
select :menuselection:`Actions --> Add to cabinets` link.
Documents can also be added in bulk to one or more cabinets from any view
that lists documents.
docs/chapters/checkouts.rst
+14
View File
@@ -0,0 +1,14 @@
*********
Checkouts
*********
Checkouts are a way to block certain accesses or actions of a document for a
period of time.
An user can choose to checkout a document to work on an update and block new
versions of that document to be uploaded by other users. Document are checked
out for a certain amount of time and if not manually checked in by the original
user, will be checked in automatically by the system.
To be able to check in documents that were checked out by other users, the
permission 'Forcefully check in documents' is required.
docs/chapters/deploying.rst
+355
View File
@@ -0,0 +1,355 @@
.. _deploying:
******************
Direct deployments
******************
Mayan EDMS should be deployed like any other Django_ project and
preferably using virtualenv_. Below are some ways to deploy and use Mayan EDMS.
Do not use more than one method.
Being a Django_ and a Python_ project, familiarity with these technologies is
recommended to better understand why Mayan EDMS does some of the things it
does.
Basic deployment
================
This setup uses less memory and CPU resources at the expense of some speed.
Binary dependencies
-------------------
If using a Debian_ or Ubuntu_ based Linux distribution, get the executable
requirements using::
sudo apt-get install g++ gcc ghostscript gnupg1 graphviz libfuse2 \
libjpeg-dev libmagic1 libpq-dev libpng-dev libreoffice libtiff-dev \
poppler-utils postgresql python-dev python-virtualenv redis-server \
sane-utils supervisor tesseract-ocr zlib1g-dev -y
Create an user account for the installation:
--------------------------------------------
::
sudo adduser mayan --disabled-password --disabled-login --no-create-home --gecos ""
Create the parent directory where the project will be deployed:
---------------------------------------------------------------
::
sudo mkdir /opt
Create the Python virtual environment for the installation:
-----------------------------------------------------------
::
sudo virtualenv /opt/mayan-edms
Make the mayan user the owner of the installation directory:
------------------------------------------------------------
::
sudo chown mayan:mayan /opt/mayan-edms -R
Install Mayan EDMS from PyPI:
-----------------------------
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir mayan-edms
Install the Python client for PostgreSQL and Redis:
---------------------------------------------------
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir psycopg2==2.7.3.2 redis==2.10.6
Create the database for the installation:
-----------------------------------------
::
sudo -u postgres psql -c "CREATE USER mayan WITH password 'mayanuserpass';"
sudo -u postgres createdb -O mayan mayan
Initialize the project:
-----------------------
::
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py initialsetup
Collect the static files:
-------------------------
::
sudo -u mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py collectstatic --noinput
Create the supervisor file at ``/etc/supervisor/conf.d/mayan.conf``:
--------------------------------------------------------------------
::
[supervisord]
environment=
MAYAN_ALLOWED_HOSTS='["*"]', # Allow access to other network hosts other than localhost
MAYAN_CELERY_RESULT_BACKEND="redis://127.0.0.1:6379/0",
MAYAN_BROKER_URL="redis://127.0.0.1:6379/0",
PYTHONPATH=/opt/mayan-edms/lib/python2.7/site-packages:/opt/mayan-edms/data,
MAYAN_MEDIA_ROOT=/opt/mayan-edms/media,
MAYAN_DATABASE_ENGINE=django.db.backends.postgresql,
MAYAN_DATABASE_HOST=127.0.0.1,
MAYAN_DATABASE_NAME=mayan,
MAYAN_DATABASE_PASSWORD=mayanuserpass,
MAYAN_DATABASE_USER=mayan,
MAYAN_DATABASE_CONN_MAX_AGE=60,
DJANGO_SETTINGS_MODULE=mayan.settings.production
[program:mayan-gunicorn]
autorestart = true
autostart = true
command = /opt/mayan-edms/bin/gunicorn -w 2 mayan.wsgi --max-requests 500 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
user = mayan
[program:mayan-worker-fast]
autorestart = true
autostart = true
command = nice -n 1 /opt/mayan-edms/bin/mayan-edms.py celery worker -Ofair -l ERROR -Q converter,sources_fast -n mayan-worker-fast.%%h --concurrency=1
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
[program:mayan-worker-medium]
autorestart = true
autostart = true
command = nice -n 18 /opt/mayan-edms/bin/mayan-edms.py celery worker -Ofair -l ERROR -Q checkouts_periodic,documents_periodic,indexing,metadata,sources,sources_periodic,uploads,documents -n mayan-worker-medium.%%h --concurrency=1
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
[program:mayan-worker-slow]
autorestart = true
autostart = true
command = nice -n 19 /opt/mayan-edms/bin/mayan-edms.py celery worker -Ofair -l ERROR -Q mailing,tools,statistics,parsing,ocr -n mayan-worker-slow.%%h --concurrency=1
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
[program:mayan-celery-beat]
autorestart = true
autostart = true
command = nice -n 1 /opt/mayan-edms/bin/mayan-edms.py celery beat --pidfile= -l ERROR
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
Configure Redis to discard data when it runs out of memory, not save its database and only keep 1 database:
-----------------------------------------------------------------------------------------------------------
::
echo "maxmemory-policy allkeys-lru" >> /etc/redis/redis.conf
echo "save \"\"" >> /etc/redis/redis.conf
echo "databases 1" >> /etc/redis/redis.conf
systemctl restart redis
Enable and restart the services [1_]:
-------------------------------------
::
systemctl enable supervisor
systemctl restart supervisor
Advanced deployment
===================
This variation uses RabbitMQ as the message broker and removes the fast worker
concurrency restriction. RabbitMQ consumes more memory but scales to thousands
of messages. RabbitMQ messages are also persistent, this means that pending
tasks are not lost in the case of a restart. The database connection lifetime
is increased to 10 minutes. The Gunicorn workers are increased to 3.
Binary dependencies
-------------------
If using a Debian_ or Ubuntu_ based Linux distribution, get the executable
requirements using::
sudo apt-get install g++ gcc ghostscript gnupg1 graphviz libfuse2 \
libjpeg-dev libmagic1 libpq-dev libpng-dev libreoffice libtiff-dev \
poppler-utils postgresql python-dev python-virtualenv rabbitmq-server \
redis-server sane-utils supervisor tesseract-ocr zlib1g-dev -y
Create an user account for the installation:
--------------------------------------------
::
sudo adduser mayan --disabled-password --disabled-login --no-create-home --gecos ""
Create the parent directory where the project will be deployed:
---------------------------------------------------------------
::
sudo mkdir /opt
Create the Python virtual environment for the installation:
-----------------------------------------------------------
::
sudo virtualenv /opt/mayan-edms
Make the mayan user the owner of the installation directory:
------------------------------------------------------------
::
sudo chown mayan:mayan /opt/mayan-edms -R
Install Mayan EDMS from PyPI:
-----------------------------
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir mayan-edms
Install the Python client for PostgreSQL and Redis:
---------------------------------------------------
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir librabbitmq==2.0.0 psycopg2==2.7.3.2 redis==2.10.6
Create the database for the installation:
-----------------------------------------
::
sudo -u postgres psql -c "CREATE USER mayan WITH password 'mayanuserpass';"
sudo -u postgres createdb -O mayan mayan
Initialize the project:
-----------------------
::
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py initialsetup
Collect the static files:
-------------------------
::
sudo -u mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py collectstatic --noinput
Create the RabbitMQ user and vhost:
-----------------------------------
::
sudo rabbitmqctl add_user mayan mayanrabbitmqpassword
sudo rabbitmqctl add_vhost mayan
sudo rabbitmqctl set_permissions -p mayan mayan ".*" ".*" ".*"
Create the supervisor file at ``/etc/supervisor/conf.d/mayan.conf``:
--------------------------------------------------------------------
::
[supervisord]
environment=
MAYAN_ALLOWED_HOSTS='["*"]', # Allow access to other network hosts other than localhost
MAYAN_CELERY_RESULT_BACKEND="redis://127.0.0.1:6379/0",
MAYAN_BROKER_URL="amqp://mayan:mayanrabbitmqpassword@localhost:5672/mayan",
PYTHONPATH=/opt/mayan-edms/lib/python2.7/site-packages:/opt/mayan-edms/data,
MAYAN_MEDIA_ROOT=/opt/mayan-edms/media,
MAYAN_DATABASE_ENGINE=django.db.backends.postgresql,
MAYAN_DATABASE_HOST=127.0.0.1,
MAYAN_DATABASE_NAME=mayan,
MAYAN_DATABASE_PASSWORD=mayanuserpass,
MAYAN_DATABASE_USER=mayan,
MAYAN_DATABASE_CONN_MAX_AGE=360,
DJANGO_SETTINGS_MODULE=mayan.settings.production
[program:mayan-gunicorn]
autorestart = true
autostart = true
command = /opt/mayan-edms/bin/gunicorn -w 3 mayan.wsgi --max-requests 500 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
user = mayan
[program:mayan-worker-fast]
autorestart = true
autostart = true
command = nice -n 1 /opt/mayan-edms/bin/mayan-edms.py celery worker -Ofair -l ERROR -Q converter,sources_fast -n mayan-worker-fast.%%h
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
[program:mayan-worker-medium]
autorestart = true
autostart = true
command = nice -n 18 /opt/mayan-edms/bin/mayan-edms.py celery worker -Ofair -l ERROR -Q checkouts_periodic,documents_periodic,indexing,metadata,sources,sources_periodic,uploads,documents -n mayan-worker-medium.%%h --concurrency=1
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
[program:mayan-worker-slow]
autorestart = true
autostart = true
command = nice -n 19 /opt/mayan-edms/bin/mayan-edms.py celery worker -Ofair -l ERROR -Q mailing,tools,statistics,parsing,ocr -n mayan-worker-slow.%%h --concurrency=1
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
[program:mayan-celery-beat]
autorestart = true
autostart = true
command = nice -n 1 /opt/mayan-edms/bin/mayan-edms.py celery beat --pidfile= -l ERROR
killasgroup = true
numprocs = 1
priority = 998
startsecs = 10
stopwaitsecs = 1
user = mayan
Configure Redis to discard data when it runs out of memory, not save its database and only keep 1 database:
-----------------------------------------------------------------------------------------------------------
::
echo "maxmemory-policy allkeys-lru" >> /etc/redis/redis.conf
echo "save \"\"" >> /etc/redis/redis.conf
echo "databases 1" >> /etc/redis/redis.conf
systemctl restart redis
Enable and restart the services [1_]:
-------------------------------------
::
systemctl enable supervisor
systemctl restart supervisor
[1]: https://bugs.launchpad.net/ubuntu/+source/supervisor/+bug/1594740
.. _Debian: http://www.debian.org/
.. _Django: http://www.djangoproject.com/
.. _Python: http://www.python.org/
.. _SQLite: https://www.sqlite.org/
.. _Ubuntu: http://www.ubuntu.com/
.. _virtualenv: http://www.virtualenv.org/en/latest/index.html
.. _1: https://bugs.launchpad.net/ubuntu/+source/supervisor/+bug/1594740
docs/chapters/development.rst
+479
View File
@@ -0,0 +1,479 @@
.. _development:
***********
Development
***********
Mayan EDMS is under active development, and contributions are welcome.
If you have a feature request, suggestion or bug report, please open a new
issue on the `GitLab issue tracker`_. To submit patches, please send a merge
request on GitLab_.
.. _GitLab: https://gitlab.com/mayan-edms/mayan-edms/
.. _`GitLab issue tracker`: https://gitlab.com/mayan-edms/mayan-edms/issues
Project philosophies
====================
How to think about Mayan EDMS when doing changes or adding new features;
why things are the way they are in Mayan EDMS:
- Functionality must be as market/sector independent as possible, code for the
95% of use cases.
- Each user must be able to configure and customize it to their needs after
install.
- Abstract as much as possible, each app must be an expert in just one thing,
for other things they should use the API/classes/functions of other apps.
- Assume as little as possible about anything outside the project
(hardware, OS, storage).
- Provide Python based abstraction so that a default install runs with a single
step.
- No hard dependencies on binaries unless there is no other choice.
- Provide “drivers” or switchable backends to allow users to fine tune the
installation.
- Call to binaries only when there is no other choice or the Python choices are
not viable/mature/efficient.
- Each app is as independent and self contained as possible. Exceptions, the
basic requirements: navigation, permissions, common, main.
- If an app is meant to be used by more than one other app, it should be as
generic as possible in regard to the project and another app will bridge the functionality.
- Example: since indexing (document_indexing) only applies to documents, the
app is specialized and depends on the documents app.
Coding conventions
==================
Follow PEP8
-----------
Whenever possible, but don't obsess over things like line length:
.. code-block:: bash
$ flake8 --ignore=E501,E128,E122 |less
To perform automatic PEP8 checks, install flake8's git hook using:
.. code-block:: bash
$ flake8 --install-hook git
Imports
-------
Import order should be:
- Standard Python modules
- Installed Python modules
- Core Django modules
- Installed Django modules
- Mayan EDMS modules
- Local imports
Example:
.. code-block:: bash
from __future__ import absolute_import
# Standard Python library
import base64
# 3rd party installed Python libraries
import requests
# Django core modules
from django.db.models import Q
from django.template.defaultfilters import slugify
from django.utils.translation import ugettext
from django.utils.translation import ugettext_lazy as _
# 3rd party installed Django libraries
from rest_framework import APIView
# Mayan apps
from metadata.classes import MetadataClass
# Local app imports (relative)
from .conf.settings import (
AVAILABLE_INDEXING_FUNCTIONS,
MAX_SUFFIX_COUNT, SLUGIFY_PATHS
)
from .exceptions import MaxSuffixCountReached
from .filesystem import (
fs_create_index_directory, fs_create_document_link,
fs_delete_document_link, fs_delete_index_directory,
assemble_suffixed_filename
)
from .models import Index, IndexInstanceNode, DocumentRenameCount
All local app module imports are in relative form. Local app module name is to
be referenced as little as possible, unless required by a specific feature,
trick, restriction (e.g., Runtime modification of the module's attributes).
Incorrect:
.. code-block:: bash
# documents app views.py model
from documents.models import Document
Correct:
.. code-block:: bash
# documents app views.py model
from .models import Document
Dependencies
------------
Mayan EDMS apps follow a hierarchical model of dependency. Apps import from
their parents or siblings, never from their children. Think plugins. A parent
app must never assume anything about a possible existing child app. The
documents app and the Document model are the basic entities; they must never
import anything else. The common and main apps are the base apps.
Variables
---------
Naming of variables should follow a Major to Minor convention, usually
including the purpose of the variable as the first piece of the name, using
underscores as spaces. camelCase is not used in Mayan EDMS.
Examples:
Links:
.. code-block:: bash
link_document_page_transformation_list = ...
link_document_page_transformation_create = ...
link_document_page_transformation_edit = ...
link_document_page_transformation_delete = ...
Constants:
.. code-block:: bash
PERMISSION_SMART_LINK_VIEW = ...
PERMISSION_SMART_LINK_CREATE = ...
PERMISSION_SMART_LINK_DELETE = ...
PERMISSION_SMART_LINK_EDIT = ...
Classes:
.. code-block:: bash
class Document(models.Model):
class DocumentPage(models.Model):
class DocumentPageTransformation(models.Model):
class DocumentType(models.Model):
class DocumentTypeFilename(models.Model):
Strings
-------
Quotation character used in Mayan EDMS for strings is the single quote.
Double quote is used for multiple line comments or HTML markup.
Migrations
----------
Migrations should do only one thing (eg: either create a table, move data to a
new table or remove an old table) to aid retrying on failure.
General
-------
Code should appear in their modules in alphabetic order or in their order of
importance if it makes more sense for the specific application. This makes
visual scanning easier on modules with a large number of imports, views or
classes. Class methods that return a value should be pretended with a
``get_`` to differentiate from an object’s properties. When a variable refers
to a file it should be named as follows:
- filename: The file’s name and extension only.
- filepath: The entire path to the file including the filename.
- path: A path to a directory.
Flash messages should end with a period as applicable for the language.
Only exception is when the tail of the message contains an exceptions message
as passed directly from the exception object.
Source Control
==============
Mayan EDMS source is controlled with Git_.
The project is publicly accessible, hosted and can be cloned from **GitLab** using::
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
Git branch structure
--------------------
Mayan EDMS follows a simplified model layout based on Vincent Driessen's
`Successful Git Branching Model`_ blog post.
``develop``
The "next release" branch, likely unstable.
``master``
Current production release (|version|).
``feature/``
Unfinished/unmerged feature.
``series/``
Released versions.
Each release is tagged separately.
When submitting patches, please place your code in its own ``feature/`` branch
prior to opening a Merge Request on GitLab_.
.. _Git: http://git-scm.org
.. _`Successful Git Branching Model`: http://nvie.com/posts/a-successful-git-branching-model/
Steps to deploy a development version
=====================================
.. code-block:: bash
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
$ cd mayan-edms
$ git checkout development
$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ ./manage.py initialsetup
$ ./manage.py runserver
Contributing changes
====================
Follow the latest contributing guidelines outlined here: https://gitlab.com/mayan-edms/mayan-edms/blob/master/CONTRIBUTING.md
Debugging
=========
Mayan EDMS makes extensive use of Django's new `logging capabilities`_.
By default debug logging for all apps is turned on. If you wish to customize
how logging is managed turn off automatic logging by setting
`COMMON_AUTO_LOGGING` to ``False`` and add the following lines to your
``settings/local.py`` file::
LOGGING = {
'version': 1,
'disable_existing_loggers': True,
'formatters': {
'verbose': {
'format': '%(levelname)s %(asctime)s %(name)s %(process)d %(thread)d %(message)s'
},
'intermediate': {
'format': '%(name)s <%(process)d> [%(levelname)s] "%(funcName)s() %(message)s"'
},
'simple': {
'format': '%(levelname)s %(message)s'
},
},
'handlers': {
'console':{
'level':'DEBUG',
'class':'logging.StreamHandler',
'formatter': 'intermediate'
}
},
'loggers': {
'documents': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
'common': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
}
}
Likewise, to see the debug output of the ``tags`` app, just add the following inside the ``loggers`` block::
'tags': {
'handlers':['console'],
'propagate': True,
'level':'DEBUG',
},
.. _`logging capabilities`: https://docs.djangoproject.com/en/dev/topics/logging
Documentation
=============
The documentation is written in `reStructured Text`_ format, processed with
Sphinx_, and resides in the ``docs`` directory. In order to build it, you will
first need to install the documentation editing dependencies with::
$ pip install -r requirements/documentation.txt
Then, to build an HTML version of the documentation, run the following command
from the **docs** directory::
$ make docs-serve
The generated documentation can be viewed by browsing to http://127.0.0.1:8000
or by browsing to the ``docs/_build/html`` directory.
You can also generate the documentation in formats other than HTML. Consult the
Sphinx_ documentation for more details.
.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org
Installable package
===================
Source file package
-------------------
This is the sequence of step used to produce an installable package:
1. Generate the packaged version (will produce dist/mayan-edms-x.y.z.tar.gz)::
$ make sdist
2. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan-edms-x.y.z.tar.gz
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Wheel package
-------------
1. Install the development requirements::
$ pip install -r requirements/development.txt
2. Create wheel package using the makefile::
$ make wheel
3. Do a test install::
$ cd /tmp
$ virtualenv venv
$ source venv/bin/activate
$ pip install <path of the Git repository>/dist/mayan_edms-x.y.z-py2-none-any.whl
$ mayan-edms.py initialsetup
$ mayan-edms.py runserver
Version numbering
=================
Mayan EDMS uses the Semantic Versioning (http://semver.org/) method to choose
version numbers along with Python's PEP-0440 (https://www.python.org/dev/peps/pep-0440/)
to format them.
X.YaN # Alpha release
X.YbN # Beta release
X.YrcN # Release Candidate
X.Y # Final release
Release checklist
=================
1. Check for missing migrations::
make check-missing-migrations
2. Synchronize translations::
make translations-pull
3. Compile translations::
make translations-compile
4. Write release notes.
5. Update changelog.
6. Scan the code with flake8 for simple style warnings.
7. Check README.rst format with::
python setup.py check -r -s
or with::
make check-readme
8. Bump version in `mayan/__init__.py`.
9. Bump version in `docker/version`.
10. Update requirements version in `setup.py` using:
::
make generate-setup
11. Build source package and test:
::
make test-sdist-via-docker-ubuntu
12. Build wheel package and test:
::
make test-wheel-via-docker-ubuntu
13. Tag version:
::
git tag -a vX.Y.Z -m "Version X.Y.Z"
14. Switch to the `releases` branch:
::
git checkout releases
15. Push tag upstream:
::
git push --tags
16. Push code to trigger builds:
::
git push
17. Build and upload a test release:
::
make release-test-via-docker-ubuntu
18. Build and upload a final release:
::
make release-via-docker-ubuntu
docs/chapters/docker.rst
+423
View File
@@ -0,0 +1,423 @@
.. _docker:
============
Docker image
============
How to use this image
=====================
Start a Mayan EDMS instance
------------------------------
With Docker properly installed, proceed to download the Mayan EDMS image using the command::
docker pull mayanedms/mayanedms:<version>
Then download version 9.5 of the Docker PostgreSQL image::
docker pull postgres:9.5
Create and run a PostgreSQL container::
docker run -d \
--name mayan-edms-postgres \
--restart=always \
-p 5432:5432 \
-e POSTGRES_USER=mayan \
-e POSTGRES_DB=mayan \
-e POSTGRES_PASSWORD=mayanuserpass \
-v /docker-volumes/mayan-edms/postgres:/var/lib/postgresql/data \
-d postgres:9.5
The PostgreSQL container will have one database named ``mayan``, with an user
named ``mayan`` too, with a password of ``mayanuserpass``. The container will
expose its internal 5432 port (PostgreSQL's default port) via the host's
5432 port. The data of this container will reside on the host's
``/docker-volumes/mayan-edms/postgres`` folder.
Finally create and run a Mayan EDMS container. Change <version> with the
latest version in numeric form (example: 2.7.3) or use the ``latest``
identifier::
docker run -d \
--name mayan-edms \
--restart=always \
-p 80:8000 \
-e MAYAN_DATABASE_ENGINE=django.db.backends.postgresql \
-e MAYAN_DATABASE_HOST=172.17.0.1 \
-e MAYAN_DATABASE_NAME=mayan \
-e MAYAN_DATABASE_PASSWORD=mayanuserpass \
-e MAYAN_DATABASE_USER=mayan \
-e MAYAN_DATABASE_CONN_MAX_AGE=60 \
-v /docker-volumes/mayan-edms/media:/var/lib/mayan \
mayanedms/mayanedms:<version>
The Mayan EDMS container will connect to the PostgreSQL container via the
``172.17.0.1`` IP address (the Docker host's default IP address). It will
connect using the ``django.db.backends.postgresql`` database drivern and
connect to the ``mayan`` database using the ``mayan`` user with the password
``mayanuserpass``. The container will keep connections to the database
for up to 60 seconds in an attempt to reuse them increasing response time
and reducing memory usage. The files of the container will be store in the
host's ``/docker-volumes/mayan-edms/media`` folder. The container will
expose its web service running on port 8000 on the host's port 80.
The container will be available by browsing to ``http://localhost`` or to
the IP address of the computer running the container.
If another web server is running on port 80 use a different port in the
``-p`` option. For example: ``-p 81:8000``.
Using a dedicated Docker network
--------------------------------
Use this method to avoid having to expose PostreSQL port to the host's network
or if you have other PostgreSQL instances but still want to use the default
port of 5432 for this installation.
Create the network::
docker network create mayan
Launch the PostgreSQL container with the network option and remove the port
binding (``-p 5432:5432``)::
docker run -d \
--name mayan-edms-postgres \
--network=mayan \
--restart=always \
-e POSTGRES_USER=mayan \
-e POSTGRES_DB=mayan \
-e POSTGRES_PASSWORD=mayanuserpass \
-v /docker-volumes/mayan-edms/postgres:/var/lib/postgresql/data \
-d postgres:9.5
Launch the Mayan EDMS container with the network option and change the
database hostname to the PostgreSQL container name (``mayan-edms-postgres``)
instead of the IP address of the Docker host (``172.17.0.1``)::
docker run -d \
--name mayan-edms \
--network=mayan \
--restart=always \
-p 80:8000 \
-e MAYAN_DATABASE_ENGINE=django.db.backends.postgresql \
-e MAYAN_DATABASE_HOST=mayan-edms-postgres \
-e MAYAN_DATABASE_NAME=mayan \
-e MAYAN_DATABASE_PASSWORD=mayanuserpass \
-e MAYAN_DATABASE_USER=mayan \
-e MAYAN_DATABASE_CONN_MAX_AGE=60 \
-v /docker-volumes/mayan-edms/media:/var/lib/mayan \
mayanedms/mayanedms:<version>
Stopping and starting the container
--------------------------------------
To stop the container use::
docker stop mayan-edms
To start the container again::
docker start mayan-edms
Environment Variables
---------------------
The Mayan EDMS image can be configure via environment variables.
``MAYAN_DATABASE_ENGINE``
Defaults to ``None``. This environment variable configures the database
backend to use. If left unset, SQLite will be used. The database backends
supported by this Docker image are:
- ``'django.db.backends.postgresql'``
- ``'django.db.backends.mysql'``
- ``'django.db.backends.sqlite3'``
When using the SQLite backend, the database file will be saved in the Docker
volume. The SQLite database as used by Mayan EDMS is meant only for development
or testing, never use it in production.
``MAYAN_DATABASE_NAME``
Defaults to 'mayan'. This optional environment variable can be used to define
the database name that Mayan EDMS will connect to. For more information read
the pertinent Django documentation page: `Connecting to the database`_
.. _Connecting to the database: https://docs.djangoproject.com/en/1.10/ref/databases/#connecting-to-the-database
``MAYAN_DATABASE_USER``
Defaults to 'mayan'. This optional environment variable is used to set the
username that will be used to connect to the database. For more information
read the pertinent Django documentation page: `Settings, USER`_
.. _Settings, USER: https://docs.djangoproject.com/en/1.10/ref/settings/#user
``MAYAN_DATABASE_PASSWORD``
Defaults to ''. This optional environment variable is used to set the
password that will be used to connect to the database. For more information
read the pertinent Django documentation page: `Settings, PASSWORD`_
.. _Settings, PASSWORD: https://docs.djangoproject.com/en/1.10/ref/settings/#password
``MAYAN_DATABASE_HOST``
Defaults to `None`. This optional environment variable is used to set the
hostname that will be used to connect to the database. This can be the
hostname of another container or an IP address. For more information read
the pertinent Django documentation page: `Settings, HOST`_
.. _Settings, HOST: https://docs.djangoproject.com/en/1.10/ref/settings/#host
``MAYAN_DATABASE_PORT``
Defaults to `None`. This optional environment variable is used to set the
port number to use when connecting to the database. An empty string means
the default port. Not used with SQLite. For more information read the
pertinent Django documentation page: `Settings, PORT`_
.. _Settings, PORT: https://docs.djangoproject.com/en/1.11/ref/settings/#port
``MAYAN_BROKER_URL``
This optional environment variable determines the broker that Celery will use
to relay task messages between the frontend code and the background workers.
For more information read the pertinent Celery Kombu documentation page: `Broker URL`_
.. _Broker URL: http://kombu.readthedocs.io/en/latest/userguide/connections.html#connection-urls
This Docker image supports using Redis and RabbitMQ as brokers.
Caveat: If the `MAYAN_BROKER_URL` and `MAYAN_CELERY_RESULT_BACKEND` environment
variables are specified, the built-in Redis server inside the container will
be disabled.
``MAYAN_CELERY_RESULT_BACKEND``
This optional environment variable determines the results backend that Celery
will use to relay result messages from the background workers to the frontend
code. For more information read the pertinent Celery Kombu documentation page:
`Task result backend settings`_
.. _Task result backend settings: http://docs.celeryproject.org/en/3.1/configuration.html#celery-result-backend
This Docker image supports using Redis and RabbitMQ as result backends.
Caveat: If the `MAYAN_BROKER_URL` and `MAYAN_CELERY_RESULT_BACKEND` environment
variables are specified, the built-in Redis server inside the container will
be disabled.
``MAYAN_SETTINGS_MODULE``
Optional. Allows loading an alternate settings file.
``MAYAN_DATABASE_CONN_MAX_AGE``
Amount in seconds to keep a database connection alive. Allow reuse of database
connections. For more information read the pertinent Django documentation
page: `Settings, CONN_MAX_AGE`_
.. _Settings, CONN_MAX_AGE: https://docs.djangoproject.com/en/1.10/ref/settings/#conn-max-age
``MAYAN_GUNICORN_WORKERS``
Optional. This environment variable controls the number of frontend workers
that will be executed. If not specified the default is 2. For heavier loads,
user a higher number. A formula recommended for this setting is the number
of CPU cores + 1.
``MAYAN_WORKER_FAST_CONCURRENCY``
Optional. Changes the concurrency (number of child processes) of the Celery
worker consuming the queues in the fast (low latency, short tasks) category.
Default is 1. Use 0 to disable hardcoded concurrency and allow the Celery
worker to launch its default number of child processes (equal to the number
of CPUs detected).
``MAYAN_WORKER_MEDIUM_CONCURRENCY``
Optional. Changes the concurrency (number of child processes) of the Celery
worker consuming the queues in the medium (medium latency, long running tasks)
category. Default is 1. Use 0 to disable hardcoded concurrency and allow the
Celery worker to launch its default number of child processes (equal to the
number of CPUs detected).
``MAYAN_WORKER_SLOW_CONCURRENCY``
Optional. Changes the concurrency (number of child processes) of the Celery
worker consuming the queues in the slow (high latency, very long running tasks)
category. Default is 1. Use 0 to disable hardcoded concurrency and allow the
Celery worker to launch its default number of child processes (equal to the
number of CPUs detected).
Accessing outside data
======================
To use Mayan EDMS's staging folders or watch folders from Docker, the data
for these source must be made accessible to the container. This is done by
mounting the folders in the host computer to folders inside the container.
This is necessary because Docker containers do not have access to host data
on purpose. For example, to make a folder in the host accessible as a watch
folder, add the following to the Docker command line when starting the
container::
-v /opt/scanned_files:/srv/watch_folder
The command line would look like this::
docker run ... -v /opt/scanned_files:/srv/watch_folder mayanedms/mayanedms:latest
Now create a watch folder in Mayan EDMS using the path ``/srv/watch_folder``
and the documents from the host folder ``/opt/scanned_files`` will be
automatically available. Use the same procedure to mount host folders to be
used as staging folderes. In this example ``/srv/watch_folder`` was as the
container directory, but any path can be used as long as it is not an
already existing path or a path used by any other program.
Performing backups
==================
To backup the existing data, stop the image and copy the content of the volume.
For the example::
docker run -d --name mayan-edms --restart=always -p 80:8000 \
-v /docker-volumes/mayan:/var/lib/mayan \
-v /opt/scanned_files:/srv/watch_folder mayanedms/mayanedms:latest
That would be the ``/docker-volumes/mayan folder``::
sudo tar -zcvf backup.tar.gz /docker-volumes/mayan
sudo chown `whoami` backup.tar.gz
If using an external PostgreSQL or MySQL database or database containers, these
too need to be backed up using their respective procedures. A simple solution
is to copy the entire database container volume after the container has
been stopped.
Restoring from a backup
=======================
Uncompress the backup archive in the original docker volume using::
sudo tar -xvzf backup.tar.gz -C /
Upgrading
=========
Upgrading a Mayan EDMS Docker container is actually a matter of stopping and
deleting the container, downloading the most recent version of the image and
starting a container again. The container will take care of updating the
database structure to the newest version if necessary.
**IMPORTANT!** Do not delete the volume storing the data, only the container.
Stop the container to be upgraded::
docker stop mayan-edms
Remove the container::
docker rm mayan-edms
Pull the new image version::
docker pull mayanedms/mayanedms:latest
Start the container again with the new image version::
docker run -d --name mayan-edms --restart=always -p 80:8000 -v /docker-volumes/mayan:/var/lib/mayan mayanedms/mayanedms:latest
Building the image
==================
Clone the repository with::
git clone https://gitlab.com/mayan-edms/mayan-edms.git
Change to the directory of the cloned repository::
cd mayan-edms
Execute Docker's build command using the provided makefile::
make docker-build
Or using an apt cacher to speed up the build::
make docker-build-with-proxy APT_PROXY=172.17.0.1:3142
Replace the IP address `172.17.0.1` with the IP address of the computer
running the APT proxy and caching service.
Customizing the image
=====================
Simple method
-------------
If you just need to add a few Ubuntu or Python packages to your installation,
you can use the following environment variables:
``MAYAN_APT_INSTALLS``
Specifies a list of Ubuntu .deb packages to be installed via APT when the
container is first created. The installed packages are not lost when the image
is stopped. Example: To install the Tesseract OCR language packs for German
and Spanish add the following in your ``docker start`` command line::
-e MAYAN_APT_INSTALLS="tesseract-ocr-deu tesseract-ocr-spa"
``MAYAN_PIP_INSTALLS``
Specifies a list of Python packages to be installed via ``pip``. Packages will
be downloaded from the Python Package Index (https://pypi.python.org) by
default.
Using Docker compose
====================
To deploy a complete production stack using the included Docker compose file
execute::
docker-compose -f docker-compose.yml up -d
This Docker compose file will provision four containers:
- Postgres as the database
- Redis as the Celery result storage
- RabbitMQ as the Celery broker
- Mayan EDMS using the above service containers
To stop the stack use::
docker-compose -f docker-compose.yml stop
The stack will also create four volumes to store the data of each container.
These are:
- mayan_app - The Mayan EDMS data container, normally called `mayan_data` when not using Docker compose.
- mayan_broker - The broker volume, in this case RabbitMQ.
- mayan_db - The database volume, in this case Postgres.
- mayan_results - The celery result backend volume, in this case Redis.
Nightly images
==============
The continious integration pipeline used for testing development builds also
produces a resulting Docker image. These are build automatically and their
stability is not guaranteed. They should never be used in production.
If you want to try out the Docker images the development uses or want a sneak
peek at the new features being worked on checkout the container registry at:
https://gitlab.com/mayan-edms/mayan-edms/container_registry
docs/chapters/document_types.rst
+74
View File
@@ -0,0 +1,74 @@
.. _document_types:
Document types
==============
The basic unit of data in Mayan EDMS is the ``document type``. A document
type can be interpreted also as a document category, a document class, or a
document template. Every other aspect of the system will rely or be tied to
one or more document type. Create one document type for each type or class of
document you intend to upload into Mayan EDMS.
Document types need to be created before documents can be
uploaded. It is not possible to upload documents without assigning them a
document type.
Document types usually mirror the type of physical, paper document they
represent.
Example document types:
* Letter
* Invoice
* Timesheet
* Blueprint
.. blockdiag::
blockdiag {
default_shape = roundedbox
document_type [ label = 'each document type' ];
documents [ label = 'many documents' ];
document_type -> documents;
}
Examples:
.. blockdiag::
blockdiag {
default_shape = roundedbox
document_type [ label = 'Invoice' ];
documents_1 [ label = 'invoice_001.pdf', width=200 ];
documents_2 [ label = 'invoice_032.pdf', width=200 ];
document_type -> documents_1, documents_2;
}
.. blockdiag::
blockdiag {
default_shape = roundedbox
document_type [ label = 'Receipts' ];
documents_1 [ label = 'groceries_18-01-11.pdf', width=200 ];
documents_2 [ label = 'car_payment-17-01-02.png', width=200 ];
document_type -> documents_1, documents_2;
}
Settings and attributes are applied to document types and documents will
inherit those settings and attributes based on the document type they were
assigned when uploaded into Mayan EDMS. A document can only be of one
type at a given moment, but if needed, the type of a document can be changed.
Upon changing its type, the document will lose its previous settings and
attributes, and will inherit the settings and attributes of its new type.
Document types are create in the
:menuselection:`System --> Setup --> Document types` menu.
docs/chapters/file_storage.rst
+36
View File
@@ -0,0 +1,36 @@
************
File storage
************
The files are stored and placed under Mayan EDMS "control" to avoid
filename clashes each file gets renamed to its ``UUID`` (Universally Unique ID),
without extension, and stored in a simple flat arrangement in a directory.
.. blockdiag::
blockdiag {
default_shape = roundedbox
file [ label = 'mayan_1-1.pdf', width=120];
document [ label = 'mayan/media/document_storage/ab6c1cfe-8a8f-4a30-96c9-f54f606b9248', width=450];
file -> document [label = "upload"];
file -> document;
}
This doesn't stop access to the files but renaming, moving or updating
directly them is not recommended because it would throw the database out
of sync.
Because Mayan EDMS components are as decoupled from each other as possible,
storage in this case is decoupled and its behavior is controlled
not by the project but by the ``Storage`` module class. All the other
modules don't make any 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 still operate exactly the same.
The default file storage backend: ``storage.backends.filebasedstorage.FileBasedStorage``
is a simple backend that only supports paths and not IP addresses. In case you
are interested in using remote volumes to store documents (NFS, SAMBA), first
mount these volumes so that they appear as a directories to Mayan EDMS. For
direct support for remote volumes a custom backend would be needed such as those
provided by the Django Storages project (https://django-storages.readthedocs.org/en/latest/).
docs/chapters/index_examples.rst
+111
View File
@@ -0,0 +1,111 @@
Index examples
--------------
Index of document types
^^^^^^^^^^^^^^^^^^^^^^^
This index will create one level for each document type in the system and place
links to the document of each respective type.
#. Go to the :menuselection:`System --> Setup --> Indexes` menu.
#. Create a new index using :menuselection:`Actions --> Create new`.
#. Give it a label to describe it, and an internal name. The internal name is
used when referencing this index in other parts of the system.
#. Press the :menuselection:`Template` link of the newly created index.
#. Select :menuselection:`New child node` to create a new level in which the
following template code will be entered.
::
{{ document.document_type }}
#. Save the template.
#. Go to :menuselection:`Document types` and associate this index with
existing document types in the system.
#. Finally go to :menuselection:`Tools --> Rebuild indexes` to execute the
index template. The rebuild process is only necesary when changes are
made to the index templates. Otherwise they update automatically whenever
a new document is uploaded or existing documents properties are modified.
#. A new index should appear under :menuselection:`Indexes` menu.
You can also program different behavior based on the different document types,
by use a comparison and a conditional statement. As the document_type itself
is not a string you cannot directly use that for that comparison. You will have
to use the label of the document type.
For example::
{% if document.document_type.label == "Invoice" or document.document_type.label == "Letter" %}
Correspondence
{% else %}
{{ document.document_type }}
{% endif %}
This will create and index level for each document type. Except for documents
of types "Invoice" and "Letter", these will now go into the level "Correspondence".
Index document by department, taken from the first character of the invoice number metadata
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Requires one index node with the template::
{% if document.metadata_value_of.invoice_number.0 == "A" %}Accounting
{% if document.metadata_value_of.invoice_number.0 == "H" %}Human Resources
{% endif %}
Nested date index from a date contained in a metadata
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Assuming the metadata type is named **date_issued** with a date format
of YYYY-MM-DD. The target is to have two levels: one for years and another
sub level for months.
**First level: Year**
::
{{ document.metadata_value_of.date_issued|slice:"0:4" }}
**Second level: Months**
::
{{ document.metadata_value_of.date_issued|slice:"5:7" }}
**Optional: Third level: Day**
::
{{ document.metadata_value_of.date_issued|slice:"8:10" }}
Index by OCR content
^^^^^^^^^^^^^^^^^^^^
This example indexes documents in a "quarterly report" level if they have the
fragment “quarterly report” in the OCR text::
{% if "quarterly report" in document.latest_version.ocr_content|join:" "|lower %}Quarterly reports{% endif %}
The same applies to text content extracted for the document::
{% if "quarterly report" in document.latest_version.content|join:" "|lower %}Quarterly reports{% endif %}
Index documents not found in any cabinet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
{% if document.cabinets.count == 0 %}No Cabinets{% endif %}
Index untagged documents
^^^^^^^^^^^^^^^^^^^^^^^^
::
{% if document.tags.count == 0 %}No Tags{% endif %}
Index documents specifically, by the year of a metadata field otherwise by their uploaded year
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
{% for tag in document.tags.all %}{% if tag.label == "Taxes" %}{% if document.metadata_value_of.tax_year|length_is:"4" %}{{ document.metadata_value_of.tax_year }}{% else %}{{ document.date_added|date:"Y" }}{% endif %}{% endif %}{% endfor %}
docs/chapters/indexes.rst
+115
View File
@@ -0,0 +1,115 @@
Indexes
=======
Indexes are an automatic method to hierarchically organize documents in
relation to their properties (:doc:`metadata`, label, MIME type, etc). To use
indexes you need to first create an index template. Once created, associate
the index to one or more :doc:`document_types`.
Index are hierarchical models so a tree template needs to be specified for them.
This tree template will contain references to document metadata or properties
that will be replaced with the actual value for those metadata or properties.
Example:
- Document type: ``Product sheet``
- Metadata type: ``Product year``, associated as a required metadata for the document type ``Product sheet``.
- Index: ``Product sheets per year``, and associated to the document type ``Product sheet``.
- Index slug: ``product-sheets-per-year``. Slugs are internal unique identifiers that can be used by other Mayan EDMS modules to reference each index.
- Index tree template as follows:
.. blockdiag::
blockdiag {
default_shape = roundedbox
span_width = 30;
index [ label = 'Product sheets per year', width=180 ];
root [ label = 'Root (Has document links? No)', width=450];
level_2 [ label = '{{ document.metadata_value_of.product_year }} (Has document links? Yes)', width=450];
group {
label = "Tree template";
color = "#dddddd";
style = dashed;
root; level_2;
}
index -> root
root -> level_2 [folded];
}
Now every time a new ``Product sheet`` is uploaded a hierarchical unit with the value
of the metadata type ``Product year`` is created and a link to the uploaded ``Product sheet`` added to it.
Example:
Suppose three ``Product sheets`` are uploaded with the following values as their
``Product year`` metadata: 2001, 2002, 2001 respectively. The result index
that will be generate based on the tree template would be as follows:
.. blockdiag::
blockdiag {
default_shape = roundedbox
index [ label = 'Product sheets per year', width=180 ];
year_1 [ label = '2001', width = 60 ];
year_2 [ label = '2002', width = 60 ];
document_1 [ label = 'Product A data sheet (2001)', width = 200 ];
document_2 [ label = 'Product B data sheet (2002)', width = 200 ];
document_3 [ label = 'Product C data sheet (2001)', width = 200 ];
group {
label = "Index content";
color = "#dddddd";
style = dashed;
year_1, year_2, document_1, document_2, document_3;
}
index -> year_1;
index -> year_2;
year_1 -> document_1;
year_2 -> document_2;
year_1 -> document_3;
}
.. include:: ../chapters/index_examples.rst
Mirroring
---------
Indexes can be exported as `FUSE <https://en.wikipedia.org/wiki/Filesystem_in_Userspace>`_
filesystems. Using the management command ``mountindex`` we could export the
previous example index as follows::
mkdir -p ~/indexes/products
mayan-edms.py mountindex product-sheets-per-year ~/indexes/products
The ``~/indexes/products`` directory will now have a directory and files structure
identical to that of the index. Once indexes are mounted with this command, they
behave like any other filesystem directory and can even be further shared
via the network with network file system software like
`Samba <https://www.samba.org/>`_ or
`NFS <https://en.wikipedia.org/wiki/Network_File_System>`_.
.. blockdiag::
blockdiag {
orientation = portrait
span_width = 200;
index [ label = 'Product sheets per year', width=180 ];
block_device [ height = 100, label = "Block device\n(Hard drive)", shape = flowchart.database ];
network [ label = "Network", shape = cloud ];
user [ label = "Users", shape = actor ];
index -> block_device [ label = "mirroring", fontsize = 8 ];
block_device -> network -> user;
}
Indexes and mirrored indexes are Read Only as they are generated as a result of
prior activities like document uploads, metadata changes.
docs/chapters/languages.rst
+36
View File
@@ -0,0 +1,36 @@
*********
Languages
*********
The list of languages choices in the language dropdown used for documents is
based on the current ISO 639 list. This list can be quite extensive. To reduce
the number of languages available use the setting ``DOCUMENTS_LANGUAGE_CODES``,
and set it to a nested list of abbreviations. This setting can be found in the
:menuselection:`System --> Setup -> Settings -> Common` menu.
For example, to reduce the list to just English and Spanish use
::
DOCUMENTS_LANGUAGE_CODES = ('eng', 'spa')
The default language to appear on the dropdown can also be configured using::
DOCUMENTS_LANGUAGE = 'spa'
Use the correct ISO 639-3 language abbreviation (https://en.wikipedia.org/wiki/ISO_639)
as this code is used in several subsystems in Mayan EDMS such as the OCR app
to determine how to interpret the document.
If using the Docker image, these settings can also be passed to the container
as environment variables by prepending the ``MAYAN_`` suffix.
Example::
-e MAYAN_DOCUMENTS_LANGUAGE_CODES='["eng", "spa"]'
For more information check out the
:ref:`environment variables <environment_variables>` section of the
:doc:`../chapters/settings` chapter.
docs/chapters/mailing.rst
+37
View File
@@ -0,0 +1,37 @@
*****************
Mailing documents
*****************
Sending emails in Mayan EDMS is controlled by two different system depending on
the type of email being sent. These are administrative emails like password
reset emails and user emails sent from the application.
Sending administrative emails
=============================
To be able to send password reset emails configure the Django email settings
via the :ref:`configuration file <configuration_file>`.
Example::
EMAIL_BACKEND: django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST: '<your smtp ip address or hostname>'
EMAIL_HOST_PASSWORD: '<your smtp password>'
EMAIL_HOST_USER: '<your smtp username>'
EMAIL_PORT: 25 # or 587 or your server's SMTP port
EMAIL_TIMEOUT:
EMAIL_USE_SSL: true
EMAIL_USE_TLS: false
For more details consult Django's documentation on the topic:
https://docs.djangoproject.com/en/1.11/ref/settings/#email-backend
Application emails
==================
To allow users to send emails or documents from within the web interface,
Mayan EDMS provides its our own email system called Mailing Profiles.
Mailing Profiles support access control per user role and can use different
email backends. Mailing Profiles are created from the
:menuselection:`System --> Setup` menu.
docs/chapters/metadata.rst
+28
View File
@@ -0,0 +1,28 @@
********
Metadata
********
Metadata is the name of the attribute of a document. The concept of metadata is
divided in two: **metadata types** (size, color, distance) and **metadata values** for
those types. Metadata types are defined in the setup menu and associated with
document types. Then when a document is uploaded, a value for that metadata
can be entered. There are two kinds of metadata type to document type relations:
optional and required. When a metadata type is optional for a document type,
it can be left blank for a document being uploaded and the upload will still
be successful. On the other hand required metadata type must be given a value
or it will not be possible to upload the document at hand.
Examples of metadata type: Invoice number, color, employee id.
The data entry of metadata types can be set to allow any value to be provided
(the default) or a list of possible values can be entered in the ``Lookup``
configuration option and users will be presented with a drop down list of options
instead of the default text entry box.
If metadata types are setup to allow any value to be entered a ``validation``
option can be chosen to block the entry of invalid data. Metadata types also
provide ``parsers`` which will not block the entry of data but are able to
interpret and modify the value provided by the user to a conform to a specific
format. An example of a provided parser is the date parser which will interpret
and correct dates provided by users regardless of the format in which they are
entered.
docs/chapters/object_storage.rst
+62
View File
@@ -0,0 +1,62 @@
.. _object_storage:
**************
Object storage
**************
It is possible to use object storage instead of the default filesystem based
storage. One such object storage system is Amazon S3 (Simple Storage Service)
API compatible object storage. The following steps will configure Mayan EDMS
to use a S3 style storage for documents.
1. Install the django-storages and boto3 Python libraries.
* For the direct deployment method of installation use::
pip install django-storages boto3
* or if using the Docker image, add the following the command line that runs the container::
-e MAYAN_PIP_INSTALLS='django-storages boto3'
2. From the web interface navigate to the :menuselection:`System --> Setup --> Setting --> Documents` menu.
3. Locate the **DOCUMENTS_STORAGE_BACKEND** setting, press **Edit** and enter::
storages.backends.s3boto3.S3Boto3Storage
4. Save and locate the setting **DOCUMENTS_STORAGE_BACKEND_ARGUMENTS**, press **Edit** and enter::
'{access_key: <your S3 access key>, secret_key: <your S3 secret key>, bucket_name: <S3 bucket name>}'
5. Save and restart your Mayan EDMS installation for the setting to take effect.
Storage
=======
Mayan EDMS stores documents in their original file format only changing the
filename to avoid collision. For best input and output speed use a block
based local filesystem for the ``/media`` sub folder of the path specified by
the MEDIA_ROOT setting. For increased storage capacity use an object storage
filesystem like S3.
To use a S3 compatible object storage do the following:
* Install the Python packages ``django-storages`` and ``boto3``:
* Using Python::
pip install django-storages boto3
* Using Docker::
-e MAYAN_PIP_INSTALLS='django-storages boto3'
On the Mayan EDMS user interface, go to ``System``, ``Setup``, ``Settings``,
``Documents`` and change the following setting:
* ``DOCUMENTS_STORAGE_BACKEND`` to ``storages.backends.s3boto3.S3Boto3Storage``
* ``DOCUMENTS_STORAGE_BACKEND_ARGUMENTS`` to ``'{access_key: <your access key>, secret_key: <your secret key>, bucket_name: <bucket name>}'``.
Restart Mayan EDMS for the changes to take effect.
docs/chapters/ocr_backend.rst
+21
View File
@@ -0,0 +1,21 @@
***********
OCR backend
***********
Mayan EDMS ships an OCR backend that uses the FLOSS engine Tesseract
(https://github.com/tesseract-ocr/tesseract/), but it can
use other engines. To support other engines crate a wrapper that subclasess the
``OCRBackendBase`` class defined in mayan/apps/ocr/classes. This subclass should
expose the ``execute`` method. For an example of how the Tesseract backend
is implemented take a look at the file ``mayan/apps/ocr/backends/tesseract.py``
Once you create you own backend, in your local.py settings add the option
OCR_BACKEND and point it to your new OCR backend class path.
The default value of OCR_BACKEND is ``"ocr.backends.tesseract.Tesseract"``
To add support to OCR more languages when using Tesseract, install the
corresponding language file. If using a Debian based OS, this command will
display the available language files:
apt-cache search tesseract-ocr
docs/chapters/permissions.rst
+30
View File
@@ -0,0 +1,30 @@
***********
Permissions
***********
Mayan EDMS provides very fine control over which actions users can
perform. Action control works by allowing ``roles``, that are composed of
``groups`` of ``users`` to be granted a ``permission`` such that the holder of
that permission can exercise it throughout the entire system.
.. blockdiag::
blockdiag {
orientation = portrait
default_shape = roundedbox
span_width = 240;
span_height = 100;
user [ label = 'Users' ];
group [ label = 'Groups' ];
role [ label = 'Roles' ];
permission [ label = 'Permissions' ];
user -> group -> role <- permission;
}
In other words, users themselves can't hold a permission, permissions are
granted only to roles. Users can't directly belong to a role, they can only
belong to a group. Groups can be members of roles. Roles are system permission
units and groups are business organizational units.
docs/chapters/scaling_up.rst
+175
View File
@@ -0,0 +1,175 @@
.. _scaling_up:
**********
Scaling up
**********
The default installation method fits most use cases. If you use case requires
more speed or capacity here are some suggestion that can help you improve the
performance of your installation.
Change the database manager
===========================
Use PostgreSQL or MySQL as the database manager.
Tweak the memory setting of the database manager to increase memory allocation.
More PostgreSQL especific examples are available in their wiki page:
https://wiki.postgresql.org/wiki/Performance_Optimization
Increase the number of Gunicorn workers
=======================================
The Gunicorn workers process HTTP requests and affect the speed at which the
website responds.
If you are using the Docker image, change the value of the
MAYAN_GUNICORN_WORKERS (https://docs.mayan-edms.com/topics/docker.html#environment-variables)
environment variable. Normally this variable defaults to 2. Increase this
number to match the number of CPU cores + 1.
If you are using the direct deployment methods, change the line that reads::
command = /opt/mayan-edms/bin/gunicorn -w 2 mayan.wsgi --max-requests 500 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
And increase the value of the ``-w 2`` argument. This line is found in the
``[program:mayan-gunicorn]`` section of the supervisor configuration file.
Background task processing
==========================
The Celery workers are system processes that take care of the background
tasks requested by the frontend interactions like document image rendering
and periodic tasks like OCR. There are several dozen tasks defined in the code.
These tasks are divided into queues based on the app of the relationship
between the tasks. The queues by default are divided into three groups
based on the speed at which they need to be processed. The document page
image rendering for example is categorized as a high volume, short duration
task. The OCR is a high volume, long duration task. Email checking is a
low volume, medium duration tasks. It is not advisable to have the same
worker processing OCR to process image rendering too. If the worker is
processing several OCR tasks it will not be able to provide fast images
when an user is browsing the user interface. This is why by default the
queues are split into 3 workers: fast, medium, and slow.
The fast worker handles the queues:
* converter: Handles document page rendering
* sources_fast: Does staging file image rendering
The medium worker handles the queues:
* checkouts_periodic: Scheduled tasks that check if a document's checkout
period has expired
* documents_periodic:
* indexing: Does reindexing of documents in the background when their
properties change
* metadata:
* sources:
* sources_periodic: Checking email accounts and watch folders for new
documents.
* uploads: Processes files to turn the into Mayan documents. Processing
encompasses MIME type detection, page count detection.
* documents:
The slow worker handles the queues:
* mailing: Does the actual sending of documents via email as requested by
users via the mailing profiles
* tools: Executes in the background maintenance requests from the options
in the tools menu
* statistics: Recalculates statistics and charts
* parsing: Parses documents to extract actual text content
* ocr: Performs OCR to transcribe page images to text
Optimizations
-------------
* Increase the number of workers and redistribute the queues among them
(only possible with direct deployments).
* Launch more workers to service a queue. For example for faster document
image generation launch 2 workers to process the converter queue only
possible with direct deployments).
* By default each worker process uses 1 thread. You can increase the thread
count of each worker process with the Docker environment options:
* MAYAN_WORKER_FAST_CONCURRENCY
* MAYAN_WORKER_MEDIUM_CONCURRENCY
* MAYAN_WORKER_SLOW_CONCURRENCY
* If using direct deployment, increase the value of the --concurrency=1
argument of each worker in the supervisor file. You can also remove this
argument and let the Celery algorithm choose the number of threads to
launch. Usually this defaults to the number of CPU cores + 1.
Change the message broker
=========================
Messages are the method of communication between front end interactive code
and background tasks. In this regard messages can be thought as homologous
to tasks requests. Improving how many messages can be sent, stored and
sorted will impact the number of tasks the system can handle. To save on
memory, the basic deployment method and the Docker image default to using
Redis as a message broker. To increase capacity and reduce volatility of
messages (pending tasks are not lost during shutdown) use RabbitMQ to
shuffle messages.
For direct installs refer to the Advanced deployment method
(https://docs.mayan-edms.com/topics/deploying.html#advanced-deployment) for
the required changes.
For the Docker image, launch a separate RabbitMQ container
(https://hub.docker.com/_/rabbitmq/)::
docker run -d --name mayan-edms-rabbitmq -e RABBITMQ_DEFAULT_USER=mayan -e RABBITMQ_DEFAULT_PASS=mayanrabbitmqpassword -e RABBITMQ_DEFAULT_VHOST=mayan rabbitmq:3
Pass the MAYAN_BROKER_URL environment variable (https://kombu.readthedocs.io/en/latest/userguide/connections.html#connection-urls)
to the Mayan EDMS container so that it uses the RabbitMQ container the
message broker::
-e MAYAN_BROKER_URL="amqp://mayan:mayanrabbitmqpassword@localhost:5672/mayan",
When tasks finish, they leave behind a return status or the result of a
calculation, these are stored for a while so that whoever requested the
background task, is able retrieve the result. These results are stored in the
result storage. By default a Redis server is launched inside the Mayan EDMS
container. You can launch a separate Docker Redis container and tell the Mayan
EDMS container to use this via the MAYAN_CELERY_RESULT_BACKEND environment
variable. The format of this variable is explained here: http://docs.celeryproject.org/en/3.1/configuration.html#celery-result-backend
Deployment type
===============
Docker provides a faster deployment and the overhead is not high on modern
systems. It is however memory and CPU limited by default and you need to
increase this limits. The settings to change the container resource limits
are here: https://docs.docker.com/config/containers/resource_constraints/#limit-a-containers-access-to-memory
For the best performance possible use the advanced deployment method on a
host dedicated to serving only Mayan EDMS.
Storage
=======
For best input and output speed use a block based local filesystem on an
SSD drive for the ``/media`` sub folder. The location of the ``/media`` folder
will be specified by the ``MEDIA_ROOT`` setting.
If capacity is your bottom line, switch to an
:ref:`object storage <object_storage>` system.
Use additional hosts
====================
When one host is not enough you can use multiple hosts and share the load.
Make sure that all hosts share the ``/media`` folder as specified by the
``MEDIA_ROOT`` setting, also the database, the broker, and the result storage.
One setting that needs to be changed in this configuration is the lock
manager backend.
Resource locking is a technique to avoid two processes or tasks to modify
the same resource at the same time causing a race condition. Mayan EDMS uses
its own lock manager. By default the lock manager with use a simple file
based lock backend ideal for single host installations. For multiple hosts
installation the database backend must be used in other to coordinate the
resource locks between the different hosts over a share data medium. This is
accomplished by modifying the environment variable ``LOCK_MANAGER_BACKEND`` in
both the direct deployment or the Docker image. Use the value
``lock_manager.backends.model_lock.ModelLock`` to switch to the database
resource lock backend. If you can also write your own lock manager backend
for other data sharing mediums with better performance than a relational
database like Redis, Memcached, Zoo Keeper.
docs/chapters/settings.rst
+107
View File
@@ -0,0 +1,107 @@
Mayan EDMS can be configure via environment variables or by setting files.
.. _environment_variables:
Via environment variables
=========================
To use environment variables, lookup the name of the setting you want to
override in the "Settings" menu. The "Settings" menu is located inside the
"Setup" main menu. To pass a value via an environment variable append
``"MAYAN_"`` to the name of the settings option. For example, to change
the number of documents displayed per page (COMMON_PAGINATE_BY, by default 40),
use::
export MAYAN_COMMON_PAGINATE_BY=10
Restart Mayan EDMS and the new value will take effect. The "Settings" menu
can be used to verify if the overridden setting value is being interpreted
correctly.
.. _configuration_file:
Via YAML configuration file
===========================
.. versionadded:: 3.1
It is possible to modify the different settings by creating or editing the
``media/config.yml`` file. This file is formatted in the YAML markup language (
http://yaml.org/). Here is an example of what the looks like::
DOCUMENT_PARSING_AUTO_PARSING: true
DOCUMENT_PARSING_PDFTOTEXT_PATH: /usr/bin/pdftotext
EMAIL_BACKEND: django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST: localhost
EMAIL_HOST_PASSWORD: ''
EMAIL_HOST_USER: ''
EMAIL_PORT: 25
EMAIL_TIMEOUT: null
EMAIL_USE_SSL: false
EMAIL_USE_TLS: false
FILE_UPLOAD_MAX_MEMORY_SIZE: 2621440
HOME_VIEW: common:home
Every time Mayan EDMS is able to start correctly it will copy the ``config.yml``
and create a backup copy in the same directory named ``config_backup.yml``.
This file is used to revert to the last know configuration file known
to be valid. You can revert manually by copy the file or by using the
``revertsettings`` management command from the command line.
Via Python settings files
=========================
Another way to configure Mayan EDMS is via Python-style, settings files.
If Mayan EDMS was installed using the Python package a ``mayan_settings``
folder will created for this purpose. If you installed Mayan EDMS
according to the :ref:`deploying` instructions provided in this
documentation your ``mayan_settings`` folder should be located in the directory:
``/usr/share/mayan-edms/mayan/media/mayan_settings``.
If Mayan EDMS was installed using Docker, the ``mayan_settings`` folder
will be found inside the install Docker volume. If you installed Mayan EDMS
according to the :ref:`docker` instructions provided in this documentation
your ``mayan_settings`` folder should be located in the directory:
``/docker-volumes/mayan/mayan_settings``.
Create a file with any valid name and a ``.py`` extension in the
``mayan_settings`` folder. The file must starts with a global import of
``mayan.settings.production``. In the form::
from mayan.settings.production import *
Now add the corresponding lines to override the default settings.
In the settings file, it is not necessary to prepend the string ``MAYAN_`` to
the setting option. For example, to change the number of documents displayed
per page (COMMON_PAGINATE_BY, by default 40),
use::
COMMON_PAGINATE_BY=10
versus::
export MAYAN_COMMON_PAGINATE_BY=10
when using the environment variable method.
For this example let's assume the file was saved with the name ``mysettings.py``.
The way used to tell Mayan EDMS to import this file will vary based on the
installation method.
For the :ref:`deploying` method, the full import path will be
``mayan.media.mayan_settings.mysettings`` and can be passed via the
``--settings`` command line argument like this::
python manage.py runserver --settings=mayan.media.mayan_settings.mysettings
or via the ``DJANGO_SETTINGS_MODULE`` environment variable like this::
export DJANGO_SETTINGS_MODULE=mayan.media.mayan_settings.mysettings
For the :ref:`docker` installation method, the full import path will be
``mayan_settings.mysettings`` and can only be passed via the
``MAYAN_SETTINGS_MODULE`` environment variable like this::
docker run <...> -e MAYAN_SETTINGS_MODULE=mayan_settings.mysettings
docs/chapters/signatures.rst
+45
View File
@@ -0,0 +1,45 @@
*******************
Document signatures
*******************
Mayan EDMS supports two types of document signatures: embedded and
detached signatures. When a document with an embedded signature is
uploaded, this signature is readily detected as part of the document
inspection step. The status of the signature can be verified by accessing the
signatures sections of a document.
.. blockdiag::
blockdiag {
orientation = portrait
span_width = 240;
user [ shape = "actor" ];
key [ shape = flowchart.database, label = "Key" ];
document [ shape = "note", label = "Document" ];
document_signed [ label = "Signed\nDocument" ];
key -> user -> document -> document_signed;
}
Signed documents are tamper-proof. That means that if any part of the document's
file is edited (even just one character or one pixel), the document's
signature becomes invalid alerting that an unauthorized change has occurred.
Existing non signed documents can be signed in one of two ways:
by downloading the document, signing it, and uploading the signed document
as a new version of the existing one or by creating a detached signature for
the non signed document and uploading such detached signature file.
Maintenance of the public keyring can be done using the ``Key management``
functionality in the ``Setup menu``.
From this menu, key servers can be queried and the results imported. Public
keys no longer needed can also be deleted from this menu.
Only `GNU Privacy Guard`_ signatures are support at the moment.
Only version 1 of `GNU Privacy Guard`_ is supported at the moment.
.. _`GNU Privacy Guard`: www.gnupg.org/
docs/chapters/smart_links.rst
+31
View File
@@ -0,0 +1,31 @@
Smart links
===========
Smart links are a way to link documents without changing how they are organized
in their respective indexes. Smart links are useful when two documents are
related somehow but are of different type or different hierarchical units.
Example: A patient record can be related to a prescription drug information
document, but they each belong to their own :doc:`indexes`.
Smart links are rule based, but don't create any organizational structure.
Smart links just show the documents that match the rules as evaluated against
the metadata or properties of the currently displayed document.
Indexes are automatic hierarchical units used to group documents, smart links
are automatic references between documents.
Example:
- Document type: ``Patient records``
- Metadata type: ``Prescription``, associated as an optional metadata for the document type ``Patient records``.
- Document type: ``Prescription information sheets``
A smart link with the following condition, will automatically links patient
records to the prescription information sheets based on the value of the
metadata type of the patient record.
.. code-block:: bash
foreign label is equal to {{ document.metadata_value_of.prescription }}
docs/chapters/sources.rst
+57
View File
@@ -0,0 +1,57 @@
Sources
=======
Document sources define places from which documents can be uploaded or gathered.
The current document sources supported are:
- Web - ``HTML`` forms with a ``Browse`` button that will open the file dialog
when clicked to allow selection of files in the user's computer to be
uploaded as documents.
- POP3 email - Provide the email, server and credential of a ``POP3`` based
email to be scanned periodically for email. The body of the email is uploaded
as a document and the attachments of the email are uploaded as separate
documents.
- IMAP email - Same as the ``POP3`` email source but for email accounts using
the ``IMAP`` protocol.
- Watch folder - A filesystem folder that is scanned periodically for files.
Any file in the watch folder is automatically uploaded.
- Staging folder - Folder where networked attached scanned can save image
files. The files in these staging folders are scanned and a preview is
generated to help the process of upload. Staging folders and Watch folders
work in a similar way with the main difference being that Staging folders are
interactive while Watch folders are automatic; documents in a Watch folder
are uploaded periodically and documents in a Staging folder remain indefinitely
there until an user uploads them. A preview for files in a Staging folder is
also provided. An example of Staging folder use is when multiple people
are scanning documents but only one person must be allowed to upload those
documents. This one person examines the scans quality and decides what to
upload and what to reject and have re-scanned. Watch folders can be used
when the quality of the scans is irrelevant or when they will be known
to be of good quality, such as when receiving e-faxes as PDFs.
.. blockdiag::
blockdiag {
mayan [shape = "roundedbox", label = "Mayan EDMS" ];
email_pop3 [shape = "mail", label = "e-mail (POP3)"];
email_imap [shape = "mail", label = "e-mail (IMAP)"];
staging [shape = "flowchart.database", label = "Staging folder" ];
watch [shape = "flowchart.database", label = "Watch folder" ];
automatic [shape = "box", label = "Automatic\n(via schedule)" ];
manual [shape = "actor", height=60, label = "Manual\n(user interaction)" ];
web [shape = "note", label = "Webform upload" ];
automatic -> mayan;
email_pop3 -> automatic;
email_imap -> automatic;
watch -> automatic;
manual -> mayan;
staging -> manual;
web -> manual;
}
Document source can be configure to allow document bundles to uploaded as
compressed files which are decompressed and their content uploaded as separate
documents. This feature is useful when migrating from another document
manager system.
docs/chapters/tags.rst
+8
View File
@@ -0,0 +1,8 @@
Tags
====
Tags allow giving documents a binary property. Documents can also be tagged
with more than one tag. Once tagged, documents can be searched also by their
tags and from the tags main menu a list of all the documents with a particular
tag can be obtained easily. Aside from their texts, tags can be assigned a
particular color.
docs/chapters/transformations.rst
+21
View File
@@ -0,0 +1,21 @@
***************
Transformations
***************
Transformations are persistent manipulations to the previews of the stored
documents. For example: a scanning equipment may only produce landscape PDFs.
In this case a useful transformation for that document source would be to rotate
all scanned documents by 270 degrees after being uploaded. By adding this
transformation to the Mayan EDMS source that is connected to the scanner, all
pages scanned via that source will inherit the transformation as they are
created. The result is that whenever a document is uploaded from that scanner,
it will appear in portrait orientation, instead of landscape orientation.
Transformations can also be added to existing documents by clicking on a
document's page and then clicking on "transformations". In this view the Actions
menu will have a new option that reads "Create new transformation". Currently,
the available transformations are: rotation, zoom, crop, and resize. Once the
document image has been corrected, resubmit it for OCR for improved results.
Transformations are not destructive and do not physically modify the document
file, they just modify the document's graphical representation.
docs/chapters/translations.rst
+17
View File
@@ -0,0 +1,17 @@
************
Translations
************
Translations are handled online via the **Transifex** website:
https://www.transifex.com/projects/p/mayan-edms/. To create a translation team
for a new language or contribute to an already existing language translation,
create a **Transifex** account and contact the team coordinator of the
respective language in which you are interested.
Feel free to open translation issues inside **Transifex** itself if you have a
question about the usage or meaning of a source text string. If you open a
translation issue, it will be your responsibility to close it after you get an
answers that satisfies your question. Administrator will not close new issues
as they have no way to determine if your question has been properly answered.
However to avoid clutter, answered questions will be scanned periodically and
closed if no activity is observed from the original poster in a period of time.
docs/chapters/upload_wizard.rst
+84
View File
@@ -0,0 +1,84 @@
*************
Upload wizard
*************
The steps needed to upgrade a document using form-tools' ``SessionWizard``
were hardcoded in the ``source`` app. This made it very difficult to add or remove
wizard steps.
The steps of the wizard are now defined by a new class called
``sources.wizard.WizardStep``. The existing steps to select a document type,
enter metadata and tag the document, have been converted to function as
``WizardSteps`` subclasses. The converted steps now live in
``sources.wizards.WizardStepDocumentType``, ``tag.wizard_steps.WizardStepTags``,
and ``metadata.wizard_steps.WizardStepMetadata``.
The steps need to define the following methods:
- ``done``: This method is execute when the wizard finished the last step
an enter the step where the actual file are uploaded. This steps is used
to encode form data into the URL query string that will be passed to the
document upload view for each file uploaded.
- ``condition``: This method is used to display the step conditionally.
If this method return True it will be displayed during the upload wizard
execution. To skip the step, return False or None.
- ``get_form_initial``: This method is used to return the initial data
for the step form. Use this method to set up initial values for the step's
form fields.
- ``step_post_upload_process``: This method will be executed once the
document finishes uploading. Use this method to process the information
encoded in the URL querystring by the step's `done`` method.
Once the ``WizardStep`` subclass is defined, it needs to be registered. This
is done by calling the ``.register`` method of the ``WizardStep`` class with
the subclass as the argument. Example::
WizardStep.register(WizardStepMetadata)
This statement must be located after the subclass definition. Finally,
the module defining the wizard step must be imported so that it is loaded
with the rest of the code and enabled. The best place to do this is in the
``.ready`` method of the apps' ``apps.py`` module. Example::
class TagsApp(MayanAppConfig):
has_rest_api = True
has_tests = True
name = 'tags'
verbose_name = _('Tags')
def ready(self):
super(TagsApp, self).ready()
from actstream import registry
from .wizard_steps import WizardStepTags # NOQA
The ``WizardStep`` class also allows for unregistering existing steps. This
is accomplished by calling the ``.deregister`` method of the ``WizardStep``
class and passing the subclass as the argument. This method should
also be called inside the ``.ready`` method of an apps' ``apps.py``
module. Example::
class TagsApp(MayanAppConfig):
has_rest_api = True
has_tests = True
name = 'tags'
verbose_name = _('Tags')
def ready(self):
super(TagsApp, self).ready()
from actstream import registry
from metadata.wizard_steps import WizardStepMetadata # NOQA
from sources.wizards import WizardStep # NOQA
from .wizard_steps import WizardStepTags # NOQA
WizardStep.deregister(WizardStepTags)
This will cause the tags assigment step to not be assigned to the upload
wizard anymore.
docs/chapters/versioning.rst
+48
View File
@@ -0,0 +1,48 @@
*******************
Document versioning
*******************
Mayan EDMS has the ability to store different versions of the same
document. A comment field is provided to allow users to summarize the new
version changes in comparison with the previous one. If a new version was
uploaded by mistake or such new version is no longer necessary the option to
revert to a previous version of the document is provided.
.. blockdiag::
blockdiag {
default_shape = roundedbox
orientation = portrait
node_width = 200;
version_1 [ label = "Version 1" ];
version_2 [ label = "Version 2" ];
document_1 [ label = "payroll_report.pdf" ];
document_2 [ label = "payroll_report_fixed.pdf" ];
upload_1 [ label = "payroll_report.pdf" ];
upload_2 [ label = "payroll_report_fixed.pdf" ];
upload_1 -> version_1 -> document_1;
upload_2 -> version_2 -> document_2;
document_1 -> document_2;
}
Only the interactive document sources (:doc:`sources`) (``Web`` and ``Staging folders``) are
available to upload new document versions.
There is no limit to the number of versions a document can have.
.. blockdiag::
blockdiag {
default_shape = roundedbox
orientation = portrait
node_width = 200;
document [ label = "payroll_report.pdf" ];
versions [ label = "Versions", stacked ];
document -> versions;
}
By default, the last version will be showed when working with the document
but any of the versions can be inspected and viewed.