Documentation: Add install troubleshooting

Add section to outline common pitfalls when installing.
Reference GitLab issue #487.

Update installation instructons to use the setting
MAYAN_DATABASES instead of the old MAYAN_DATABASE_*.

Unify the installation instructions by converting the
chapters into partials that are now included in the
topic file.

Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>

docs/chapters/deploying.rst

@@ -73,9 +73,8 @@ Initialize the project:
 -----------------------
 ::
 
-    sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
+    sudo -u mayan MAYAN_DATABASES='{ENGINE: django.db.backends.postgresql, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, HOST=127.0.0.1}' \
-    MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
+    MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
-    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:
@@ -96,12 +95,7 @@ Create the supervisor file at ``/etc/supervisor/conf.d/mayan.conf``:
         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_DATABASES='{ENGINE: django.db.backends.postgresql, HOST: 127.0.0.1, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, CONN_MAX_AGE: 60}',
-        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]
@@ -240,9 +234,8 @@ Initialize the project:
 -----------------------
 ::
 
-    sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
+    sudo -u mayan MAYAN_DATABASES='{ENGINE: django.db.backends.postgresql, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, HOST=127.0.0.1}' \
-    MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
+    MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
-    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:
@@ -271,12 +264,7 @@ Create the supervisor file at ``/etc/supervisor/conf.d/mayan.conf``:
         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_DATABASES='{ENGINE: django.db.backends.postgresql, HOST: 127.0.0.1, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, CONN_MAX_AGE: 60}',
-        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]
@@ -345,6 +333,36 @@ Enable and restart the services [1_]:
     systemctl enable supervisor
     systemctl restart supervisor
 
+
+Troubleshooting
+===============
+
+- Due to OS differences some binaries might reside in different locations.
+  Use environment variables or the configuration file to tell Mayan EDMS where
+  to file these binaries.
+
+  Example: OpenBSD. Add the following entries to supervisor configuration files.
+  ::
+
+      MAYAN_DOCUMENT_PARSING_PDFTOTEXT_PATH=/usr/local/bin/pdftotext,
+      MAYAN_SIGNATURES_GPG_PATH=/usr/local/bin/gpg,
+      MAYAN_SOURCES_SCANIMAGE_PATH: /usr/local/bin/scanimage,
+
+  Alternatively a symlink from the actual binary location to where Mayan
+  EDMS is expecting them to be found by default also works for some users::
+
+      ln -s /usr/local/bin/gpg /usr/bin/gpg1
+
+  Example 2: Ubuntu 16.04. Add the following entries to supervisor
+  configuration files.
+  ::
+
+      MAYAN_SIGNATURES_GPG_PATH=/usr/bin/gpg1,
+
+  Or add a symlink::
+
+      ln -s /usr/bin/gpg /usr/bin/gpg1
+
 [1]: https://bugs.launchpad.net/ubuntu/+source/supervisor/+bug/1594740
 
 .. _Debian: https://www.debian.org/

docs/chapters/docker.rst

@@ -1,118 +1,10 @@
-============
+************
 Docker image
-============
+************
 
-How to use this image
-=====================
-
-.. _docker_install:
-
-Start a Mayan EDMS image
-------------------------
-
-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 driver 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::
 
@@ -127,9 +19,11 @@ To start the container again::
 .. _docker_environment_variables:
 
 Environment Variables
----------------------
+=====================
 
-The Mayan EDMS image can be configure via environment variables.
+In addition to the all the environment variables supported by Mayan EDMS, the
+Mayan EDMS image provides some additional variables to configure the Docker
+specifics of the image.
 
 ``MAYAN_DATABASE_ENGINE``
 
@@ -145,27 +39,6 @@ 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:
-: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:
-: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:
-:django-docs:`Settings, PASSWORD <ref/settings/#password>`
-
 ``MAYAN_DATABASE_HOST``
 
 Defaults to `None`. This optional environment variable is used to set the
@@ -215,12 +88,6 @@ be disabled.
 
 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: :django-docs:`Settings, CONN_MAX_AGE <ref/settings/#conn-max-age>`
