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

Update installation instruction using Docker.

Browse Source
This commit is contained in:
Roberto Rosario
2017-01-16 02:31:19 -04:00
parent a3c1b0873d
commit 2259cbde40
5 changed files with 204 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/_templates/donate.html vendored
View File

@@ -1,4 +1,16 @@
<h3>Support</h3>
<p>
Consulting, support, customization, rebranding, and plug-in development are available. Email for information to: <a href='mailto:info@mayan-edms.com'>info@mayan-edms.com</a>
<a href='http://www.mayan-edms.com/providers/'>Consulting and support plans are available, click here</a>.
</p>
<hr />
<p>
Or consider supporting Mayan EDMS by contributing to its development. (US tax payers, please note this contribution is not tax deductible).
</p>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="3PXN336XFXQNN">
<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1" style="display: none !important;">
</form>
<hr />

29
docs/index.rst
View File

@@ -1,26 +1,10 @@
Welcome to Mayan EDMS!
======================
Mayan EDMS is a `Free Open Source`_ `Electronic Document Management System`_, coded in
the Python language using the Django_ web application framework and released
under the `Apache 2.0 License`_. It provides an electronic vault or repository for electronic documents.
The easiest way to use Mayan EDMS is by using a Debian based Linux distribution
and install it from PyPI with the following commands:
.. code-block:: bash
$ sudo apt-get install libjpeg-dev libmagic1 libpng-dev \
libreoffice libtiff-dev gcc ghostscript gnupg python-dev \
python-virtualenv tesseract-ocr poppler-utils -y
$ virtualenv venv
$ source venv/bin/activate
(venv) pip install mayan-edms
(venv) mayan-edms.py initialsetup
(venv) mayan-edms.py runserver
Point your browser to 127.0.0.1:8000 and use the automatically created admin
account.
Mayan EDMS is a `Free Open Source`_ `Electronic Document Management System`_,
coded in the Python language using the Django_ web application framework and
released under the `Apache 2.0 License`_. It provides an electronic vault or
repository for electronic documents.
.. image:: /_static/overview.gif
:alt: Overview
@@ -28,9 +12,9 @@ account.
.. toctree::
:hidden:
Features <topics/features>
Installation <topics/installation>
Deploying <topics/deploying>
Features <topics/features>
Advanced deployment <topics/deploying>
Release notes and upgrading <releases/index>
Concepts <topics/index>
Development <topics/development>
@@ -42,6 +26,7 @@ account.
FAQ <topics/faq>
Contact <topics/contact>
.. _Docker: https://www.docker.com/
.. _Django: http://www.djangoproject.com/
.. _Free Open Source: http://en.wikipedia.org/wiki/Open_source
.. _Electronic Document Management System: https://en.wikipedia.org/wiki/Document_management_system

8
docs/releases/2.2.rst
View File

@@ -18,7 +18,7 @@ Other changes
- Improve upgrade instructions
- New image caching pipeline
- New drop down menus for the documents, folders and tags app as well as for
the user links
the user links
- Dashboard
- Moved licenses to their own module in every app
- Update project to work with Django 1.10.4
@@ -30,14 +30,14 @@ the user links
- Sample documents moved to distribution to allow running all tests in production.
- DEBUG now defaults to False.
- Production settings don't override the DEBUG variable. DEBUG can be set to True
on production install to debug errors live.
on production install to debug errors live.
- Refactor add document to folder view to allow adding a documents to multiple folders at the same time.
- Refactor the remove document from folder view to allow removing documents from multiple folders at the same time.
- Refactor the document mailing views and add support for sending multiple documents via email at the same time.
- Refactor the document metadata views and add support for adding multiple metadata types to a document at the same time.
- Addition of a new OCR backend using PyOCR. This backend tries first to do OCR
using libtesseract. If libtesseract is not available the backend defaults to
calling the Tesseract executable.
using libtesseract. If libtesseract is not available the backend defaults to
calling the Tesseract executable.
- Language list moved from document model to document form.
- Enable password validation for the user password change view, user password change API endpoint, current user view and current user API endpoint.
- New API endpoints (initial work by @lokeshmanmode):

176
docs/topics/deploying.rst
View File

