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

Document update. Add new deployment chapter.

Browse Source
This commit is contained in:
Roberto Rosario
2015-09-11 09:47:56 -04:00
parent d474efe8b3
commit ca6f6c3402
9 changed files with 224 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/conf.py
View File

@@ -240,9 +240,9 @@ html_theme_options = {
'description': mayan.__description__,
'github_user': 'mayan-edms',
'github_repo': 'mayan-edms',
'travis_button': True,
'travis_button': False,
'gratipay_user': 'rosarior',
'github_banner': True,
'github_banner': False,
}
html_logo = '_static/logo_pyramid_only.png'

1
docs/index.rst
View File

@@ -25,6 +25,7 @@ account.
Features <topics/features>
Installation <topics/installation>
Deploying <topics/deploying>
Getting started <topics/getting_started>
Release notes and upgrading <releases/index>
Concepts <topics/index>

24
docs/releases/0.12.1.rst
View File

@@ -13,7 +13,7 @@ While bug fixes and minor feature were the focus for this release, some
bigger changes were included because of their importance. The parsing of
documents saw a complete rewrite being now class based and allows for more
than one parser per mimetype with sequencial fallback. This provides the
best text extraction on deployments where users have control over the
best text extraction on deployments where users have control over the
installation and basic extraction when deploying on the cloud or other
environments where users don't have the ability to install OS level
binaries.
@@ -24,7 +24,7 @@ What's new in Mayan EDMS v0.12.1
Fabric file (fabfile)
~~~~~~~~~~~~~~~~~~~~~
A Fabric file is included to help users not very familiar with Ubuntu,
A Fabric file is included to help users not very familiar with Ubuntu,
Python and Django install **Mayan EDMS**, or for system administrators
looking to automate the install whether in local or remote systems.
At the moment the fabfile will install **Mayan EDMS** in the same configurations
@@ -36,10 +36,10 @@ the fabfile as more are tested.
Documentation update
~~~~~~~~~~~~~~~~~~~~
The installation instructions were updated to include the installation of
the libpng-dev and libjpeg-dev libraries as well as the installation of
the libpng-dev and libjpeg-dev libraries as well as the installation of
the poppler-utils package. An additional step to help users test their
new installation of **Mayan EDMS** was also added.
Translations
~~~~~~~~~~~~
The Italian translation has been synchronized with the source files at
@@ -50,30 +50,30 @@ Usability improvements
The index instance view now feature the same multi document action
buttons (Submit to OCR, delete, download, etc) as the mail and recent
document views.
Better office document conversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A new method of converting office documents has been implemented, this
new method doesn't require the use of the command line utility ``UNOCONV``.
If this new method proves to work better than previous solutions the use
of ``UNOCONV`` may be deprecated in the future. The conversion method
adds just one new configuration option: :setting:`CONVERTER_LIBREOFFICE_PATH`
adds just one new configuration option: `CONVERTER_LIBREOFFICE_PATH`
which defaults to '/usr/bin/libreoffice'.
Better PDF text parsing
~~~~~~~~~~~~~~~~~~~~~~~
Brian E. submitted a patch to use the Poppler package pdftotext utility to
extract text from PDF files. This is now the default method Mayan EDMS
will execute to try to extract text from a PDF and failing that will
will execute to try to extract text from a PDF and failing that will
fallback to the previous method. This change add a new configuration
option: :setting:`OCR_PDFTOTEXT_PATH` to specify the location of the ``pdftotext``
option: `OCR_PDFTOTEXT_PATH` to specify the location of the ``pdftotext``
executable, it defaults to '/usr/bin/pdftotext'. Be sure to install the
``poppler-utils`` os package to take advantage of this new parser.
Changed defaults
~~~~~~~~~~~~~~~~
The OCR queue is now active by default when first created during the
``syncdb`` phase and the :setting:`OCR_AUTOMATIC_OCR` option now defaults
The OCR queue is now active by default when first created during the
``syncdb`` phase and the `OCR_AUTOMATIC_OCR` option now defaults
to ``True``. These two changes are made to reduce the steps required for
new users to start enjoying the benefits of automatic text extraction from
uploaded documents without having to read the documentation and have a more
@@ -95,7 +95,7 @@ Install the ``poppler-utils`` package:
* Ubuntu, Debian::
$ apt-get install -y poppler-utils
* Fedora::
$ yum install -y poppler-utils
@@ -112,5 +112,5 @@ Bugs fixed
* Issue #25 "Office document conversion error"
Stuff removed
=============
=============
* None