-
 ``MAYAN_GUNICORN_WORKERS``
 
 Optional. This environment variable controls the number of frontend workers
@@ -252,6 +119,7 @@ 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
 ======================
 
@@ -297,6 +165,7 @@ 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
 =======================
 
@@ -304,6 +173,7 @@ Uncompress the backup archive in the original docker volume using::
 
     sudo tar -xvzf backup.tar.gz -C /
 
+
 Upgrading
 =========
 
@@ -333,6 +203,7 @@ 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
 ==================
 
@@ -355,9 +226,11 @@ Or using an apt cacher to speed up the build::
 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
 -------------
 
@@ -379,6 +252,7 @@ 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
 ====================
 

docs/chapters/docker_installation.rst

@@ -0,0 +1,109 @@
+*******************
+Docker installation
+*******************
+
+Docker is a system that allows running programs in isolated areas which
+have restricted access to resources, devices, and memory. Docker usage also
+distributing software as a single file.
+
+Make sure Docker is properly installed and working before attempting to install
+Mayan EDMS.
+
+Docker can be installed using their automated script::
+
+    wget -qO- https://get.docker.com/ | sh
+
+This installs the latest versions of Docker. If you don't want run an automated
+script follow the instructions outlined in their documentation:
+https://docs.docker.com/install/
+
+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_DATABASES='{ENGINE: django.db.backends.postgresql, HOST: 172.17.0.1, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, 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 driver 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_DATABASES='{ENGINE: django.db.backends.postgresql, HOST: mayan-edms-postgres, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, CONN_MAX_AGE: 60}' \
+    -v /docker-volumes/mayan-edms/media:/var/lib/mayan \
+    mayanedms/mayanedms:<version>

docs/releases/3.2.rst

@@ -77,6 +77,7 @@ Backward incompatible changes
 Bugs fixed or issues closed
 ---------------------------
 
+* :gitlab-issue:`487` gnupg1 Issue with Ubuntu 16.04 - Could not show/view documents
 * :gitlab-issue:`498` Can't scan subdirectories
 * :gitlab-issue:`522` Office 365 SMTP
 * :gitlab-issue:`539` Setting for default email sender is missing

docs/topics/administration.rst

@@ -9,3 +9,4 @@ Administration
 .. include:: ../chapters/backups.rst
 .. include:: ../chapters/scaling_up.rst
 .. include:: ../chapters/database_conversion.rst
+.. include:: ../chapters/docker.rst

docs/topics/installation.rst

@@ -2,9 +2,11 @@
 Installation
 ############
 
-The easiest way to use Mayan EDMS is by using the official Docker_ image.
+Mayan EDMS can be install in several way. The two recommended ways are: by
-Make sure Docker is properly installed and working before attempting to install
+using Docker_, and by doing a direct installation.
-Mayan EDMS.
+
+The Docker method provides the easiest installation process while the direct
+installation provides better performance and customization.
 
 *****************************
 Minimum hardware requirements
@@ -15,34 +17,9 @@ Minimum hardware requirements
 - Unix-like operating system like Linux and OpenBSD. For other operating systems
   user container technologies like Docker or virtual machines.
 
-****************
-Docker procedure
-****************
 
-Docker is a computer program that performs operating-system-level
+.. include:: ../chapters/docker_installation.rst
-virtualization also known as containerization. It allows independent
+.. include:: ../chapters/deploying.rst
-"containers" to run within a single Linux instance, avoiding the overhead
-of starting and maintaining virtual machines (VMs).
-
-Docker can be installed using their automated script::
-
-    wget -qO- https://get.docker.com/ | sh
-
-This installs the latest versions of Docker. If you don't want run an automated
-script follow the instructions outlined in their documentation: https://docs.docker.com/install/
-
-Once the Docker installation is finished, proceed to the link below to install
-the Docker image for Mayan EDMS.
-
-Docker image chapter: :ref:`docker_install`
-
-*******************
-Direct installation
-*******************
-
-For users with knowledge of Python, Django, Ubuntu, and databases.
-
-Deployments chapter: :doc:`../chapters/deploying`
 
 
 .. _Docker: https://www.docker.com/