Direct deployment¶
Mayan EDMS should be deployed like any other Django project and preferably using virtualenv. Below are some ways to deploy and use 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.
Compilers and development libraries will be installed to compile runtime libraries. LibreOffice and Poppler utils will also be installed as they are used to convert document files. Supervisor (https://supervisord.org/), a Process Control System, will be used to monitor and keep all Mayan processes running.
Basic deployment¶
This setup uses less memory and CPU resources at the expense of some speed. For another setup that offers more performance and scalability refer to the Advanced deployment below.
Install binary dependencies:
If using a Debian or Ubuntu based Linux distribution, get the executable requirements using:
sudo apt-get install exiftool g++ gcc coreutils ghostscript gnupg1 graphviz \ libfuse2 libjpeg-dev libmagic1 libpq-dev libpng-dev libreoffice \ libtiff-dev poppler-utils postgresql python3-dev python3-virtualenv \ redis-server sane-utils supervisor tesseract-ocr zlib1g-dev -y
Note
Platforms with the ARM CPU might also need additional requirements:
sudo apt-get install libffi-dev libssl-dev -y
Create the user account for the installation:
This will create an unprivileged user account that is also unable to login:
sudo adduser mayan --disabled-password --disabled-login --gecos ""
Create the parent directory where the project will be deployed:
/opt/
is a good choice as it is meant is for “software and add-on packages that are not part of the default installation”. (https://www.tldp.org/LDP/Linux-Filesystem-Hierarchy/html/opt.html). Create the/opt
directory if it doesn’t already exists:sudo mkdir /opt
Create the Python virtual environment:
This will keep all the Python packages installed here isolated from the rest of the Python packages in the system:
sudo virtualenv /opt/mayan-edms -p /usr/bin/python3
Make the mayan user the owner of the installation directory:
sudo chown mayan:mayan /opt/mayan-edms -R
Upgrade to the latest pip version:
sudo -u mayan /opt/mayan-edms/bin/pip install -U pip
Install Mayan EDMS from PyPI:
sudo -u mayan /opt/mayan-edms/bin/pip install mayan-edms
Install the Python client for PostgreSQL and Redis:
sudo -u mayan /opt/mayan-edms/bin/pip install psycopg2==2.8.6 redis==3.5.3
Note
Platforms with the ARM CPU might also need additional requirements:
sudo -u mayan /opt/mayan-edms/bin/pip install psutil==5.7.0
Create the database for the installation:
sudo -u postgres psql -c "CREATE USER mayan WITH password 'mayanuserpass';" sudo -u postgres createdb -O mayan mayan
Initialize the project:
This step will create all the database structures, download and compress static media files like JavaScript libraries and HTML frameworks, and create and initial admin account with a random password.
Note
For simplicity, the
MAYAN_MEDIA_ROOT
folder is set to be a subfolder of the installation. If you want to keep your files separated from the installation files, change the value of theMAYAN_MEDIA_ROOT
variable in this and all subsequent steps. Be sure to first create the folder and give ownership of it to themayan
user with thechown
command.Warning
If this step is interrupted, even if it is later resumed, will cause the automatic admin user to not be created in some cases. Make sure all environment variables and values are correct. If this happens, refer to the troubleshooting chapters: Missing automatic admin account after installation and Admin password reset.
sudo -u mayan MAYAN_DATABASES="{'default':{'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
Create the supervisor file at
/etc/supervisor/conf.d/mayan.conf
:Note
The generated supervisor file assumes Mayan EDMS is being installed into
/opt/mayan-edms
. If you are installing Mayan EDMS in a different location, you must manually review the produced/etc/supervisor/conf.d/mayan.conf
file and update all directory references from/opt/mayan-edms
to match your custom installation directory.sudo -u mayan MAYAN_DATABASES="{'default':{'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 platformtemplate supervisord | sudo sh -c "cat > /etc/supervisor/conf.d/mayan.conf"
Configure Redis:
Configure Redis to discard data when it runs out of memory, not save its database, keep 2 database, and be password protected:
echo "maxmemory-policy allkeys-lru" | sudo tee -a /etc/redis/redis.conf echo "save \"\"" | sudo tee -a /etc/redis/redis.conf echo "databases 2" | sudo tee -a /etc/redis/redis.conf echo "requirepass mayanredispassword" | sudo tee -a /etc/redis/redis.conf sudo systemctl restart redis
Enable and restart the services [1]:
sudo systemctl enable supervisor sudo systemctl restart supervisor
Cleaning up:
The following operating system dependencies are only needed during installation and can be removed.
sudo apt-get remove --purge libjpeg-dev libpq-dev libpng-dev libtiff-dev zlib1g-dev
Advanced deployment¶
This variation uses RabbitMQ as the message broker. RabbitMQ consumes more memory but scales to thousands of messages per second. RabbitMQ messages are also persistent by default, this means that pending tasks are not lost in the case of a restart or power failure. The Gunicorn workers are increased to 3.
Install RabbitMQ:
If using a Debian or Ubuntu based Linux distribution, get the executable requirements using:
sudo apt-get install rabbitmq-server -y
Install the Python client for RabbitMQ:
sudo -u mayan /opt/mayan-edms/bin/pip install amqp==2.5.2
Create the RabbitMQ user and vhost:
sudo rabbitmqctl add_user mayan mayanrabbitmqpassword sudo rabbitmqctl add_vhost mayan sudo rabbitmqctl set_permissions -p mayan mayan ".*" ".*" ".*"
Edit the supervisor file at
/etc/supervisor/conf.d/mayan.conf
:Replace (paying attention to the comma at the end):
MAYAN_CELERY_BROKER_URL="redis://127.0.0.1:6379/0",
with:
MAYAN_CELERY_BROKER_URL="amqp://mayan:mayanrabbitmqpassword@localhost:5672/mayan",
increase the number of Gunicorn workers to 3 in the line (
-w 2
section):command = /opt/mayan-edms/bin/gunicorn -w 2 mayan.wsgi --max-requests 1000 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
remove the concurrency limit (or increase it) of the fast worker (remove
--concurrency=1
).Restart the services:
sudo supervisorctl reread sudo supervisorctl restart all
[1]: https://bugs.launchpad.net/ubuntu/+source/supervisor/+bug/1594740