Documentation: Use Sphinx's extlinks to cut down on repeated URLs. Merge Administration and Maintenance topics. Add database conversion chapter. Unify the header format of all recent release notes. Fix :doc: references.
Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>
This commit is contained in:
Roberto Rosario
@@ -2,11 +2,11 @@
|
||||
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.
|
||||
Besides the permissions system explained in :doc:`../chapters/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::
|
||||
|
||||
@@ -40,9 +40,10 @@ 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.
|
||||
It is also possible to grant a permission to a role for a specific document
|
||||
type (:doc:`../chapters/document_types`). Under this scheme all users in
|
||||
groups belonging to that role will inherit that permission for all documents
|
||||
of that type.
|
||||
|
||||
.. blockdiag::
|
||||
|
||||
|
||||
103
docs/chapters/database_conversion.rst
Normal file
103
docs/chapters/database_conversion.rst
Normal file
@@ -0,0 +1,103 @@
|
||||
*******************
|
||||
Database conversion
|
||||
*******************
|
||||
|
||||
Version 3.1.x added a new management command to help convert data residing in
|
||||
an SQLite database to other database managers like PostgreSQL. Here is the
|
||||
conversion procedure.
|
||||
|
||||
Direct install
|
||||
==============
|
||||
|
||||
* Make a backup of your existing SQLite database and documents by copying the
|
||||
``/opt/mayan-edms/media`` folder.
|
||||
* :doc:`Upgrade to at least version 3.1.3. <../releases/3.1.3>`
|
||||
* Migrate the existing SQLite database with the command ``performupgrade``::
|
||||
|
||||
sudo -u mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media /opt/mayan-edms/bin/mayan-edms.py performupgrade
|
||||
|
||||
* Install PostgreSQL::
|
||||
|
||||
sudo apt-get install postgresql libpq-dev
|
||||
|
||||
* Provision a PostgreSQL database::
|
||||
|
||||
sudo -u postgres psql -c "CREATE USER mayan WITH password 'mayanuserpass';"
|
||||
sudo -u postgres createdb -O mayan mayan
|
||||
|
||||
* Install the Python client for PostgreSQL::
|
||||
|
||||
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir psycopg2==2.7.3.2
|
||||
|
||||
* Copy the newly created fallback config file::
|
||||
|
||||
cp /opt/mayan-edms/media/config_backup.yml /opt/mayan-edms/media/config.yml
|
||||
|
||||
* Edit the configuration file to add the entry for the PostgreSQL database and
|
||||
rename the SQLite database to 'old'::
|
||||
|
||||
# Before
|
||||
DATABASES:
|
||||
default:
|
||||
ATOMIC_REQUESTS: false
|
||||
AUTOCOMMIT: true
|
||||
CONN_MAX_AGE: 0
|
||||
ENGINE: django.db.backends.sqlite3
|
||||
HOST: ''
|
||||
NAME: /opt/mayan-edms/media/db.sqlite3
|
||||
OPTIONS: {}
|
||||
PASSWORD: ''
|
||||
PORT: ''
|
||||
TEST: {CHARSET: null, COLLATION: null, MIRROR: null, NAME: null}
|
||||
TIME_ZONE: null
|
||||
USER: ''
|
||||
|
||||
# After
|
||||
DATABASES:
|
||||
old:
|
||||
ATOMIC_REQUESTS: false
|
||||
AUTOCOMMIT: true
|
||||
CONN_MAX_AGE: 0
|
||||
ENGINE: django.db.backends.sqlite3
|
||||
HOST: ''
|
||||
NAME: /opt/mayan-edms/media/db.sqlite3
|
||||
OPTIONS: {}
|
||||
PASSWORD: ''
|
||||
PORT: ''
|
||||
TEST: {CHARSET: null, COLLATION: null, MIRROR: null, NAME: null}
|
||||
TIME_ZONE: null
|
||||
USER: ''
|
||||
default:
|
||||
ATOMIC_REQUESTS: false
|
||||
AUTOCOMMIT: true
|
||||
CONN_MAX_AGE: 0
|
||||
ENGINE: django.db.backends.postgresql
|
||||
HOST: '127.0.0.1'
|
||||
NAME: /opt/mayan-edms/media/db.sqlite3
|
||||
OPTIONS: {}
|
||||
PASSWORD: 'mayanuserpass'
|
||||
PORT: ''
|
||||
TEST: {CHARSET: null, COLLATION: null, MIRROR: null, NAME: null}
|
||||
TIME_ZONE: null
|
||||
USER: 'mayan'
|
||||
|
||||
* Migrate the new database to create the empty tables::
|
||||
|
||||
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 migrate
|
||||
|
||||
* Convert the data in the SQLite and store it in the PostgreSQL database::
|
||||
|
||||
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 convertdb --from=old --to=default --force
|
||||
|
||||
* Update the supervisor config file to have Mayan EDMS run from the PostgreSQL database::
|
||||
|
||||
[supervisord]
|
||||
environment=
|
||||
<...>
|
||||
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,
|
||||
<...>
|
||||
@@ -1,5 +1,3 @@
|
||||
.. _deploying:
|
||||
|
||||
******************
|
||||
Direct deployments
|
||||
******************
|
||||
@@ -172,6 +170,9 @@ Enable and restart the services [1_]:
|
||||
systemctl enable supervisor
|
||||
systemctl restart supervisor
|
||||
|
||||
|
||||
.. _deployment_advanced:
|
||||
|
||||
Advanced deployment
|
||||
===================
|
||||
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
.. _development:
|
||||
|
||||
***********
|
||||
Development
|
||||
***********
|
||||
@@ -270,7 +268,9 @@ Follow the latest contributing guidelines outlined here: https://gitlab.com/maya
|
||||
Debugging
|
||||
=========
|
||||
|
||||
Mayan EDMS makes extensive use of Django's new `logging capabilities`_.
|
||||
Mayan EDMS makes extensive use of Django's new
|
||||
:django-docs:`logging capabilities <topics/logging>`.
|
||||
|
||||
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
|
||||
@@ -322,9 +322,6 @@ Likewise, to see the debug output of the ``tags`` app, just add the following in
|
||||
},
|
||||
|
||||
|
||||
.. _`logging capabilities`: https://docs.djangoproject.com/en/dev/topics/logging
|
||||
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
.. _docker:
|
||||
|
||||
|
||||
============
|
||||
Docker image
|
||||
============
|
||||
@@ -8,8 +5,10 @@ Docker image
|
||||
How to use this image
|
||||
=====================
|
||||
|
||||
Start a Mayan EDMS instance
|
||||
------------------------------
|
||||
.. _docker_install:
|
||||
|
||||
Start a Mayan EDMS image
|
||||
------------------------
|
||||
|
||||
With Docker properly installed, proceed to download the Mayan EDMS image using the command::
|
||||
|
||||
@@ -113,7 +112,7 @@ instead of the IP address of the Docker host (``172.17.0.1``)::
|
||||
mayanedms/mayanedms:<version>
|
||||
|
||||
Stopping and starting the container
|
||||
--------------------------------------
|
||||
-----------------------------------
|
||||
|
||||
To stop the container use::
|
||||
|
||||
@@ -125,6 +124,8 @@ To start the container again::
|
||||
docker start mayan-edms
|
||||
|
||||
|
||||
.. _docker_environment_variables:
|
||||
|
||||
Environment Variables
|
||||
---------------------
|
||||
|
||||
@@ -148,43 +149,38 @@ or testing, never use it in production.
|
||||
|
||||
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
|
||||
the pertinent Django documentation page:
|
||||
:django-docs:`Connecting to the database <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
|
||||
read the pertinent Django documentation page:
|
||||
:django-docs:`Settings, USER <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
|
||||
read the pertinent Django documentation page:
|
||||
:django-docs:`Settings, PASSWORD <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
|
||||
the pertinent Django documentation page:
|
||||
:django-docs:`Settings, HOST <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
|
||||
pertinent Django documentation page:
|
||||
:django-docs:`Settings, PORT <ref/settings/#port>`
|
||||
|
||||
``MAYAN_BROKER_URL``
|
||||
|
||||
@@ -223,9 +219,7 @@ Optional. Allows loading an alternate settings file.
|
||||
|
||||
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
|
||||
page: :django-docs:`Settings, CONN_MAX_AGE <ref/settings/#conn-max-age>`
|
||||
|
||||
``MAYAN_GUNICORN_WORKERS``
|
||||
|
||||
|
||||
@@ -1,9 +1,7 @@
|
||||
.. _document_types:
|
||||
|
||||
Document types
|
||||
==============
|
||||
|
||||
The basic unit of data in Mayan EDMS is the ``document type``. A document
|
||||
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
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
.. _indexes:
|
||||
|
||||
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`.
|
||||
relation to their properties (:doc:`../chapters/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:`../chapters/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
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
.. _mailing:
|
||||
|
||||
*****************
|
||||
Mailing documents
|
||||
*****************
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
.. _metadata:
|
||||
|
||||
********
|
||||
Metadata
|
||||
********
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
.. _object_storage:
|
||||
|
||||
**************
|
||||
Object storage
|
||||
**************
|
||||
|
||||
@@ -5,7 +5,7 @@ Password reset
|
||||
To use the password reset feature, administrative emails need to be configured.
|
||||
These are sent by the system itself and not by the users. Their usage and
|
||||
configuration is different than the
|
||||
:ref:`email system used to share documents via email<mailing>`.
|
||||
:doc:`email system used to share documents via email<../chapters/mailing>`.
|
||||
|
||||
Sending administrative emails
|
||||
=============================
|
||||
@@ -24,9 +24,6 @@ Example::
|
||||
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
|
||||
|
||||
To change the reference URL in the password reset emails on in the
|
||||
default document mailing template modify the ``COMMON_PROJECT_URL`` setting.
|
||||
For information on the different ways to change a setting check the
|
||||
|
||||
@@ -1,6 +1,3 @@
|
||||
.. _scaling_up:
|
||||
|
||||
|
||||
**********
|
||||
Scaling up
|
||||
**********
|
||||
@@ -22,9 +19,9 @@ 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.
|
||||
``MAYAN_GUNICORN_WORKERS`` environment variable (check the Docker image chapter:
|
||||
:ref:`docker_environment_variables`). 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::
|
||||
|
||||
@@ -111,9 +108,8 @@ 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 direct installs refer to the :ref:`deployment_advanced` documentation
|
||||
section for the required changes.
|
||||
|
||||
For the Docker image, launch a separate RabbitMQ container
|
||||
(https://hub.docker.com/_/rabbitmq/)::
|
||||
@@ -151,7 +147,7 @@ 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.
|
||||
:doc:`object storage <../chapters/object_storage>` system.
|
||||
|
||||
Use additional hosts
|
||||
====================
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
Settings
|
||||
********
|
||||
|
||||
|
||||
Mayan EDMS can be configure via environment variables or by setting files.
|
||||
|
||||
|
||||
.. _environment_variables:
|
||||
|
||||
Via environment variables
|
||||
@@ -23,6 +23,7 @@ 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
|
||||
@@ -53,20 +54,21 @@ 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
|
||||
according to the :doc:`../chapters/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:
|
||||
according to the :doc:`../chapters/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
|
||||
@@ -94,7 +96,7 @@ 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
|
||||
For the :doc:`../chapters/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::
|
||||
|
||||
@@ -104,7 +106,7 @@ 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
|
||||
For the :doc:`../chapters/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::
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ 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`.
|
||||
document, but they each belong to their own :doc:`../chapters/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
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
.. _sources:
|
||||
|
||||
Sources
|
||||
=======
|
||||
|
||||
|
||||
@@ -26,8 +26,8 @@ revert to a previous version of the document is provided.
|
||||
document_1 -> document_2;
|
||||
}
|
||||
|
||||
Only the interactive document sources (:doc:`sources`) (``Web`` and ``Staging folders``) are
|
||||
available to upload new document versions.
|
||||
Only the interactive document sources (:doc:`../chapters/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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user