diff --git a/docs/_templates/donate.html b/docs/_templates/donate.html index 85126af031..42850e33d2 100644 --- a/docs/_templates/donate.html +++ b/docs/_templates/donate.html @@ -1,4 +1,16 @@

Support

- Consulting, support, customization, rebranding, and plug-in development are available. Email for information to: info@mayan-edms.com + Consulting and support plans are available, click here.

+
+

+ Or consider supporting Mayan EDMS by contributing to its development. (US tax payers, please note this contribution is not tax deductible). +

+
+ + + + +
+ +
diff --git a/docs/index.rst b/docs/index.rst index 4b35bd36e2..51f7d0a5c9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 Installation - Deploying + Features + Advanced deployment Release notes and upgrading Concepts Development @@ -42,6 +26,7 @@ account. FAQ 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 diff --git a/docs/releases/2.2.rst b/docs/releases/2.2.rst index b160a603b4..af0b3a41ed 100644 --- a/docs/releases/2.2.rst +++ b/docs/releases/2.2.rst @@ -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): diff --git a/docs/topics/deploying.rst b/docs/topics/deploying.rst index e9dccbb704..f16bbd59ad 100644 --- a/docs/topics/deploying.rst +++ b/docs/topics/deploying.rst @@ -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 `_ +or `Homebrew `_. + + +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 diff --git a/docs/topics/installation.rst b/docs/topics/installation.rst index 813f6a03c0..095b052d39 100644 --- a/docs/topics/installation.rst +++ b/docs/topics/installation.rst @@ -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 `_ -or `Homebrew `_. +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/