[Guide] Install Mayan EDMS Document Management System [Arch Linux] and [Others]
Introduction These instructions were build in about a whole week, and I hit many many pits in this week. The point 'Setup Mayan-EDMS' on my ToDo-List was over two years old and I never found enough time to do it. But finally: here it is....
Why Arch Linux? Well, it is small, it runs on quite everything that is able to process 0 and 1, it uses as less ressources as possible but also can serve a whole Desktop, it is a 'rolling-release' - so no old software inside, it has a mature package manager and the most important: It is pure Linux. No Debian/Ubuntu wrappers, no Fedora/RedHat/CentOS properitary. Don't misunderstand me - I really like Debian and CentOS for my servers at work but sometimes I need fresh software
The only command in this guide that belongs to Arch Linux is pacman
, Other distributions may have slightly different pathes/filenames for configuration files. Look around a little bit and I'm sure you will find the correct path/filename in a very similar place.
About these instructions There are countless sources I used to create these instructions and a big step forward was issue #327 (closed). Unfortunately I found it after the most work was done ;-) My instructions works without any AUR-Packages. Just plain Arch Linux
At some points you will find some wired left-over DokuWiki markup for which I wrote this guide on my private DokuWiki first. Sorry for that I will work on that every time I find one.
@rosarior : I don't want to take away your customers with this guide. If you feel that it is too much in detail feel free to strip it down. On the other hand many parts of this guide should be in the main documentation. It would had helped me a lot.
ToDo
-
Add a link for official PostgreSQL installation -
Instructions for Apache2 Webserver -
Verify/rewrite the storage backend section. Provide the official way to change the storage location too.
History
- 23.Jan.2017 - First release
- 2.Feb.2017 - Added Apache2 section
- 20.Feb.2017 - Added systemd section. Thanks to @exioreed for contributing.
Here we go...
Install Mayan EDMS Document Management System [Arch Linux] and [Others]
Install Mayan-edms dependencies
pacman -S python2 python2-pip python2-magic python2-virtualenv libjpeg-turbo libpng libreoffice-fresh libreoffice-fresh-de libtiff rsync redis base-devel ghostscript gnupg tesseract tesseract tesseract-data-eng tesseract-data-deu poppler poppler-data mariadb
Which will lead into a bunch of dependencies. Just select the default everwhere and install. Note: You always need tesseract-data-eng. Even for non-english systems or configurations.
:: There are 25 members in group base-devel:
:: Repository core
1) autoconf 2) automake 3) binutils 4) bison 5) fakeroot 6) file 7) findutils 8) flex 9) gawk 10) gcc 11) gettext
12) grep 13) groff 14) gzip 15) libtool 16) m4 17) make 18) pacman 19) patch 20) pkg-config 21) sed 22) sudo 23) texinfo
24) util-linux 25) which
Enter a selection (default=all):
resolving dependencies...
looking for conflicting packages...
warning: dependency cycle detected:
warning: harfbuzz will be installed before its freetype2 dependency
Packages (151) atk-2.22+1+gd57f97d-1 avahi-0.6.32-3 boost-libs-1.63.0-1 cairo-1.14.8-1 clucene-2.3.3.4-9 compositeproto-0.4.2-3
...
tesseract-data-deu-3.04.00-1 texinfo-6.3-1 util-linux-2.29-2 which-2.21-2
Total Download Size: 229.80 MiB
Total Installed Size: 1248.19 MiB
Net Upgrade Size: 1066.28 MiB
:: Proceed with installation? [Y/n]
Configure MariaDB (MySQL)
Note: In case you want to use the official PostgreSQL installation method head over to the official deplyment guide.
Install mariadb, afterwards run the following command //before starting// the mariadb.service:
mysql_install_db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
systemctl enable mariadb
Now configure MariaDB. Edit mcedit /etc/mysql/my.cnf
and uncomment the line # skip-networking
which grants usage on localhost only.
Then add the lines to the [mysqld] section:
#Use UTF-8
init_connect = 'SET collation_connection = utf8_general_ci,NAMES utf8'
collation_server = utf8_general_ci
character_set_client = utf8
character_set_server = utf8
Now start the database with systemctl start mariadb
Create a Database and User, grant permissions
mysql -u root -p
Enter password:
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MariaDB connection id is 3
Server version: 10.1.20-MariaDB
...
MariaDB [(none)]> create database mayan_edms;
Query OK, 1 row affected (0.00 sec)
MariaDB [(none)]> create user mayan@localhost identified by 'YOUR_SQL_DATABASE_PASSWORD';
Query OK, 0 rows affected (0.00 sec)
MariaDB [(none)]> grant all privileges on mayan_edms.* to mayan@localhost;
Query OK, 0 rows affected (0.00 sec)
MariaDB [(none)]> flush privileges;
Query OK, 0 rows affected (0.00 sec)
MariaDB [(none)]> quit
Bye
Install and enable redis server
Enable and start the redis server
pacman -S redis
systemctl enable redis
systemctl start redis
Install mayan-edms
First at all install the wonderful fish shell. I love it!
pacman -S fish
chsh -s /usr/bin/fish
If you don't like the fish shell or love your zsh or bash it's ok - use your own shell.
Go to /usr/share and initialize the Python virtual environment.
cd /usr/share
virtualenv2 mayan-edms
and activate it (assuming using fish shell)
source mayan-edms/bin/activate.fish
In case you are using bash as the shell just use source mayan-edms/bin/activate
instead.
mayan-edms.py and pip
Whenever you want to install any pip
package in this guide or want to
run any mayan-edms.py
command always do this inside the virtualenv2 environment!
Whenever you see (mayan-edms) pip
or (mayan-edms) mayan-edms.py
in this guide you need to run
cd /usr/share/mayan-edms
source mayan-edms/bin/activate.fish
at least once before!
[[ Install Mayan EDMS from PyPihttps://mayan.readthedocs.io/en/latest/topics/faq.html]]
Does Mayan EDMS work with Python 3?
Not at the moment. When all the projects and libraries upon which Mayan is dependent support Python 3 then will the project move to fully support Python 3.
(mayan-edms) pip2 install mayan-edms
This will install a bunch of additional dependencies, such as Django, Pillow, PyYAML and a lot of other pip packages.
Install Redis and uWSGI
(mayan-edms) pip2 install redis uwsgi MySQL-python
Prepare...
(mayan-edms) mkdir /var/log/mayan
(mayan-edms) cd mayan-edms/
(mayan-edms) ln -s lib/python2.7/site-packages/mayan .
(mayan-edms) mayan-edms.py createsettings
Now edit the settings file mcedit mayan/settings/local.py
and add
/usr/share/mayan-edms/mayan/settings/local.py
#DEBUG = True
#TEMPLATE_DEBUG = DEBUG
ALLOWED_HOSTS = ['*']
BROKER_URL = 'redis://127.0.0.1:6379/0'
CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/0'
SIGNATURES_GPG_PATH = '/usr/bin/gpg2'
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'mayan_edms',
'USER': 'mayan',
'PASSWORD': 'SECRET-SQL-PASSWORD',
'HOST': 'localhost',
'PORT': '3306'
}
}
For all possible settings refer to: https://docs.djangoproject.com/en/dev/ref/settings/
Initialize the database
Now initialize the mayan database
(mayan-edms) mayan-edms.py initialsetup
common.apps <5343> [DEBUG] "ready() App mimetype doesn't have URLs defined. Exception: No module named urls"
common.apps <5343> [DEBUG] "ready() App navigation doesn't have URLs defined. Exception: No module named urls"
smart_settings.classes <5343> [DEBUG] "initialize() App appearance has no settings.py file"
...
Applying tags.0003_remove_tag_color... OK
Applying tags.0004_auto_20150717_2336... OK
Applying tags.0005_auto_20150718_0616... OK
Applying tags.0006_documenttag... OK
autoadmin.models <5343> [INFO] "create_autoadmin() Creating superuser -- login: admin, email: autoadmin@example.com, password: AmTmhP8U7c"
Superuser created successfully.
Please write down the automatically created admin account above!
You may test mayan running the build-in mini-web-server now with
(mayan-edms) mayan-edms.py runserver
and connect to http://127.0.0.1:8000
.
mayan-edms.py runserver IP-ADDRESS-TO-LISTEN-ON:PORT
Note that this is for testing only! Tasks, and scheduled tasks will not run in test-mode!
Install a Web-server (Apache or Nginx)
You need to decide which web-server you want to use. This guide will provide information for the most common ones, Apache and Nginx. Both works, both have their pro's and con's you need to decide.
vHost or Sub-URI
Decide if you want to install Mayan in a vHost or in a Sub-URI. What's the difference, what are the pro's and con's?
The difference between vHost and Sub-URL
vHost | Sub-URI | |
---|---|---|
URI | http://DOMAIN.TLD/ | http://DOMAIN.TLD/mayan |
Pro's and Con's
Pro's using vHost
- Easier to remember URI
- Slightly easier to setup
- Less places to modify (Does this really count? You need to touch the files anyway)
Con's using vHost
- Needs a dedicated IP-Address (if using a certificate)
- Needs an own certificate
- Cannot be integrated into a an existing site
Nginx webserver
pacman -S nginx
Configure nginx
Edit mcedit /etc/nginx/nginx.conf
and:
Uncomment line #user html
and change to user http
Uncomment line #error_log logs/error.log;
and change to error_log /var/log/nginx/error.log;
if you want error log.
Configure as vHost for nginx
The URL to access mayan-edms would be http://DOMAIN.TLD/
In group server
add
location / {
include uwsgi_params;
uwsgi_pass unix:/usr/share/mayan-edms/uwsgi.sock;
client_max_body_size 50M; # Increase if your plan to upload bigger documents
proxy_read_timeout 60s; # Increase if your document uploads take more than 30 seconds
}
location /mayan-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;
}
Edit /usr/share/mayan-edms/mayan/settings/local.py
and comment out or delete these lines
USE_X_FORWARDED_HOST = True
FORCE_SCRIPT_NAME = '/mayan' # https://docs.djangoproject.com/en/1.10/ref/settings/#force-script-name
BASE_PATH = '/mayan'
STATIC_URL = '/mayan-static/' # https://docs.djangoproject.com/en/1.10/ref/settings/#static-url
MEDIA_URL = BASE_PATH + '/media/' # https://docs.djangoproject.com/en/1.10/ref/settings/#media-url
Configure as Sub-URI for nginx
The URL to access mayan-edms would be http://DOMAIN.TLD/mayan
In group server
add
location /mayan {
include uwsgi_params;
uwsgi_pass unix:/usr/share/mayan-edms/uwsgi.sock;
# For use with a Sub-URI uncomment 'uwsgi_modifier' and 'uwsgi_param' + supply URI-Path. Don't forget to configure /mayan/settings/local.py too
uwsgi_param SCRIPT_NAME /mayan;
uwsgi_modifier1 30;
client_max_body_size 50M; # Increase if your plan to upload bigger documents
proxy_read_timeout 60s; # Increase if your document uploads take more than 30 seconds
}
location /mayan-static {
alias /usr/share/mayan-edms/mayan/media/static;
expires 1h;
}
location /mayan/favicon.ico {
alias /usr/share/mayan-edms/mayan/media/static/appearance/images/favicon.ico;
expires 1h;
}
Edit /usr/share/mayan-edms/mayan/settings/local.py
and add
USE_X_FORWARDED_HOST = True
FORCE_SCRIPT_NAME = '/mayan' # https://docs.djangoproject.com/en/1.10/ref/settings/#force-script-name
BASE_PATH = '/mayan'
STATIC_URL = '/mayan-static/' # https://docs.djangoproject.com/en/1.10/ref/settings/#static-url
MEDIA_URL = BASE_PATH + '/media/' # https://docs.djangoproject.com/en/1.10/ref/settings/#media-url
Restart ngnix
systemctl restart nginx
Apache2
pacman -S apache2 mod_proxy_uwsgi
Configure apache
Edit mcedit /etc/httpd/conf/httpd.conf
Uncomment the lines
LoadModule mpm_prefork_module modules/mod_mpm_prefork.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/mod_proxy.so
and add
LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so
to the end of the LoadModule block.
Configure as vHost for apache
Edit mcedit /etc/httpd/conf/httpd.conf
and uncomment the line Include conf/extra/httpd-vhosts.conf
.
Debian/Ubuntu is slightly different in place but very similar. Please search your distributions documentation for enabling vHosts for apache.
Now edit mcedit /etc/httpd/conf/extra/httpd-vhosts.conf
<VirtualHost *:80>
ServerAdmin webmaster@dummy-host.example.com
DocumentRoot "/srv/http/dummy-host.example.com"
ServerName dummy-host.example.com
ServerAlias www.dummy-host.example.com
ErrorLog "/var/log/httpd/dummy-host.example.com-error_log"
CustomLog "/var/log/httpd/dummy-host.example.com-access_log" common
ProxyPass /mayan unix:/usr/share/mayan-edms/uwsgi.sock|uwsgi://mayan/
<Directory "/mayan">
Options FollowSymLinks Indexes
SetHandler uwsgi-handler
</Directory>
Alias "/mayan-static" "/usr/share/mayan-edms/mayan/media/static/"
<Location "/mayan-static">
#Options Indexes
SetHandler None
Require all granted
</Location>
Alias /favicon.ico /usr/share/mayan-edms/mayan/media/static/appearance/images/favicon.ico
</VirtualHost>
Edit /usr/share/mayan-edms/mayan/settings/local.py
and comment out or delete these lines
USE_X_FORWARDED_HOST = True
FORCE_SCRIPT_NAME = '/mayan' # https://docs.djangoproject.com/en/1.10/ref/settings/#force-script-name
BASE_PATH = '/mayan'
STATIC_URL = '/mayan-static/' # https://docs.djangoproject.com/en/1.10/ref/settings/#static-url
MEDIA_URL = BASE_PATH + '/media/' # https://docs.djangoproject.com/en/1.10/ref/settings/#media-url
Configure as Sub-URI for apache
Edit mcedit /etc/httpd/conf/httpd.conf
and add the following below the main <Directory>
block
DocumentRoot "/srv/http"
<Directory "/srv/http">
...
</Directory>
ProxyPass /mayan unix:/usr/share/mayan-edms/uwsgi.sock|uwsgi://mayan/
<Directory "/mayan">
Options FollowSymLinks Indexes
SetHandler uwsgi-handler
</Directory>
Alias "/mayan-static" "/usr/share/mayan-edms/mayan/media/static/"
<Location "/mayan-static">
#Options Indexes
SetHandler None
Require all granted
</Location>
Alias /favicon.ico /usr/share/mayan-edms/mayan/media/static/appearance/images/favicon.ico
Edit /usr/share/mayan-edms/mayan/settings/local.py
and comment out or delete these lines
USE_X_FORWARDED_HOST = True
FORCE_SCRIPT_NAME = '/mayan' # https://docs.djangoproject.com/en/1.10/ref/settings/#force-script-name
BASE_PATH = '/mayan'
STATIC_URL = '/mayan-static/' # https://docs.djangoproject.com/en/1.10/ref/settings/#static-url
MEDIA_URL = BASE_PATH + '/media/' # https://docs.djangoproject.com/en/1.10/ref/settings/#media-url
Restart apache
systemctl restart httpd
Configure uWSGI
Create the uWSGI init file with mcedit /usr/share/mayan-edms/uwsgi.ini
Note When using systemd you need to comment out the logto
line.
# logto = /var/log/uwsgi/%n.log
/usr/share/mayan-edms/uwsgi.ini
[uwsgi]
chdir = /usr/share/mayan-edms/lib/python2.7/site-packages/mayan
chmod-socket = 664
chown-socket = http:http
env = DJANGO_SETTINGS_MODULE=mayan.settings.production
uid = http
gid = http
logto = /var/log/uwsgi/%n.log
pythonpath = /usr/share/mayan-edms/lib/python2.7/site-packages
pyhome = /usr/share/mayan-edms
home = /usr/share/mayan-edms
master = True
max-requests = 5000
socket = /usr/share/mayan-edms/uwsgi.sock
vacuum = True
wsgi-file = /usr/share/mayan-edms/lib/python2.7/site-packages/mayan/wsgi.py
Create a uWSGI logging directory mkdir /var/log/uwsgi
Configure your service manager
As always on Unix systems you have the choice to choose your favorite service manager. While the Mayan documentation mentions supervisor (which is a good choice although) most modern distributions are using systemd these days. To make it short: If your distribution us using systemd already don't waste time with supervisor. Use systemd. Head over to the Create the systemd services section below.
When your distribution is not using systemd use supervisor or write your own startup scripts.
Install supervisor
pacman -S supervisor
Configure supervisor
Add the two configuration files for mayan.
mcedit /etc/supervisor.d/mayan-uwsgi.conf
/etc/supervisor.d/mayan-uwsgi.conf
[program:mayan-uwsgi]
command = /usr/share/mayan-edms/bin/uwsgi --ini /usr/share/mayan-edms/uwsgi.ini
environment="PATH=/usr/share/mayan-edms/bin:%(ENV_PATH)s"
user = root
autostart = true
autorestart = true
redirect_stderr = true
startsecs = 10
stopwaitsecs = 15
/etc/supervisor.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
environment="PATH=/usr/share/mayan-edms/bin:%(ENV_PATH)s"
user = http
stdout_logfile = /var/log/mayan/worker-stdout.log
stderr_logfile = /var/log/mayan/worker-stderr.log
autostart = true
autorestart = true
startsecs = 30
stopwaitsecs = 30
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
environment="PATH=/usr/share/mayan-edms/bin:%(ENV_PATH)s"
user = http
numprocs = 1
stdout_logfile = /var/log/mayan/beat-stdout.log
stderr_logfile = /var/log/mayan/beat-stderr.log
autostart = true
autorestart = true
startsecs = 30
stopwaitsecs = 5
killasgroup = true
priority = 998
environment=PATH="/usr/share/mayan-edms/bin"
is required because celery would run outside the virtualenv2 environment. Since virtualenv2 just sets the correct path through the activate script I will do the same for supervisord.
Test mayan <--> supervisor
To test uwsgi (ngnix <--> django reverse proxy) run
/usr/share/mayan-edms/bin/uwsgi --ini /usr/share/mayan-edms/uwsgi.ini
and open the Mayan-URL in a browser.
See: /etc/supervisor.d/mayan-uwsgi.ini
To test celery-worker (the mayan task scheduler/queue) within the virtualenv2 environment run
/usr/share/mayan-edms/bin/python /usr/share/mayan-edms/bin/mayan-edms.py celery --settings=mayan.settings.production worker -Ofair -l ERROR
-------------- celery@pi v3.1.19 (Cipater)
---- **** -----
--- * *** * -- Linux-3.10.103-2-ARCH-armv7l-with-glibc2.4
-- * - **** ---
- ** ---------- [config]
- ** ---------- .> app: mayan:0xb5b49e90
- ** ---------- .> transport: redis://127.0.0.1:6379/0
- ** ---------- .> results: redis://127.0.0.1:6379/0
- *** --- * --- .> concurrency: 8 (prefork)
-- ******* ----
--- ***** ----- [queues]
-------------- .> checkouts_periodic exchange=checkouts_periodic(direct) key=checkouts_periodic
.> common_periodic exchange=common_periodic(direct) key=common_periodic
.> converter exchange=converter(direct) key=converter
.> default exchange=default(direct) key=default
.> documents_periodic exchange=documents_periodic(direct) key=documents_periodic
.> indexing exchange=indexing(direct) key=indexing
.> mailing exchange=mailing(direct) key=mailing
.> metadata exchange=metadata(direct) key=metadata
.> ocr exchange=ocr(direct) key=ocr
.> signatures exchange=signatures(direct) key=signatures
.> sources exchange=sources(direct) key=sources
.> sources_periodic exchange=sources_periodic(direct) key=sources_periodic
.> statistics exchange=statistics(direct) key=statistics
.> tools exchange=tools(direct) key=tools
.> uploads exchange=uploads(direct) key=uploads
documents.managers <14892> [INFO] "check_delete_periods() Executing"
[2017-01-19 07:08:17,092: INFO/Worker-5] Executing
documents.managers <14894> [INFO] "check_trash_periods() Executing"
Test celery-beat
To test celery-beat (the mayan task scheduler/queue) within the virtualenv2 environment run
/usr/share/mayan-edms/bin/python /usr/share/mayan-edms/bin/mayan-edms.py celery --settings=mayan.settings.production beat -l ERROR
__ - ... __ - _
Configuration ->
. broker -> redis://127.0.0.1:6379/0
. loader -> celery.loaders.app.AppLoader
. scheduler -> djcelery.schedulers.DatabaseScheduler
. logfile -> [stderr]@%ERROR
. maxinterval -> now (0s)
If starting supervisord fails, try to increase startsecs = 30
and stopwaitsecs = 30
in file /etc/supervisor.d/mayan-celery.ini
. Especially on slow machines like the raspi. I run mayan-edms on a Odroid-XU4 Octacore with 2GB RAM and it takes up to 30 seconds to initialize mayan-edms and all the dependencies. So be patient. It is not as fast as dedicated server but takes just about 4.5 watts at 100% load and about 1.7 watts when idle (with the USB3 HDD idle). Try to beat this with a standalone server for home use ;-)
Troubleshooting supervisord
To troubleshoot supervisord stop the daemon systemctl stop supervisord
and run it again in foreground. supervisord -n
Enable and start supervisor
systemctl enable supervisord
systemctl start supervisord
Create the systemd services
Thanks to user @exioreed who originally provided the systemd.service files.
With the current configuration the celery worker and beat are started together with uwsgi if launched via systemctl start mayan-edms.service
(see Wants=
dependencies in mayan-edms.service
). If uwsgi gets restarted or stopped by systemd the corresponding action is propagated to the worker and beat as well (see PartOf=
in mayan-worker.service
and mayan-beat.service
).
If e.g. nginx, mysql or redis-server should be started with uwsgi as well, they could be added to the Wants=
option.
Please also note that the services will log to journal (accessible via journalctl
) instead of /var/log/mayan/
.
For uwsgi this also depends on the logto
option in uwsgi.ini
which needs to be removed if logging to journal is intended.
Edit the uWSGI init file /usr/share/mayan-edms/uwsgi.ini
and comment out the logto
line.
# logto = /var/log/uwsgi/%n.log
Create the three following files in /etc/systemd/system directory
/etc/systemd/system/mayan-edms.service
### /etc/systemd/system/mayan-edms.service
[Unit]
Description=Document management system
Wants=mayan-worker.service mayan-beat.service
[Service]
Type=notify
NotifyAccess=all
ExecStart=/usr/share/mayan-edms/bin/uwsgi --ini /usr/share/mayan-edms/uwsgi.ini
KillSignal=SIGQUIT
WorkingDirectory=/usr/share/mayan-edms
User=http
Group=http
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
/etc/systemd/system/mayan-worker.service
### /etc/systemd/system/mayan-worker.service
[Unit]
Description=Celery worker for Mayan EDMS
PartOf=mayan-edms.service
[Service]
ExecStart=/usr/share/mayan-edms/bin/python /usr/share/mayan-edms/bin/mayan-edms.py celery --settings=mayan.settings.production worker -Ofair -l ERROR
WorkingDirectory=/usr/share/mayan-edms
Environment="PATH=/usr/share/mayan-edms/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
User=http
Group=http
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
/etc/systemd/system/mayan-beat.service
### /etc/systemd/system/mayan-beat.service
[Unit]
Description=Celery beat for Mayan EDMS
PartOf=mayan-edms.service
[Service]
ExecStart=/usr/share/mayan-edms/bin/python /usr/share/mayan-edms/bin/mayan-edms.py celery --settings=mayan.settings.production beat -l ERROR
WorkingDirectory=/usr/share/mayan-edms
Environment="PATH=/usr/share/mayan-edms/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
User=http
Group=http
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
Now enable the with...
systemctl enable mayan-edms.service
systemctl enable mayan-worker.service
systemctl enable mayan-beat.service
... and start it with systemctl start mayan-edms
Finalize the installation
(mayan-edms) mayan-edms.py collectstatic --noinput
chown -R http:http /usr/share/mayan-edms
systemctl restart nginx supervisord
Configure Mayan EDMS
Now that Mayan is installed you need to configure some aspects of Mayan.
Most of the configuration needs to be configured in /usr/share/mayan-edms/mayan/settings/local.py
Follow the [[http://mayan.readthedocs.io/en/latest/topics/settings.html|Mayan Settings link]] to learn anything about it.
Change the data storage path
First of all the location of stored documents. Running Mayan on an raspi/sdcard isn't a good place to store documents uploaded to Mayan. So let's change it to the hard disk.
mkdir /mnt/hdd/Mayan-EDMS-media
mv /usr/share/mayan-edms/mayan/media/document_* /mnt/hdd/Mayan-EDMS-media/
ln -s /mnt/hdd/Mayan-EDMS-media/document_cache /usr/share/mayan-edms/mayan/media/document_cache
ln -s /mnt/hdd/Mayan-EDMS-media/document_storage /usr/share/mayan-edms/mayan/media/document_storage
chown -R http:http /mnt/hdd/mayan-edms-media
chown -R http:http /usr/share/mayan-edms
Change the (long) list of available languages
/usr/share/mayan-edms/mayan/settings/local.py
#Reduce the list of possible languages for OCR and set the default language
DOCUMENTS_LANGUAGE_CHOICES = (('ger', 'German'), ('eng', 'English'))
DOCUMENTS_LANGUAGE = 'ger'
Configure Mayan to send EMails
Configure outgoing mails
/usr/share/mayan-edms/mayan/settings/local.py
#Configure your outgoing email provider
EMAIL_HOST = 'smtp.gmail.com' # Or similar
EMAIL_PORT = 587
EMAIL_HOST_USER = '<your smtp username>'
EMAIL_HOST_PASSWORD = '<your smtp password>'
EMAIL_USE_TLS = True
Configure incoming mails
To configure incoming mails logon into the mayan-WebUI 'admin->Setup->Sources' and add an new IMAP/POP3 source.
Logrotate
Logfile will grow in time. Some of them a lot. So it is wise to let logrotate handle them.
If not already installed (it comes by default often) install logrotate with pacman -S logrotate
Create the following files in /etc/logrotate.d/
/etc/logrotate.d/mayan
/var/log/mayan/*.log {
missingok
weekly
notifempty
compress
}
/etc/logrotate.d/supervisor
/var/log/supervisor/*.log {
missingok
weekly
notifempty
compress
}
/etc/logrotate.d/uwsgi
/var/log/uwsgi/*.log {
missingok
weekly
notifempty
compress
}
Backup Mayan-EDMS installation and data
No need to say: Backup often, backup regularly, backup everything and test the backup! Oh, I forgot: Backup these instructions too!
Backup the database
To backup the MariaDB Database just do
mysqldump -u root -p mayan_edms > MAYAN_EDMS.sql
Backup Mayan installtion without data
tar --exclude='**/mayan/media/document_*' -cjvf /BACKUP/mayan-installation.tbz /usr/share/mayan-edms
Backup Mayan Data (Documents)
tar --exclude='**/mayan/media/static*' -cjvhf /mnt/hdd/mayan-data.tbz /usr/share/mayan-edms/mayan/media/
Automate the backup
Put the above into cronjobs or systemd timers to automate the backup.
Update Mayan-EDMS
Updating Mayan is quite easy. But remember to make a backup first!
cd /usr/share/mayan-edms/
source bin/activate.fish
(mayan-edms) pip freeze > requirements.txt
(mayan-edms) pip install -r requirements.txt --upgrade
(mayan-edms) pip install --upgrade mayan-edms
(mayan-edms) bin/mayan-edms.py performupgrade
When the update has finished and you verified that everything is still working as expected remove the requirements.txt
. Don't remove this file before you verified everything! In case something gone wrong you may need it to revert back or identify the broken package.
(mayan-edms) rm requirements.txt
List of used files
This section is a collection of all configured/modified files to get Mayan up and running.
Logfiles used by the project
- /var/log/supervisord.log
- /var/log/supervisor/mayan-uwsgi-stdout---supervisor-*.log
- /var/log/uwsgi/uwsgi.log
- /var/log/mayan/beat-stderr.log
- /var/log/mayan/beat-stdout.log
- /var/log/mayan/worker-stderr.log
- /var/log/mayan/worker-stdout.log
- /var/log/ngnix/access.log
- /var/log/ngnix/error.log
Configuration files used by the project
/etc/supervisord.conf
; Sample supervisor config file.
[unix_http_server]
file=/run/supervisor.sock ; (the path to the socket file)
;chmod=0700 ; socked file mode (default 0700)
;chown=nobody:nogroup ; socket file uid:gid owner
;username=user ; (default is no username (open server))
;password=123 ; (default is no password (open server))
[inet_http_server] ; inet (TCP) server disabled by default
port=127.0.0.1:9001 ; (ip_address:port specifier, *:port for all iface)
;username=user ; (default is no username (open server))
;password=123 ; (default is no password (open server))
[supervisord]
logfile=/var/log/supervisord.log ; (main log file;default $CWD/supervisord.log)
;logfile_maxbytes=50MB ; (max main logfile bytes b4 rotation;default 50MB)
;logfile_backups=10 ; (num of main logfile rotation backups;default 10)
loglevel=info ; (log level;default info; others: debug,warn,trace)
pidfile=/run/supervisord.pid ; (supervisord pidfile;default supervisord.pid)
nodaemon=false ; (start in foreground if true;default false)
;minfds=1024 ; (min. avail startup file descriptors;default 1024)
;minprocs=200 ; (min. avail process descriptors;default 200)
;umask=022 ; (process file creation umask;default 022)
;user=chrism ; (default is current user, required if root)
;identifier=supervisor ; (supervisord identifier, default is 'supervisor')
;directory=/tmp ; (default is not to cd during start)
;nocleanup=true ; (don't clean up tempfiles at start;default false)
childlogdir=/var/log/supervisor ; ('AUTO' child log dir, default $TEMP)
;environment=KEY=value ; (key value pairs to add to environment)
;strip_ansi=false ; (strip ansi escape codes in logs; def. false)
; the below section must remain in the config file for RPC
; (supervisorctl/web interface) to work, additional interfaces may be
; added by defining them in separate rpcinterface: sections
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
[supervisorctl]
serverurl=unix:///run/supervisor.sock ; use a unix:// URL for a unix socket
;serverurl=http://127.0.0.1:9001 ; use an http:// url to specify an inet socket
;username=chris ; should be same as http_username if set
;password=123 ; should be same as http_password if set
;prompt=mysupervisor ; cmd line prompt (default "supervisor")
;history_file=~/.sc_history ; use readline history if available
; The below sample program section shows all possible program subsection values,
; create one or more 'real' program: sections to be able to control them under
; supervisor.
;[program:theprogramname]
;command=/bin/cat ; the program (relative uses PATH, can take args)
;process_name=%(program_name)s ; process_name expr (default %(program_name)s)
;numprocs=1 ; number of processes copies to start (def 1)
;directory=/tmp ; directory to cwd to before exec (def no cwd)
;umask=022 ; umask for process (default None)
;priority=999 ; the relative start priority (default 999)
;autostart=true ; start at supervisord start (default: true)
;autorestart=unexpected ; whether/when to restart (default: unexpected)
;startsecs=1 ; number of secs prog must stay running (def. 1)
;startretries=3 ; max # of serial start failures (default 3)
;exitcodes=0,2 ; 'expected' exit codes for process (default 0,2)
;stopsignal=QUIT ; signal used to kill process (default TERM)
;stopwaitsecs=10 ; max num secs to wait b4 SIGKILL (default 10)
;killasgroup=false ; SIGKILL the UNIX process group (def false)
;user=chrism ; setuid to this UNIX account to run the program
;redirect_stderr=true ; redirect proc stderr to stdout (default false)
;stdout_logfile=/a/path ; stdout log path, NONE for none; default AUTO
;stdout_logfile_maxbytes=1MB ; max # logfile bytes b4 rotation (default 50MB)
;stdout_logfile_backups=10 ; # of stdout logfile backups (default 10)
;stdout_capture_maxbytes=1MB ; number of bytes in 'capturemode' (default 0)
;stdout_events_enabled=false ; emit events on stdout writes (default false)
;stderr_logfile=/a/path ; stderr log path, NONE for none; default AUTO
;stderr_logfile_maxbytes=1MB ; max # logfile bytes b4 rotation (default 50MB)
;stderr_logfile_backups=10 ; # of stderr logfile backups (default 10)
;stderr_capture_maxbytes=1MB ; number of bytes in 'capturemode' (default 0)
;stderr_events_enabled=false ; emit events on stderr writes (default false)
;environment=A=1,B=2 ; process environment additions (def no adds)
;serverurl=AUTO ; override serverurl computation (childutils)
; The below sample eventlistener section shows all possible
; eventlistener subsection values, create one or more 'real'
; eventlistener: sections to be able to handle event notifications
; sent by supervisor.
;[eventlistener:theeventlistenername]
;command=/bin/eventlistener ; the program (relative uses PATH, can take args)
;process_name=%(program_name)s ; process_name expr (default %(program_name)s)
;numprocs=1 ; number of processes copies to start (def 1)
;events=EVENT ; event notif. types to subscribe to (req'd)
;buffer_size=10 ; event buffer queue size (default 10)
;directory=/tmp ; directory to cwd to before exec (def no cwd)
;umask=022 ; umask for process (default None)
;priority=-1 ; the relative start priority (default -1)
;autostart=true ; start at supervisord start (default: true)
;autorestart=unexpected ; whether/when to restart (default: unexpected)
;startsecs=1 ; number of secs prog must stay running (def. 1)
;startretries=3 ; max # of serial start failures (default 3)
;exitcodes=0,2 ; 'expected' exit codes for process (default 0,2)
;stopsignal=QUIT ; signal used to kill process (default TERM)
;stopwaitsecs=10 ; max num secs to wait b4 SIGKILL (default 10)
;killasgroup=false ; SIGKILL the UNIX process group (def false)
;user=chrism ; setuid to this UNIX account to run the program
;redirect_stderr=true ; redirect proc stderr to stdout (default false)
;stdout_logfile=/a/path ; stdout log path, NONE for none; default AUTO
;stdout_logfile_maxbytes=1MB ; max # logfile bytes b4 rotation (default 50MB)
;stdout_logfile_backups=10 ; # of stdout logfile backups (default 10)
;stdout_events_enabled=false ; emit events on stdout writes (default false)
;stderr_logfile=/a/path ; stderr log path, NONE for none; default AUTO
;stderr_logfile_maxbytes=1MB ; max # logfile bytes b4 rotation (default 50MB)
;stderr_logfile_backups ; # of stderr logfile backups (default 10)
;stderr_events_enabled=false ; emit events on stderr writes (default false)
;environment=A=1,B=2 ; process environment additions
;serverurl=AUTO ; override serverurl computation (childutils)
; The below sample group section shows all possible group values,
; create one or more 'real' group: sections to create "heterogeneous"
; process groups.
;[group:thegroupname]
;programs=progname1,progname2 ; each refers to 'x' in [program:x] definitions
;priority=999 ; the relative start priority (default 999)
; The [include] section can just contain the "files" setting. This
; setting can list multiple files (separated by whitespace or
; newlines). It can also contain wildcards. The filenames are
; interpreted as relative to this file. Included files *cannot*
; include files themselves.
[include]
files = /etc/supervisor.d/*.ini
/etc/supervisor.d/mayan-uwsgi.ini
[program:mayan-uwsgi]
command = /usr/share/mayan-edms/bin/uwsgi --ini /usr/share/mayan-edms/uwsgi.ini
environment=PATH="/usr/share/mayan-edms/bin"
user = root
autostart = true
autorestart = true
redirect_stderr = true
startsecs = 10
stopwaitsecs = 15
/etc/supervisor.d/mayan-celery.ini
[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
environment=PATH="/usr/share/mayan-edms/bin"
user = http
stdout_logfile = /var/log/mayan/worker-stdout.log
stderr_logfile = /var/log/mayan/worker-stderr.log
autostart = true
autorestart = true
startsecs = 50
stopwaitsecs = 30
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
environment=PATH="/usr/share/mayan-edms/bin"
user = http
numprocs = 1
stdout_logfile = /var/log/mayan/beat-stdout.log
stderr_logfile = /var/log/mayan/beat-stderr.log
autostart = true
autorestart = true
startsecs = 50
stopwaitsecs = 15
killasgroup = true
priority = 998
/usr/share/mayan-edms/uwsgi.ini
[uwsgi]
chdir = /usr/share/mayan-edms/lib/python2.7/site-packages/mayan
chmod-socket = 664
chown-socket = http:http
env = DJANGO_SETTINGS_MODULE=mayan.settings.production
uid = http
gid = http
logto = /var/log/uwsgi/%n.log
pythonpath = /usr/share/mayan-edms/lib/python2.7/site-packages
pyhome = /usr/share/mayan-edms
home = /usr/share/mayan-edms
master = True
max-requests = 5000
socket = /usr/share/mayan-edms/uwsgi.sock
vacuum = True
wsgi-file = /usr/share/mayan-edms/lib/python2.7/site-packages/mayan/wsgi.py
/usr/share/mayan-edms/mayan/settings/local.py
from __future__ import absolute_import
from __future__ import absolute_import
from .base import *
# DEBUG=True
# TEMPLATE_DEBUG = DEBUG
SECRET_KEY = 'A_KEY_RANDOMLY_GENERATED_AT_SETUP'
ALLOWED_HOSTS = ['*']
BROKER_URL = 'redis://127.0.0.1:6379/0'
CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/0'
SIGNATURES_GPG_PATH = '/usr/bin/gpg2'
# This depends on how you install mayan. vHost or Sub-URI. Need to configure nginx-conf too. "uwsgi_param SCRIPT_NAME /mayan;" "uwsgi_param SCRIPT_NAME /mayan;"
# USE_X_FORWARDED_HOST = True
# FORCE_SCRIPT_NAME = '/mayan' # https://docs.djangoproject.com/en/1.10/ref/settings/#force-script-name
# BASE_PATH = '/mayan'
# STATIC_URL = /mayan-static/' # https://docs.djangoproject.com/en/1.10/ref/settings/#static-url
# MEDIA_URL = BASE_PATH + '/media/' # https://docs.djangoproject.com/en/1.10/ref/settings/#media-url
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'mayan_edms',
'USER': 'mayan',
'PASSWORD': 'YOUR_DATABASE_PASSWORD',
'HOST': 'localhost',
'PORT': '3306'
}
}
#Configure your outgoing email provider
#EMAIL_HOST = 'smtp.gmail.com' # Or similar
#EMAIL_PORT = 587
#EMAIL_HOST_USER = '<your smtp username>'
#EMAIL_HOST_PASSWORD = '<your smtp password>'
#EMAIL_USE_TLS = True
#Reduce the list of possible languages for OCR and set the default language
DOCUMENTS_LANGUAGE_CHOICES = (('deu', 'Deutsch'), ('eng', 'English'))
DOCUMENTS_LANGUAGE = 'deu'
NGNIX config, running Mayan in a Sub-URI /etc/nginx/nginx.conf
user http;
worker_processes 1;
error_log /var/log/nginx/error.log;
#error_log logs/error.log notice;
#error_log logs/error.log info;
#pid logs/nginx.pid;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
#log_format main '$remote_addr - $remote_user [$time_local] "$request" '
# '$status $body_bytes_sent "$http_referer" '
# '"$http_user_agent" "$http_x_forwarded_for"';
#access_log logs/access.log main;
sendfile on;
#tcp_nopush on;
#keepalive_timeout 0;
keepalive_timeout 65;
#gzip on;
server {
listen 80;
server_name localhost;
#charset koi8-r;
#access_log logs/host.access.log main;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
}
# The following three are for mayan-edms
location /mayan {
include uwsgi_params;
uwsgi_pass unix:/usr/share/mayan-edms/uwsgi.sock;
uwsgi_param SCRIPT_NAME /mayan;
uwsgi_modifier1 30;
client_max_body_size 50M; # Increase if your plan to upload bigger documents
proxy_read_timeout 60s; # Increase if your document uploads take more than 30 seconds
}
location /mayan-static {
alias /usr/share/mayan-edms/mayan/media/static;
expires 1h;
}
location /mayan/favicon.ico {
alias /usr/share/mayan-edms/mayan/media/static/appearance/images/favicon.ico;
expires 1h;
}
error_page 404 /404.html;
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
}
# another virtual host using mix of IP-, name-, and port-based configuration
#
#server {
# listen 8000;
# listen somename:8080;
# server_name somename alias another.alias;
# location / {
# root html;
# index index.html index.htm;
# }
#}
# HTTPS server
#
#server {
# listen 443 ssl;
# server_name localhost;
# ssl_certificate cert.pem;
# ssl_certificate_key cert.key;
# ssl_session_cache shared:SSL:1m;
# ssl_session_timeout 5m;
# ssl_ciphers HIGH:!aNULL:!MD5;
# ssl_prefer_server_ciphers on;
# location / {
# root html;
# index index.html index.htm;
# }
#}
}
Further informations
A List of YouTube videos
- [[https://www.youtube.com/watch?v=PXw5vVf2n8g|Mayan EDMS Introduction]]
- [[https://www.youtube.com/watch?v=K5sUDXAMuxo|Version 2.1 new features highlight]]
- [[https://www.youtube.com/watch?v=q7pclEiren0|Indexes in Mayan EDMS]]
- [[https://www.youtube.com/watch?v=-YANl3xjodI|OCR in Mayan EDMS]]
- [[https://www.youtube.com/watch?v=OT3y9tCZJgs|EDMS Workflow]]
- [[https://www.youtube.com/watch?v=Hfa5EFjhWME|Document Classification]]
To learn about Mayan EDMS usage concepts and many more head over to the documentation
[[http://mayan.readthedocs.io/en/latest/|http://mayan.readthedocs.io/en/latest/]]
and especially the concepts