diff --git a/README.md b/README.md index c7be86ac9b..da7d9d125d 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,13 @@ ![python][python] ![license][license] +[![Docker pulls](https://img.shields.io/docker/pulls/mayanedms/mayanedms.svg?maxAge=3600)](https://hub.docker.com/r/mayanedms/mayanedms/) +[![Docker Stars](https://img.shields.io/docker/stars/mayanedms/mayanedms.svg?maxAge=3600)](https://hub.docker.com/r/mayanedms/mayanedms/) +[![Docker layers](https://images.microbadger.com/badges/image/mayanedms/mayanedms.svg)](https://microbadger.com/images/mayanedms/mayanedms) +[![Docker version](https://images.microbadger.com/badges/version/mayanedms/mayanedms.svg)](https://microbadger.com/images/mayanedms/mayanedms) +![Docker build](https://img.shields.io/docker/automated/mayanedms/mayanedms.svg) +![License](https://img.shields.io/badge/License-MIT-green.svg?maxAge=3600) + [pypi]: http://img.shields.io/pypi/v/mayan-edms.svg [pypi-url]: http://badge.fury.io/py/mayan-edms diff --git a/docs/index.rst b/docs/index.rst index 0197410e57..20e506a3ca 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,14 +19,12 @@ repository for electronic documents. Installation Features - Advanced deployment Release notes and upgrading Concepts Development App creation Roadmap Translations - Contributors Licensing FAQ Contact diff --git a/docs/topics/contributors.rst b/docs/topics/contributors.rst deleted file mode 100644 index 59989fe853..0000000000 --- a/docs/topics/contributors.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _contributors: - -============ -Contributors -============ - - -How to contribute? ------------------- - -You can help further the development of Mayan EDMS by testing, reporting -bugs, submitting documentation or code patches. - -Lead developer --------------- -* Roberto Rosario (roberto.rosario@mayan-edms.com) - -Contributors (in alphabetical order) ------------------------------------- -* Aziz M. Bookwala (https://github.com/azizmb) -* Bertrand Bordage (https://github.com/BertrandBordage) -* Brian E (brian@realize.org) -* David Herring (https://github.com/abadger1406) -* Emlyn Clay (https://github.com/EmlynC) -* Jens Kadenbach (https://github.com/audax) -* Kolmar Kafran -* Helga Carrero -* IHLeanne (https://github.com/IHLeanne) -* Iliya Georgiev (ikgeorgiev@gmail.com) -* Lars Kruse (devel@sumpfralle.de) -* Mathias Behrle -* Meurig Freeman (https://github.com/meurig) -* Nate Aune (nate@appsembler.com) -* Paul Whipp [https://github.com/pwhipp] [http://paulwhippconsulting.com] -* Rafael Esparra -* Sergey Glita (s.v.glita@gmail.com) -* Simone Federici [https://twitter.com/aldaranalton] [https://github.com/simone] -* Webfaction (https://www.webfaction.com) diff --git a/docs/topics/deploying.rst b/docs/topics/deploying.rst index 88af0bcd2f..d541cdab04 100644 --- a/docs/topics/deploying.rst +++ b/docs/topics/deploying.rst @@ -1,3 +1,5 @@ +.. _deploying: + =================== Advanced deployment =================== diff --git a/docs/topics/docker.rst b/docs/topics/docker.rst new file mode 100644 index 0000000000..2ba3fd5434 --- /dev/null +++ b/docs/topics/docker.rst @@ -0,0 +1,277 @@ +.. _docker: + + +============ +Docker image +============ + +How to use this image +===================== + +Start a Mayan EDMS instance +------------------------------ + +With Docker properly installed, proceed to download the Mayan EDMS image using the command:: + + docker pull mayanedms/mayanedms: + docker run -d --name mayan-edms --restart=always -p 80:8000 -v /docker-volumes/mayan:/var/lib/mayan mayanedms/mayanedms: + +Change with the latest version in numeric form (example: 2.7.3) or user the ``latest`` identifier. + +The container will be available by browsing to ``http://localhost`` + +All files will be stored in the directory ``/docker-volumes/mayan`` + +If another web server is running on port 80 use a different port in the ``-p`` option, ie: ``-p 81:8000``. + + +Stopping and starting the container +-------------------------------------- + +To stop the container use:: + + docker stop mayan-edms + + +To start the container again:: + + docker start mayan-edms + + +Environment Variables +--------------------- + +The Mayan EDMS image can be configure via environment variables. + +``MAYAN_DATABASE_ENGINE`` + +Defaults to ``None``. This environment variable configures the database +backend to use. If left unset, SQLite will be used. The database backends +supported by this Docker image are: + +- 'django.db.backends.postgresql' +- 'django.db.backends.mysql' +- 'django.db.backends.sqlite3' same as ``None`` + +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: +[Connecting to the database](https://docs.djangoproject.com/en/1.10/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: [Settings, USER](https://docs.djangoproject.com/en/1.10/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: [Settings, PASSWORD](https://docs.djangoproject.com/en/1.10/ref/settings/#password) + +``MAYAN_DATABASE_HOST`` + +Defaults to `None`. This optional environment variable is used to set the +hostname that will be used to connect to the database. This can be the +hostname of another container or an IP address. For more information read +the pertinent Django documentation page: [Settings, HOST](https://docs.djangoproject.com/en/1.10/ref/settings/#host) + +``MAYAN_DATABASE_PORT`` + +Defaults to `None`. This optional environment variable is used to set the +port number to use when connecting to the database. An empty string means +the default port. Not used with SQLite. For more information read the +pertinent Django documentation page: [Settings, PORT](https://docs.djangoproject.com/en/1.11/ref/settings/#port) + +``MAYAN_BROKER_URL`` + +This optional environment variable determines the broker that Celery will use +to relay task messages between the frontend code and the background workers. +For more information read the pertinent Celery Kombu documentation page: [Broker URL](http://kombu.readthedocs.io/en/latest/userguide/connections.html#connection-urls) + +This Docker image supports using Redis and RabbitMQ as brokers. + +Caveat: If the `MAYAN_BROKER_URL` and `MAYAN_CELERY_RESULT_BACKEND` environment +variables are specified, the built-in Redis server inside the container will +be disabled. + +``MAYAN_CELERY_RESULT_BACKEND`` + +This optional environment variable determines the results backend that Celery +will use to relay result messages from the background workers to the frontend +code. For more information read the pertinent Celery Kombu documentation page: +[Task result backend settings](http://docs.celeryproject.org/en/3.1/configuration.html#celery-result-backend) + +This Docker image supports using Redis and RabbitMQ as result backends. + +Caveat: If the `MAYAN_BROKER_URL` and `MAYAN_CELERY_RESULT_BACKEND` environment +variables are specified, the built-in Redis server inside the container will +be disabled. + +``MAYAN_SETTINGS_MODULE`` + +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: [Settings, CONN_MAX_AGE](https://docs.djangoproject.com/en/1.10/ref/settings/#conn-max-age) + + +Accessing outside data +====================== + +To use Mayan EDMS's staging folders or watch folders from Docker, the data +for these source must be made accessible to the container. This is done by +mounting the folders in the host computer to folders inside the container. +This is necessary because Docker containers do not have access to host data +on purpose. For example, to make a folder in the host accessible as a watch +folder, add the following to the Docker command line when starting the +container:: + + -v /opt/scanned_files:/srv/watch_folder + +The complete command line would then be:: + + docker run -d --name mayan-edms --restart=always -p 80:8000 -v /docker-volumes/mayan:/var/lib/mayan -v /opt/scanned_files:/srv/watch_folder mayanedms/mayanedms:latest + +Now create a watch folder in Mayan EDMS using the path `/srv/watch_folder` +and the documents from the host folder `/opt/scanned_files` will be +automatically available. Use the same procedure to mount host folders to be +used as staging folderes. In this example `/srv/watch_folder` was as the +container directory, but any path can be used as long as it is not an +already existing path or a path used by any other program. + + +Performing backups +================== + +To backup the existing data, stop the image and copy the content of the volume. +For the example:: + + docker run -d --name mayan-edms --restart=always -p 80:8000 -v /docker-volumes/mayan:/var/lib/mayan -v /opt/scanned_files:/srv/watch_folder mayanedms/mayanedms:latest + +That would be the ``/docker-volumes/mayan folder``:: + + sudo tar -zcvf backup.tar.gz /docker-volumes/mayan + sudo chown `whoami` backup.tar.gz + +If using an external PostgreSQL or MySQL database or database containers, these +too need to be backed up using their respective procedures. + +Restoring from a backup +======================= + +Uncompress the backup archive in the original docker volume using:: + + sudo tar -xvzf backup.tar.gz -C / + +Upgrading +========= + +Upgrading a Mayan EDMS Docker container is actually a matter of stopping and +deleting the container, downloading the most recent version of the image and +starting a container again. The container will take care of updating the +database structure to the newest version if necessary. + +**IMPORTANT!** Do not delete the volume storing the data, only the container. + +Stop the container to be upgraded:: + + docker stop mayan-edms + + +Remove the container:: + + docker rm mayan-edms + + +Pull the new image version:: + + docker pull mayanedms/mayanedms:latest + + +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 +================== + +Clone the repository with:: + + git clone https://gitlab.com/mayan-edms/mayan-edms.git + +Change to the directory of the cloned repository:: + + cd mayan-edms + +Execute Docker's build command using the provided makefile:: + + make docker-build + +Or using an apt cacher to speed up the build:: + + make docker-build-with-proxy APT_PROXY=172.17.0.1:3142 + +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 +------------- + +If you just need to add a few Ubuntu or Python packages to your installation, +you can use the following environment variables: + +``MAYAN_APT_INSTALLS`` + +Specifies a list of Ubuntu .deb packages to be installed via APT when the +container is first created. The installed packages are not lost when the image +is stopped. Example: To install the Tesseract OCR language packs for German +and Spanish add the following in your `docker start` command line:: + + -e MAYAN_APT_INSTALLS="tesseract-ocr-deu tesseract-ocr-spa" + +``MAYAN_PIP_INSTALLS`` + +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 +==================== + +To deploy a complete production stack using the included Docker compose file +execute:: + + docker-compose -f docker-compose.yml up -d + +This Docker compose file will provision four containers: + +- Postgres as the database +- Redis as the Celery result storage +- RabbitMQ as the Celery broker +- Mayan EDMS using the above service containers + +To stop the stack use:: + + docker-compose -f docker-compose.yml stop + +The stack will also create four volumes to store the data of each container. +These are: + +- mayan_app - The Mayan EDMS data container, normally called `mayan_data` when not using Docker compose. +- mayan_broker - The broker volume, in this case RabbitMQ. +- mayan_db - The database volume, in this case Postgres. +- mayan_results - The celery result backend volume, in this case Redis. diff --git a/docs/topics/index.rst b/docs/topics/index.rst index cc0d05abd4..1365232361 100644 --- a/docs/topics/index.rst +++ b/docs/topics/index.rst @@ -27,3 +27,4 @@ Introductions to all the key parts of Mayan EDMS you'll need to know: upload_wizard pending_work code_statistics + docker diff --git a/docs/topics/installation.rst b/docs/topics/installation.rst index 42a8561cea..5b86791a60 100644 --- a/docs/topics/installation.rst +++ b/docs/topics/installation.rst @@ -14,9 +14,19 @@ Hardware requirements Docker procedure ---------------- -For the complete set of installation, configuration, upgrade, and backup -instructions visit the Mayan EDMS Docker Hub page at: -https://hub.docker.com/r/mayanedmsng/mayanedmsng/ +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). + +:ref:`docker` + +Advanced deployment +------------------- + +For users with knowledge of Python, Django, Ubuntu, and databases. + +:ref:`deploying` .. _Docker: https://www.docker.com/ diff --git a/docs/topics/languages.rst b/docs/topics/languages.rst index 277ed0a38a..8318ba37d6 100644 --- a/docs/topics/languages.rst +++ b/docs/topics/languages.rst @@ -4,10 +4,10 @@ Languages The list of languages choices in the language dropdown used for documents is based on the current ISO 639 list. This list can be quite extensive. To reduce -the number of languages available use the settings ``DOCUMENTS_LANGUAGE_CHOICES``, +the number of languages available use the settings ``DOCUMENTS_LANGUAGE_CODES``, and set it to a nested list of abbreviations + languages names like:: - DOCUMENTS_LANGUAGE_CHOICES = (('eng', 'English'), ('spa', 'Spanish')) + DOCUMENTS_LANGUAGE_CODES = ('eng', 'spa') The default language to appear on the dropdown can also be configured using::