Direct deployment¶

Mayan EDMS should be deployed like any other Django project and preferably using virtualenv.

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.

The installation steps will be performed on “Debian 11”.

Install binary dependencies:

sudo apt-get install --yes ca-certificates fonts-arphic-uming \
fonts-arphic-ukai fonts-unfonts-core gcc gnupg1 graphviz libfuse2 \
libarchive-zip-perl libimage-exiftool-perl libmagic1 \
libreoffice-calc-nogui libreoffice-draw-nogui libreoffice-impress-nogui \
libreoffice-math-nogui libreoffice-writer-nogui libfile-mimeinfo-perl \
libldap-2.4-2 libldap-dev libpq-dev libpq5 libsasl2-dev libsasl2-2 \
poppler-utils postgresql python3-dev python3-venv rabbitmq-server \
redis-server sane-utils supervisor tesseract-ocr

Important

For Mayan EDMS 4.1 and later, Supervisord must be upgraded to version 4.2.2 or later. See troubleshooting section: After upgrade to version 4.1

Note

Platforms with the ARM CPU might also need additional requirements:

sudo apt-get install --yes libffi-dev libssl-dev

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 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 --parent /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 python3 -m venv /opt/mayan-edms/
```
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 pip==21.3.1

Install Mayan EDMS from PyPI:

sudo -u mayan /opt/mayan-edms/bin/pip install mayan-edms

Install the Python client for PostgreSQL, RabbitMQ, and Redis:

sudo -u mayan /opt/mayan-edms/bin/pip install amqp==5.0.9 psycopg2==2.9.2 redis==4.0.2

Note

Platforms with the ARM CPU might also need additional requirements:

sudo -u mayan /opt/mayan-edms/bin/pip install psutil==5.8.0

Create the RabbitMQ user and vhost:

sudo rabbitmqctl add_user mayan mayanrabbitmqpassword
sudo rabbitmqctl add_vhost mayan
sudo rabbitmqctl set_permissions -p mayan mayan ".*" ".*" ".*"

Create the database for the installation:

sudo -u postgres psql -c "CREATE USER mayan WITH password 'mayanuserpass';"
sudo -u postgres createdb -O mayan mayan

Configure Redis:

Configure Redis to discard data when it runs out of memory, not save its database, keep 3 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 3" | sudo tee -a /etc/redis/redis.conf
echo "requirepass mayanredispassword" | sudo tee -a /etc/redis/redis.conf
sudo systemctl restart redis

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 the MAYAN_MEDIA_ROOT variable in this and all subsequent steps. Be sure to first create the folder and give ownership of it to the mayan user with the chown 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_CELERY_BROKER_URL="amqp://mayan:mayanrabbitmqpassword@127.0.0.1:5672/mayan" \
MAYAN_CELERY_RESULT_BACKEND="redis://:mayanredispassword@127.0.0.1:6379/1" \
MAYAN_DATABASES="{'default':{'ENGINE':'django.db.backends.postgresql','NAME':'mayan','PASSWORD':'mayanuserpass','USER':'mayan','HOST':'127.0.0.1'}}" \
MAYAN_LOCK_MANAGER_BACKEND="mayan.apps.lock_manager.backends.redis_lock.RedisLock" \
MAYAN_LOCK_MANAGER_BACKEND_ARGUMENTS="{'redis_url':'redis://:mayanredispassword@127.0.0.1:6379/2'}" \
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-edms.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-edms.conf file and update all directory references from /opt/mayan-edms/ to match your custom installation directory.
```
sudo -u mayan 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-edms.conf"
```

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 --yes libjpeg-dev libpq-dev libpng-dev libtiff-dev zlib1g-dev
```

[1]: https://bugs.launchpad.net/ubuntu/+source/supervisor/+bug/1594740