8
docs/releases/0.12.2.rst
View File

@@ -27,10 +27,10 @@ Smarter auto admin creation
**Mayan EDMS** creates a administrator user during the
database creation phase to reduce the amount of steps required for a
functional install. The creation of this account is controlled by the configuration
option :setting:`COMMON_AUTO_CREATE_ADMIN`, the username of the account is
specified with the configuration option :setting:`COMMON_AUTO_ADMIN_USERNAME`
and the password of this account by the option :setting:`COMMON_AUTO_ADMIN_PASSWORD`.
Previously the :setting:`COMMON_AUTO_ADMIN_PASSWORD` defaulted to 'admin' which
option `COMMON_AUTO_CREATE_ADMIN`, the username of the account is
specified with the configuration option `COMMON_AUTO_ADMIN_USERNAME`
and the password of this account by the option `COMMON_AUTO_ADMIN_PASSWORD`.
Previously the `COMMON_AUTO_ADMIN_PASSWORD` defaulted to 'admin' which
created an administrator account of username 'admin' with a password of
'admin'. The new default is to randomize an initial password and show this password
at the login screen until the administrator password is changed.

10
docs/releases/0.12.rst
View File

@@ -60,7 +60,7 @@ ACL support
Anonymous user support
~~~~~~~~~~~~~~~~~~~~~~
Anonymous user support is a two tier function, first is the addition of
the :setting:`COMMON_ALLOW_ANONYMOUS_ACCESS` configuration option that
the `COMMON_ALLOW_ANONYMOUS_ACCESS` configuration option that
allows non authenticated user to browse all the pages of a **Mayan EDMS** installation.
The second part of this support is the ability to assign permissions
or individual access to objects to anonymous users.
@@ -88,7 +88,7 @@ the download of several documents in a single compressed file.
Customizable GPG home directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Addition of the :setting:`SIGNATURES_GPG_HOME` configuration option to let
Addition of the `SIGNATURES_GPG_HOME` configuration option to let
administrators set **Mayan EDMS**'s GPG instance home directory, used to
store keyrings and other GPG configuration files.
@@ -116,7 +116,7 @@ These populated trees can also be mirrored on the physical filesystem and shared
using Samba or another filesharing server giving users a structured view
of the documents contained within **Mayan EDMS** from the ``Indexes`` tab
or from a mirrored index shared via the network. A new configuration option
has been added, :setting:`DOCUMENT_INDEXING_FILESYSTEM_SERVING`, which maps
has been added, `DOCUMENT_INDEXING_FILESYSTEM_SERVING`, which maps
the index internal name with the physical directory where such index will be
mirrored on disk.
@@ -226,6 +226,6 @@ Stuff removed
* Configuration options removed:
* OCR_CACHE_URI
* DOCUMENT_INDEXING_FILESYSTEM_FILESERVING_PATH - Use the newest :setting:`DOCUMENT_INDEXING_FILESYSTEM_SERVING`
* DOCUMENT_INDEXING_FILESYSTEM_FILESERVING_ENABLE - Use the newest :setting:`DOCUMENT_INDEXING_FILESYSTEM_SERVING`
* DOCUMENT_INDEXING_FILESYSTEM_FILESERVING_PATH - Use the newest `DOCUMENT_INDEXING_FILESYSTEM_SERVING`
* DOCUMENT_INDEXING_FILESYSTEM_FILESERVING_ENABLE - Use the newest `DOCUMENT_INDEXING_FILESYSTEM_SERVING`

251
docs/releases/2.0.rst
View File

