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>
This commit is contained in:
Roberto Rosario
@@ -73,9 +73,8 @@ Initialize the project:
|
||||
-----------------------
|
||||
::
|
||||
|
||||
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 \
|
||||
sudo -u mayan MAYAN_DATABASES='{ENGINE: django.db.backends.postgresql, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, 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_DATABASE_HOST=127.0.0.1,
|
||||
MAYAN_DATABASE_NAME=mayan,
|
||||
MAYAN_DATABASE_PASSWORD=mayanuserpass,
|
||||
MAYAN_DATABASE_USER=mayan,
|
||||
MAYAN_DATABASE_CONN_MAX_AGE=60,
|
||||
MAYAN_DATABASES='{ENGINE: django.db.backends.postgresql, HOST: 127.0.0.1, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, 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 \
|
||||
MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
|
||||
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
|
||||
sudo -u mayan MAYAN_DATABASES='{ENGINE: django.db.backends.postgresql, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, 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_DATABASE_HOST=127.0.0.1,
|
||||
MAYAN_DATABASE_NAME=mayan,
|
||||
MAYAN_DATABASE_PASSWORD=mayanuserpass,
|
||||
MAYAN_DATABASE_USER=mayan,
|
||||
MAYAN_DATABASE_CONN_MAX_AGE=360,
|
||||
MAYAN_DATABASES='{ENGINE: django.db.backends.postgresql, HOST: 127.0.0.1, NAME: mayan, PASSWORD: mayanuserpass, USER: mayan, CONN_MAX_AGE: 60}',
|
||||
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/
|
||||
|
||||
@@ -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
|
||||
====================
|
||||
|
||||
|
||||
109
docs/chapters/docker_installation.rst
Normal file
109
docs/chapters/docker_installation.rst
Normal file
@@ -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>
|
||||
@@ -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
|
||||
|
||||
@@ -9,3 +9,4 @@ Administration
|
||||
.. include:: ../chapters/backups.rst
|
||||
.. include:: ../chapters/scaling_up.rst
|
||||
.. include:: ../chapters/database_conversion.rst
|
||||
.. include:: ../chapters/docker.rst
|
||||
|
||||
@@ -2,9 +2,11 @@
|
||||
Installation
|
||||
############
|
||||
|
||||
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.
|
||||
Mayan EDMS can be install in several way. The two recommended ways are: by
|
||||
using Docker_, and by doing a direct installation.
|
||||
|
||||
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
|
||||
virtualization also known as containerization. It allows independent
|
||||
"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`
|
||||
.. include:: ../chapters/docker_installation.rst
|
||||
.. include:: ../chapters/deploying.rst
|
||||
|
||||
|
||||
.. _Docker: https://www.docker.com/
|
||||
|
||||
Reference in New Issue
Block a user