@@ -1,24 +1,22 @@
=========
Deploying
=========
===================
Advanced deployment
===================
Below are some ways to deploye and use Mayan EDMS. Do use more than one method.
Mayan EDMS should be deployed like any other Django_ project and
preferably using virtualenv_.
OS "bare metal" 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.
Like other Django based projects Mayan EDMS can be deployed in a wide variety
of ways. The method provided below is only a bare minimum example.
These instructions are independent of the instructions mentioned in the
:doc:`installation` chapter but assume you have already made a test install to
test the compatibility of your operating system. These instruction are for
Ubuntu 16.10.
Binary dependencies
===================
Switch to superuser::
Ubuntu
------
sudo -i
Install all system dependencies::
If using a Debian_ or Ubuntu_ based Linux distribution, get the executable
requirements using::
apt-get install nginx supervisor redis-server postgresql \
libpq-dev libjpeg-dev libmagic1 libpng-dev libreoffice \
@@ -29,6 +27,79 @@ If using Ubuntu 16.10 also install GPG version 1 (as GPG version 2 is the new de
apt-get install gnupg1 -y
Mac OSX
-------
Mayan EDMS is dependent 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With MacPorts installed run the command:
.. code-block:: bash
sudo port install python-dev gcc tesseract-ocr unpaper \
python-virtualenv ghostscript libjpeg-dev libpng-dev \
poppler-utils
Set the Binary paths
********************
Mayan EDMS by default will look in /usr/bin/ for the binary files it needs
so either you can symlink the binaries installed via MacPorts in /opt/local/bin/
to /usr/bin/ with ...
.. code-block:: bash
sudo ln -s /opt/local/bin/tesseract /usr/bin/tesseract
... alternatively set the paths in the ``settings/locals.py``
.. code-block:: python
LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'
Or Use Homebrew
~~~~~~~~~~~~~~~
With Homebrew installed run the command:
.. code-block:: bash
brew install python gcc tesseract unpaper poppler libpng postgresql
Set the Binary paths
********************
Mayan EDMS by default will look in /usr/bin/ for the binary files it needs
so either you can symlink the binaries installed via brew in /usr/local/bin/
to /usr/bin/ with ...
.. code-block:: bash
sudo ln -s /usr/local/bin/tesseract /usr/bin/tesseract && \
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
... alternatively set the paths in the ``settings/locals.py``
.. code-block:: python
LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'
Common steps
------------
Switch to superuser::
sudo -i
Change to the directory where the project will be deployed::
cd /usr/share
@@ -200,70 +271,9 @@ Restart the services::
systemctl restart supervisor
systemctl restart nginx
Docker method
=============
Deploy the Docker image stack::
docker run --name postgres -e POSTGRES_DB=mayan -e POSTGRES_USER=mayan -e POSTGRES_PASSWORD=mysecretpassword -v /var/lib/postgresql/data -d postgres
docker run --name redis -d redis
docker run --name mayan-edms -p 80:80 --link postgres:postgres --link redis:redis -e POSTGRES_DB=mayan -e POSTGRES_USER=mayan -e POSTGRES_PASSWORD=mysecretpassword -v /usr/local/lib/python2.7/dist-packages/mayan/media -d mayanedms/monolithic
After the Mayan EDMS container finishes initializing (about 5 minutes), it will
be available by browsing to http://127.0.0.1. You can inspect the initialization
with::
docker logs mayan-edms
Docker Compose method
=====================
Create a file named ``environment`` with the following content::
POSTGRES_DB=mayan
POSTGRES_PASSWORD=mayanpassword
POSTGRES_USER=mayan
Create a file named ``docker-compose.yml`` with the content::
postgres:
env_file:
- ./environment
image: postgres
volumes:
- /var/lib/postgresql/data
redis:
image: redis
mayan-edms:
env_file:
- ./environment
image: mayanedms/monolithic
links:
- postgres
- redis
ports:
- "80:80"
volumes:
- /usr/local/lib/python2.7/dist-packages/mayan/media
Launch the entire stack (Postgres, Redis, and Mayan EDMS) using::
docker-compose -f docker-compose.yml -p mayanedms up -d
After the Mayan EDMS container finishes initializing (about 5 minutes), it will
be available by browsing to http://127.0.0.1. You can inspect the initialization
with::
docker logs mayanedms_mayan-edms_1
Vagrant method
==============
Make sure you have Vagrant and a provider properly installed as per
https://docs.vagrantup.com/v2/installation/index.html
Clone the repository and execute::
vagrant up production
.. _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

206
docs/topics/installation.rst
View File

@@ -1,143 +1,111 @@
============
Installation
============
Mayan EDMS should be deployed like any other Django_ project and
preferably using virtualenv_.
The easiest way to use Mayan EDMS is by using the official Docker_ image.
Make sure Docker_ is properly installed and working before attempting to install
Mayan EDMS.
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.
With Docker properly installed, proceed to download the Mayan EDMS image using
the command:
Bellow are the step needed for a test install.
.. code-block:: bash
Binary dependencies
===================
docker pull mayanedms/mayanedms
Ubuntu
------
After the image finishes downloading, initialize a Mayan EDMS container.
If using a Debian_ or Ubuntu_ based Linux distribution, get the executable
requirements using::
.. code-block:: bash
sudo apt-get install libjpeg-dev libmagic1 libpng-dev libreoffice libtiff-dev gcc ghostscript gpgv python-dev python-virtualenv tesseract-ocr poppler-utils -y
docker run --rm -v mayan_media:/var/lib/mayan \
-v mayan_settings:/etc/mayan mayanedms/mayanedms mayan:init
With initialization complete, launch the container. If another web server is
running on port 80 use a different port in the -p option, ie: -p 81:80.
Mac OSX
.. code-block:: bash
docker run -d --name mayan-edms --restart=always -p 80:80 \
-v mayan_media:/var/lib/mayan -v mayan_settings:/etc/mayan \
mayanedms/mayanedms
Point your browser to 127.0.0.1 (or the alternate port chosen, ie: 127.0.0.1:81)
and use the automatically created admin account.
All files will be stored in the following two volumes:
- mayan_media
- mayan_settings
Stopping and starting
---------------------
To stop the container use::
docker stop mayan-edms
To start the container again::
docker start mayan-edms
Configuring
-----------
To edit the settings file, check the physical location of the `mayan_settings`
volume using::
docker volume inspect mayan_settings
Which should produce an output similar to this one:
.. code-block:: bash
[
{
"Name": "mayan_settings",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/mayan_settings/_data",
"Labels": null,
"Scope": "local"
}
]
In this case the physical location of the `mayan_settings` volume is
`/var/lib/docker/volumes/mayan_settings/_data`. Edit the settings file with your
favorite editor::
sudo vi /var/lib/docker/volumes/mayan_settings/_data/local.py
Backups
-------
Mayan EDMS is dependent 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/>`_.
To backup the existing data, check the physical location of the `mayan_media`
volume using::
docker volume inspect mayan_media
Use MacPorts to install binary dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With MacPorts installed run the command:
Which should produce an output similar to this one:
.. code-block:: bash
sudo port install python-dev gcc tesseract-ocr unpaper \
python-virtualenv ghostscript libjpeg-dev libpng-dev \
poppler-utils
[
{
"Name": "mayan_settings",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/mayan_media/_data",
"Labels": null,
"Scope": "local"
}
]
Set the Binary paths
********************
Only the `db.sqlite3` file and the `document_storage` folder need to be backed
up::
Mayan EDMS by default will look in /usr/bin/ for the binary files it needs
so either you can symlink the binaries installed via MacPorts in /opt/local/bin/
to /usr/bin/ with ...
sudo tar -zcvf backup.tar.gz /var/lib/docker/volumes/mayan_media/_data/document_storage /var/lib/docker/volumes/mayan_media/_data/db.sqlite3
sudo chown `whoami` backup.tar.gz
.. code-block:: bash
Restore
-------
Uncompress the archive in the original docker volume using::
sudo ln -s /opt/local/bin/tesseract /usr/bin/tesseract
... alternatively set the paths in the ``settings/locals.py``
.. code-block:: python
LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'
Or Use Homebrew
~~~~~~~~~~~~~~~
With Homebrew installed run the command:
.. code-block:: bash
brew install python gcc tesseract unpaper poppler libpng postgresql
Set the Binary paths
********************
Mayan EDMS by default will look in /usr/bin/ for the binary files it needs
so either you can symlink the binaries installed via brew in /usr/local/bin/
to /usr/bin/ with ...
.. code-block:: bash
sudo ln -s /usr/local/bin/tesseract /usr/bin/tesseract && \
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
... alternatively set the paths in the ``settings/locals.py``
.. code-block:: python
LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'
Actual project installation
===========================
Initialize a ``virtualenv`` to deploy the project:
.. code-block:: bash
virtualenv venv
source venv/bin/activate
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:
.. code-block:: bash
mayan-edms.py initialsetup
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.
Background tasks and scheduled tasks will not run when using the test server.
The ``runserver`` command is only meant for testing, do not use in a production
server.
Note that the default IP address, 127.0.0.1, is not accessible from other
machines on your network. To make your test server viewable to other
machines on the network, use its own IP address (e.g. 192.168.2.1) or 0.0.0.0 or :: (with IPv6 enabled).
You can provide an IPv6 address surrounded by brackets (e.g. [200a::1]:8000). This will automatically enable IPv6 support.
Production use
==============
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.7/howto/deployment/
For a simple production deployment setup follow the instructions in the
:doc:`deploying` chapter.
sudo tar -xvzf backup.tar.gz -C /
.. _Debian: http://www.debian.org/
.. _Django: http://www.djangoproject.com/
.. _Download: https://github.com/mayan-edms/mayan-edms/archives/master
.. _Python: http://www.python.org/
.. _SQLite: https://www.sqlite.org/
.. _Ubuntu: http://www.ubuntu.com/
.. _virtualenv: http://www.virtualenv.org/en/latest/index.html
.. _Docker: https://www.docker.com/