@@ -12,179 +12,216 @@ What's new in Mayan EDMS v2.0
Update to Django 1.7
--------------------
The biggest change of this release comes in the form of support for Django 1.7. **Mayan EDMS** makes use of several new features
of Django 1.7 like: migrations, app config and transaction handling. The version of Django supported in this version is 1.7.10.
With the move to Django 1.7, support for South migrations and Python 2.6 is removed. The switch to Django 1.7's app config
means that the startup order of app should not longer have any relevance, cause any import or startup
problems.
The biggest change of this release comes in the form of support for Django 1.7.
**Mayan EDMS** makes use of several new features of Django 1.7 like: migrations,
app config and transaction handling. The version of Django supported in this
version is 1.7.10. With the move to Django 1.7, support for South migrations
and Python 2.6 is removed. The switch to Django 1.7's app config means that
the startup order of app should not longer have any relevance, cause any import
or startup problems.
Frontend UI
-----------
The frontend UI HTML has been refactored to use Bootstrap. Along with this update a lot of legacy HTML and CSS was removed, greatly
simplifying the existing template and allowing the removal of some.
The frontend UI HTML has been refactored to use Bootstrap. Along with this
update a lot of legacy HTML and CSS was removed, greatly simplifying the
existing template and allowing the removal of some.
Theming and rebranding
----------------------
All the presentation logic and markup has been moved into it's own app, the 'appearance' app.
All modifications required to customize the entire look of the **Mayan EDMS** can now be done in a single app. Very little markup
remains in the other apps, and it's usually because of necesity, namely the widgets.py modules.
All the presentation logic and markup has been moved into it's own app, the
'appearance' app. All modifications required to customize the entire look of
the **Mayan EDMS** can now be done in a single app. Very little markup remains
in the other apps, and it's usually because of necesity, namely the widgets.py
modules.
Improved page navigation interface
----------------------------------
Previously the document page interface used a fancybox windows leaving the current document in the background.
This UI workflow as been improved and the document page navigation behaves like the rest of the document
views.
Previously the document page interface used a fancybox windows leaving the
current document in the background. This UI workflow as been improved and the
document page navigation behaves like the rest of the document views.
Menu reorganization
-------------------
To improve user experience, the main menu has been restructured based on function usage, moving seldom used buttons inside
other views.
To improve user experience, the main menu has been restructured based on
function usage, moving seldom used buttons inside other views.
Removal of famfam icon set
--------------------------
The previously used icon set and icon display code was removed and a new system that favor font icon was added.
The previously used icon set and icon display code was removed and a new
system that favor font icon was added.
Document preview generation
---------------------------
The image conversion system was refactored from the ground up and uses a much smarted caching system. The document
image cache has it's own Django file storage driver and no longer default to the system /tmp directory.
By moving the document image cache to a Django file storage, the cache doesn't need to reside
in the same filesystem or even computer serving the document images. This change also allows nodes in a
clutered install to share the document image cache.
The image conversion system was refactored from the ground up and uses a much
smarted caching system. The document image cache has it's own Django file
storage driver and no longer default to the system /tmp directory. By moving
the document image cache to a Django file storage, the cache doesn't need to
reside in the same filesystem or even computer serving the document images.
This change also allows nodes in a clustered install to share the document
image cache.
Document submission for OCR changed to POST
-------------------------------------------
Previously submitting a document for OCR could be done with a GET request to the corresponding URL.
This design decision allowed for fast user experience but caused massive document submissions
when sites were scanned by web spiders. The new workflow is to submit documents to the
OCR queue only on POST request.
Previously submitting a document for OCR could be done with a GET request to
the corresponding URL. This design decision allowed for fast user experience
but caused massive document submissions when sites were scanned by web spiders.
The new workflow is to submit documents to the OCR queue only on POST request.
New YAML based settings system
------------------------------
The first phase of the new distributed settings system has landed in this version.
This first change causes settings to be serialized to YAML. This also means that it is
not possible to pass functions or custom classes as values to settings.
Setting that related to a class or function, now specify the path to those classes or
functions and they are imported dynamically at runtime.
Example: DOCUMENTS_STORAGE_BACKEND = 'storage.backends.filebasedstorage.FileBasedStorage'
The first phase of the new distributed settings system has landed in this
version. This first change causes settings to be serialized to YAML. This also
means that it is not possible to pass functions or custom classes as values to
settings. Setting that related to a class or function, now specify the path to
those classes or functions and they are imported dynamically at runtime.
Example::
DOCUMENTS_STORAGE_BACKEND = 'storage.backends.filebasedstorage.FileBasedStorage'
Removal of auto admin creation
------------------------------
The auto admin user creation code used during new installs has been removed and it
is its own reusable Django app. The app is available at https://pypi.python.org/pypi/django-autoadmin
The auto admin user creation code used during new installs has been removed and
it is its own reusable Django app. The app is available at
https://pypi.python.org/pypi/django-autoadmin
Removal of dependencies
-----------------------
Through optimizations and code reduction several Python libraries and Django app are no longer
required. These are: South, GitPython, django-pagination, psutil, python-hkp, sendfile and slate.
Through optimizations and code reduction several Python libraries and Django
app are no longer required. These are:
* South
* GitPython
* django-pagination
* psutil
* python-hkp
* sendfile
* slate
ACL system refactor
-------------------
The Access Control System has been greatly simplified and optimized. The logistics to grant and revoke permissions
are now as follows: Only Roles can hold permissions, groups and user can no longer on their own be granted a permission.
Groups are now only organizational units that hold users and Roles are collections of groups. User are just a
profile and authentication information object. So to grant a permission or access to a document to a user, grant
those permissions to a new or existing role, add the desired user to a group and add that group to the role to
which you granted the permission. When thinking about granting permissions think of it this way:
Permissions -> Roles -> Groups -> User
Permissions for a document -> Roles -> Groups -> User
Permissions for a type of document -> Roles -> Groups -> User
The Access Control System has been greatly simplified and optimized. The
logistics to grant and revoke permissions are now as follows: Only Roles can
hold permissions, groups and user can no longer on their own be granted a
permission. Groups are now only organizational units that hold users and Roles
are collections of groups. User are just a profile and authentication
information object. So to grant a permission or access to a document to a user,
grant those permissions to a new or existing role, add the desired user to a
group and add that group to the role to which you granted the permission. When
thinking about granting permissions think of it this way:
**Permissions -> Roles -> Groups -> User**
**Permissions for a document -> Roles -> Groups -> User**
**Permissions for a type of document -> Roles -> Groups -> User**
Object access control inheritance
---------------------------------
A frequently asked feature is the ability to change the access control of a group of documents. This
feature has been implemented in the form of object access control inheritance. This means that
if you grant a permission to a role for a document type, that role will inherit that permission
for all document that are later created of that type. If you revoke a permission from a role
for a document type, that role loses that permission for all documents of that type. With this new
system changing the access control of individual documents should be an edge case. This new ability of
modifying the access control of document types is the new recommended method.
A frequently asked feature is the ability to change the access control of a
group of documents. This feature has been implemented in the form of object
access control inheritance. This means that if you grant a permission to a role
for a document type, that role will inherit that permission for all document
that are later created of that type. If you revoke a permission from a role for
a document type, that role loses that permission for all documents of that type.
With this new system changing the access control of individual documents
should be an edge case. This new ability of modifying the access control of
document types is the new recommended method.
Removal of anonymous user support
---------------------------------
Allowing anonymous users access to your document repository is no longer support. Admininstrator
wanting to make a group of documents public are encouraged to create an user, group and role for
that purpose.
Allowing anonymous users access to your document repository is no longer
support. Admininstrator wanting to make a group of documents public are
encouraged to create an user, group and role for that purpose.
Metadata validators refactor
----------------------------
The metadata validator have been splitted into: Validators and Parsers. Validators will just
check that the input value conforms to certain specification, raising a validation error is not
and blocking the user from submitting data. The Parsers will transform user input and store the
result as the metadata value.
The metadata validator have been splitted into: Validators and Parsers.
Validators will just check that the input value conforms to certain
specification, raising a validation error is not and blocking the user from
submitting data. The Parsers will transform user input and store the result as
the metadata value.
Trash can support
-----------------
To avoid accidental data loss, documents are not deleted but moved to a virtual trash can. From
that trash can documents can them be deleted permanently. The deletion document documents and
the moving of documents to the trash can are governed by two different permissions.
To avoid accidental data loss, documents are not deleted but moved to a virtual
trash can. From that trash can documents can them be deleted permanently. The
deletion document documents and the moving of documents to the trash can are
governed by two different permissions.
Retention policies
------------------
Support for retention policies was added and is control on a document type basis.
Two aspects can be controlled: the time at which documents will be automatically moved to the
trash can and the time after which documents in the trash can will be automatically
deleted. By default all new document types created will have a retention policy that doesn't
move documents to the trash can and that permanently deletes documents in the trash can after
30 days.
Two aspects can be controlled: the time at which documents will be
automatically moved to the trash can and the time after which documents in the
trash can will be automatically deleted. By default all new document types
created will have a retention policy that doesn't move documents to the trash
can and that permanently deletes documents in the trash can after 30 days.
Support to share an index as a FUSE filesystem
----------------------------------------------
Index mirror has been added after being removed several version ago. This time mirroring works
by creating a FUSE filesystem that is then mounted anywhere in the filesystem. The
previous implementation used symbolic links that while fast, required constant modification
to keep in sync with the indexes structure and only worked when the document storage and
the index mirror resided in the same physical computer or node. This new implementation
allowing mirroring of indexes even across a network or if the document storage is not a
traditional filesystem but a remote object store. Since this new FUSE mirroring uses
direct read access to the database caching is provided and is controlled by the
MIRRORING_DOCUMENT_CACHE_LOOKUP_TIMEOUT and MIRRORING_NODE_CACHE_LOOKUP_TIMEOUT setting
options. Both setting have a default of 10 seconds.
Index mirror has been added after being removed several version ago. This time
mirroring works by creating a FUSE filesystem that is then mounted anywhere in
the filesystem. The previous implementation used symbolic links that while
fast, required constant modification to keep in sync with the indexes structure
and only worked when the document storage and the index mirror resided in the
same physical computer or node. This new implementation allowing mirroring of
indexes even across a network or if the document storage is not a traditional
filesystem but a remote object store. Since this new FUSE mirroring uses direct
read access to the database caching is provided and is controlled by the
**MIRRORING_DOCUMENT_CACHE_LOOKUP_TIMEOUT** and **MIRRORING_NODE_CACHE_LOOKUP_TIMEOUT**
setting options. Both setting have a default of 10 seconds.
Clickable preview images titles
-------------------------------
To shorten the amount of click required to access a document, document preview image titles
are clickable and will take the user straight to the document view.
To shorten the amount of click required to access a document, document preview
image titles are clickable and will take the user straight to the document view.
Removal of eval
---------------
Use of Python's eval statement has been completely removed. Metadata type defaults, lookup fields,
smart links and indexes templates now use Django's own template language.
Use of Python's eval statement has been completely removed. Metadata type
defaults, lookup fields, smart links and indexes templates now use Django's
own template language.
Smarter OCR
-----------
Document OCR workflow has been improved to try to parse text for each document page and in
failing to parse text will only perform OCR on that specific page, returning to the parsing
behavior for the next page. This allowing proper text extraction of documents containing both,
embedded text and images.
Document OCR workflow has been improved to try to parse text for each document
page and in failing to parse text will only perform OCR on that specific page,
returning to the parsing behavior for the next page. This allowing proper text
extraction of documents containing both, embedded text and images.
Failure tolerance
-----------------
Previous versions made use of transactions to prevent data loss in the event of an unexpected
error. This release improves on that approach by also reacting to infrastructure failures.
**Mayan EDMS** can now recover without any or minimal data loss from critical events such as loss
of connectivity to the database manager. This changes allow installation of using database managers
that do not provide guaranteed concurrency such as SQLite, to scale to thousand of documents.
While this configuration is still not recommended, **Mayan EDMS** will now work and scale much better
in environments where parts of the infrastructure cannot be changed (such as the database manager).
Previous versions made use of transactions to prevent data loss in the event of
an unexpected error. This release improves on that approach by also reacting
to infrastructure failures. **Mayan EDMS** can now recover without any or
minimal data loss from critical events such as loss of connectivity to the
database manager. This changes allow installation of using database managers
that do not provide guaranteed concurrency such as SQLite, to scale to thousand
of documents. While this configuration is still not recommended, **Mayan EDMS**
will now work and scale much better in environments where parts of the
infrastructure cannot be changed (such as the database manager).
For more information about this change read the blog post: http://blog.robertorosario.com/testing-django-project-infrastructure-failure-tolerance/
For more information about this change read the blog post:
http://blog.robertorosario.com/testing-django-project-infrastructure-failure-tolerance/
As a result of this work a new Django app called Django-sabot was created that gives Django projects the
ability to create unit tests for infrastructure failure tolerance: https://pypi.python.org/pypi/django-sabot
As a result of this work a new Django app called Django-sabot was created that
gives Django projects the ability to create unit tests for infrastructure
failure tolerance: https://pypi.python.org/pypi/django-sabot
RGB tags
--------
Previously tags could only choose from a predertermined number of color. This release changes
that and tags be of any color. Tags now store the color selected in HTML RGB format. Existing tags
are automatically converted to this new scheme.
Previously tags could only choose from a predertermined number of color. This
release changes that and tags be of any color. Tags now store the color
selected in HTML RGB format. Existing tags are automatically converted to this
new scheme.
Default document type and default document source
-------------------------------------------------
After installation a default document type and document source are created, this means
that users can start uploading documents as soon as **Mayan EDMS** is installed without
having to do any configuration setting changes. The default document type and default document
source are both called 'Default'.
After installation a default document type and document source are created,
this means that users can start uploading documents as soon as **Mayan EDMS**
is installed without having to do any configuration setting changes. The
default document type and default document source are both called 'Default'.
Other changes
-------------
@@ -232,7 +269,7 @@ Other changes
* Reduction of text strings.
Upgrading from a previous version
=================================
---------------------------------
Using PIP
~~~~~~~~~
@@ -251,7 +288,8 @@ If you installed Mayan EDMS by cloning the Git repository issue the commands::
$ git reset --hard HEAD
$ git pull
otherwise download the compressed archived and uncompress it overriding the existing installation.
otherwise download the compressed archived and uncompress it overriding the
existing installation.
Next upgrade/add the new requirements::
@@ -293,6 +331,7 @@ Remove unused dependencies::
$ pip uninstall python-hkp
$ pip uninstall django-sendfile
$ pip uninstall django-pagination
$ pip uninstall slate
The upgrade procedure is now complete.
@@ -300,13 +339,14 @@ The upgrade procedure is now complete.
Backward incompatible changes
=============================
* Document and sources transformations
* Current document and document sources transformations will be lost during upgrade.
* Permissions and Access Controls granted to users and/or groups will be lost during upgrade.
Bugs fixed or issues closed
===========================
* `issue #33 <https://github.com/mayan-edms/mayan-edms/issues/33>`_ Update to Django 1.7
* `issue #59 <https://github.com/mayan-edms/mayan-edms/issues/59`_ New bootstrap based UI
* `issue #59 <https://github.com/mayan-edms/mayan-edms/issues/59>`_ New bootstrap based UI
* `issue #60 <https://github.com/mayan-edms/mayan-edms/issues/60>`_ Backport class based navigation code from the unstable branch
* `issue #62 <https://github.com/mayan-edms/mayan-edms/issues/62>`_ Simplify and reduce code in templates
* `issue #67 <https://github.com/mayan-edms/mayan-edms/issues/67>`_ Python 3 compatibility: Update models __unicode__ methdo to __str__ methods (using Django's six library)
@@ -317,4 +357,3 @@ Bugs fixed or issues closed
.. _PyPI: https://pypi.python.org/pypi/mayan-edms/

28
docs/topics/deploying.rst Normal file
View File

@@ -0,0 +1,28 @@
=========
Deploying
=========
Like other Django based projects **Mayan EDMS** can be deployed in a wide variety
of ways. The method provided below is only provided as a bare minimum example.
These instructions asume you installed **Mayan EDMS** as mentioned in the
Installation chapter.
Install the system dependencies:
sudo apt-get install nginx supervisor redis-server
Switch and activate the `virtualenv` where you installed **Mayan EDMS**. Install
the Python client for redis:
pip install redis
Install the Python application server gunicorn:
pip install gunicorn
Update the settings/local.py file:
BROKER_URL = 'redis://127.0.0.1:6379/0'
CELERY_ALWAYS_EAGER = False
CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/0'

33
docs/topics/development.rst
View File

@@ -6,11 +6,11 @@ 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 `GitHub issue tracker`_. To submit patches, please send a pull
request on GitHub_. Make sure to add yourself to the :ref:`contributors` file.
issue on the `GitLab issue tracker`_. To submit patches, please send a pull
request on GitLab_. Make sure to add yourself to the :ref:`contributors` file.
.. _GitHub: https://github.com/mayan-edms/mayan-edms/
.. _`GitHub issue tracker`: https://github.com/mayan-edms/mayan-edms/issues
.. _GitLab: https://gitlab.com/mayan-edms/mayan-edms/
.. _`GitLab issue tracker`: https://gitlab.com/mayan-edms/mayan-edms/issues
Project philosophies
@@ -286,9 +286,9 @@ Source Control
**Mayan EDMS** source is controlled with Git_.
The project is publicly accessible, hosted and can be cloned from **GitHub** using::
The project is publicly accessible, hosted and can be cloned from **GitLab** using::
$ git clone git://github.com/mayan-edms/mayan-edms.git
$ git clone git://gitlab.com/mayan-edms/mayan-edms.git
Git branch structure
@@ -306,21 +306,20 @@ Git branch structure
Released versions.
Each release is tagged and available for download on the Downloads_ section of the **Mayan EDMS** repository on GitHub_.
Each release is tagged separately.
When submitting patches, please place your code in its own ``feature/`` branch prior to opening a pull request on GitHub_.
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/
.. _git-flow: https://github.com/nvie/gitflow
.. _Downloads: https://github.com/mayan-edms/mayan-edms/archives/master
Steps to deploy a development version
-------------------------------------
.. code-block:: bash
$ git clone https://github.com/mayan-edms/mayan-edms.git
$ git clone https://gitlab.com/mayan-edms/mayan-edms.git
$ cd mayan-edms
$ git checkout development
$ virtualenv venv
@@ -372,14 +371,12 @@ Then on a separate console launch a celery worker from the same provisioned Vagr
Contributing changes
--------------------
Once your have created and committed some new code or feature, submit a Pull Request.
Be sure to merge with mayan-edms/development before doing a pull request so that patches
apply as cleanly as possible. If there are no conflicts, Pull Requests can be merged
directly from Github otherwise a manual command line merge has to be done and
your patches might take longer to get merged.
For more information on how to create Pull Request read: https://help.github.com/articles/using-pull-requests
or the quick version: https://help.github.com/articles/creating-a-pull-request
Once your have created and committed some new code or feature, submit a Pull
Request. Be sure to merge with the development branch before doing a Pull
Request so that patches apply as cleanly as possible. If there are no conflicts,
Merge Requests can be merged directly from the website UI otherwise a manual
command line merge has to be done and your patches might take longer to get
merged.
Debugging

39
docs/topics/installation.rst
View File

@@ -26,7 +26,8 @@ Initialize a ``virtualenv`` to deploy the project:
$ pip install mayan-edms
By default **Mayan EDMS** will create a single file SQLite_ database, which makes
it very easy to start using **Mayan EDMS**. Populate the database with the project's schema doing:
it very easy to start using **Mayan EDMS**. Populate the database with the
project's schema doing:
.. code-block:: bash
@@ -34,13 +35,15 @@ it very easy to start using **Mayan EDMS**. Populate the database with the proje
$ mayan-edms.py runserver
Point your browser to http://127.0.0.1:8000. If everything was installed
correctly you should see the login screen and panel showing a randomly generated admin password.
correctly you should see the login screen and panel showing a randomly generated
admin password.
Mac OSX
-------
**Mayan EDMS** is dependant on a number of binary packages and the recommended way is
to use a package manager such as `MacPorts <https://www.macports.org/>`_ or `Homebrew <http://brew.sh/>`.
**Mayan EDMS** is dependant on a number of binary packages and the recommended
way is to use a package manager such as `MacPorts <https://www.macports.org/>`_
or `Homebrew <http://brew.sh/>`.
Use MacPorts to install binary dependencies
@@ -52,13 +55,6 @@ With MacPorts installed run the command:
sudo port install python-dev gcc tesseract-ocr unpaper python-virtualenv ghostscript libjpeg-dev libpng-dev poppler-utils
**Mayan EDMS** can use either Pillow, ImageMagick or GraphicsMagick as the backend to
convert images so in addition you can install GraphicsMagick ...
.. code-block:: bash
sudo port install graphicsmagick
Set the Binary paths
********************
@@ -68,19 +64,12 @@ to /usr/bin/ with ...
.. code-block:: bash
sudo ln -s /opt/local/bin/tesseract /usr/bin/tesseract && \
sudo ln -s /opt/local/bin/identify /usr/bin/identify && \
sudo ln -s /opt/local/bin/gs /usr/bin/gs
sudo ln -s /opt/local/bin/tesseract /usr/bin/tesseract
... alternatively set the paths in the ``settings/locals.py``
.. code-block:: python
# document converters
CONVERTER_IM_CONVERT_PATH = '/opt/local/bin/convert'
IM_IDENTIFY_PATH = '/opt/local/bin/identify'
GRAPHICS_BACKEND = 'converter.backends.graphicsmagick.GraphicsMagick'
GM_PATH = '/opt/local/bin/gm'
LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'
Or Use Homebrew
@@ -90,7 +79,7 @@ With Homebrew installed run the command:
.. code-block:: bash
brew install python gcc tesseract unpaper poppler libpng graphicsmagick postgresql
brew install python gcc tesseract unpaper poppler libpng postgresql
Set the Binary paths
********************
@@ -102,20 +91,14 @@ to /usr/bin/ with ...
.. code-block:: bash
sudo ln -s /usr/local/bin/tesseract /usr/bin/tesseract && \
sudo ln -s /usr/local/bin/identify /usr/bin/identify && \
sudo ln -s /usr/local/bin/unpaper /usr/bin/unpaper && \
sudo ln -s /usr/local/bin/pdftotext /usr/bin/pdftotext && \
sudo ln -s /usr/local/bin/gs /usr/bin/gs && \
sudo ln -s /usr/local/bin/gs /usr/bin/gs
... alternatively set the paths in the ``settings/locals.py``
.. code-block:: python
# document converters
CONVERTER_IM_CONVERT_PATH = '/usr/local/bin/convert'
IM_IDENTIFY_PATH = '/usr/local/bin/identify'
GRAPHICS_BACKEND = 'converter.backends.graphicsmagick.GraphicsMagick'
GM_PATH = '/usr/local/bin/gm'
LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'
Testing the install
@@ -145,6 +128,8 @@ After making sure everything is running correctly, stop the `runserver` command.
Deploy **Mayan EDMS** using the webserver of your preference. For more information
on deployment instructions and examples, checkout Django's official documentation
on the topic https://docs.djangoproject.com/en/1.6/howto/deployment/
For a simple production deployment setup follow the instructions in the
Deploying chapter <topics/deploying>
Other database managers