diff --git a/docs/chapters/deploying.rst b/docs/chapters/deploying.rst index 1b94d20222..b2161d3eba 100644 --- a/docs/chapters/deploying.rst +++ b/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 \ - 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/ diff --git a/docs/chapters/docker.rst b/docs/chapters/docker.rst index 88a63f6be9..2f5c7ef45f 100644 --- a/docs/chapters/docker.rst +++ b/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: - -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 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: - -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: 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 ` - -``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 ` - -``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 ` - ``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 ` - ``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 ==================== diff --git a/docs/chapters/docker_installation.rst b/docs/chapters/docker_installation.rst new file mode 100644 index 0000000000..a022168edc --- /dev/null +++ b/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: + +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 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: + +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: diff --git a/docs/releases/3.2.rst b/docs/releases/3.2.rst index 578bc8f1e5..163ebd18c8 100644 --- a/docs/releases/3.2.rst +++ b/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 diff --git a/docs/topics/administration.rst b/docs/topics/administration.rst index 29899dbf50..9556cb8bf5 100644 --- a/docs/topics/administration.rst +++ b/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 diff --git a/docs/topics/installation.rst b/docs/topics/installation.rst index 453101a32c..036e208484 100644 --- a/docs/topics/installation.rst +++ b/docs/topics/installation.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/