Advanced 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.

Binary dependencies

Ubuntu

If using a Debian or Ubuntu based Linux distribution, get the executable requirements using:

apt-get install nginx supervisor redis-server postgresql \
libpq-dev libjpeg-dev libmagic1 libpng-dev libreoffice \
libtiff-dev gcc ghostscript gnupg python-dev python-virtualenv \
tesseract-ocr poppler-utils -y

If using Ubuntu 16.10 also install GPG version 1 (as GPG version 2 is the new default for this distribution and not yet supported by Mayan EDMS)

apt-get install gnupg1 -y

Mac OSX

Mayan EDMS is dependent on a number of binary packages and the recommended way is to use a package manager such as MacPorts or Homebrew.

Use MacPorts to install binary dependencies

With MacPorts installed run the command:

sudo port install python-dev gcc tesseract-ocr unpaper \
python-virtualenv ghostscript libjpeg-dev libpng-dev \
poppler-utils
Set the Binary paths

Mayan EDMS by default will look in /usr/bin/ for the binary files it needs so either you can symlink the binaries installed via MacPorts in /opt/local/bin/ to /usr/bin/ with ...

sudo ln -s /opt/local/bin/tesseract /usr/bin/tesseract

... alternatively set the paths in the settings/locals.py

LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'

Or Use Homebrew

With Homebrew installed run the command:

brew install python gcc tesseract unpaper poppler libpng postgresql
Set the Binary paths

Mayan EDMS by default will look in /usr/bin/ for the binary files it needs so either you can symlink the binaries installed via brew in /usr/local/bin/ to /usr/bin/ with ...

sudo ln -s /usr/local/bin/tesseract /usr/bin/tesseract  && \
sudo ln -s /usr/local/bin/unpaper /usr/bin/unpaper && \
sudo ln -s /usr/local/bin/pdftotext /usr/bin/pdftotext && \
sudo ln -s /usr/local/bin/gs /usr/bin/gs

... alternatively set the paths in the settings/locals.py

LIBREOFFICE_PATH = '/Applications/LibreOffice.app/Contents/MacOS/soffice'

Common steps

Switch to superuser:

sudo -i

Change to the directory where the project will be deployed:

cd /usr/share

Create the Python virtual environment for the installation:

virtualenv mayan-edms

Activate the virtualenv:

source mayan-edms/bin/activate

Install Mayan EDMS from PyPI:

pip install mayan-edms

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

pip install psycopg2 redis uwsgi

Create the database for the installation:

sudo -u postgres createuser -P mayan  (provide password)
sudo -u postgres createdb -O mayan mayan

Create the directory for the log files:

mkdir /var/log/mayan

Change the current directory to be the one of the installation:

cd mayan-edms

Make a convenience symbolic link:

ln -s lib/python2.7/site-packages/mayan .

Create an initial settings file:

mayan-edms.py createsettings

Append the following to the mayan/settings/local.py file, paying attention to replace the PASSWORD value:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'mayan',
        'USER': 'mayan',
        'PASSWORD': '<password used when creating postgreSQL user>',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

BROKER_URL = 'redis://127.0.0.1:6379/0'
CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/0'

If using Ubuntu 16.10, also add this line to the mayan/settings/local.py file:

SIGNATURES_GPG_PATH = '/usr/bin/gpg1'

Migrate the database or initialize the project:

mayan-edms.py initialsetup

Disable the default NGINX site:

rm /etc/nginx/sites-enabled/default

Create a uwsgi.ini file with the following contents:

[uwsgi]
chdir = /usr/share/mayan-edms/lib/python2.7/site-packages/mayan
chmod-socket = 664
chown-socket = www-data:www-data
env = DJANGO_SETTINGS_MODULE=mayan.settings.production
gid = www-data
logto = /var/log/uwsgi/%n.log
pythonpath = /usr/share/mayan-edms/lib/python2.7/site-packages
master = True
max-requests = 5000
socket = /usr/share/mayan-edms/uwsgi.sock
uid = www-data
vacuum = True
wsgi-file = /usr/share/mayan-edms/lib/python2.7/site-packages/mayan/wsgi.py

Create the directory for the uWSGI log files:

mkdir /var/log/uwsgi

Create the NGINX site file for Mayan EDMS, /etc/nginx/sites-available/mayan:

server {
    listen 80;
    server_name localhost;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/usr/share/mayan-edms/uwsgi.sock;

        client_max_body_size 30M;  # Increse if your plan to upload bigger documents
        proxy_read_timeout 30s;  # Increase if your document uploads take more than 30 seconds
    }

    location /static {
        alias /usr/share/mayan-edms/mayan/media/static;
        expires 1h;
    }

    location /favicon.ico {
        alias /usr/share/mayan-edms/mayan/media/static/appearance/images/favicon.ico;
        expires 1h;
    }
}

Enable the NGINX site for Mayan EDMS:

ln -s /etc/nginx/sites-available/mayan /etc/nginx/sites-enabled/

Create the supervisor file for the uWSGI process, /etc/supervisor/conf.d/mayan-uwsgi.conf:

[program:mayan-uwsgi]
command = /usr/share/mayan-edms/bin/uwsgi --ini /usr/share/mayan-edms/uwsgi.ini
user = root
autostart = true
autorestart = true
redirect_stderr = true

Create the supervisor file for the Celery worker, /etc/supervisor/conf.d/mayan-celery.conf:

[program:mayan-worker]
command = /usr/share/mayan-edms/bin/python /usr/share/mayan-edms/bin/mayan-edms.py celery --settings=mayan.settings.production worker -Ofair -l ERROR
directory = /usr/share/mayan-edms
user = www-data
stdout_logfile = /var/log/mayan/worker-stdout.log
stderr_logfile = /var/log/mayan/worker-stderr.log
autostart = true
autorestart = true
startsecs = 10
stopwaitsecs = 10
killasgroup = true
priority = 998

[program:mayan-beat]
command = /usr/share/mayan-edms/bin/python /usr/share/mayan-edms/bin/mayan-edms.py celery --settings=mayan.settings.production beat -l ERROR
directory = /usr/share/mayan-edms
user = www-data
numprocs = 1
stdout_logfile = /var/log/mayan/beat-stdout.log
stderr_logfile = /var/log/mayan/beat-stderr.log
autostart = true
autorestart = true
startsecs = 10
stopwaitsecs = 1
killasgroup = true
priority = 998

Collect the static files:

mayan-edms.py collectstatic --noinput

Make the installation directory readable and writable by the webserver user:

chown www-data:www-data /usr/share/mayan-edms -R

Restart the services:

systemctl enable supervisor
systemctl restart supervisor
systemctl restart nginx