MacOS is a Unix based operating system, so we have the capability to run it natively on MacOS as well. The steps however differ from our main deployment documentation in a number of ways, so we're sharing this here so people can install natively on MacOS
Important Note: If you are new to MacOS or the Linux command line then you may find it easier to use our Simple Docker Installation process. First you will need to install Docker for MacOS which will then allow you to run Linux containers inside of a Linux virtual machine on your Mac. It is a significantly easier process and much more in line with our officially supported methods. The guide below replicates the direct deployment instructions for MacOS allowing you to run Mayan EDMS natively on bare metal with no Virtualisation overhead.
Very Important Note: Although this process is known to work and has been validated by myself (and hopefully other forum members also), MacOS is NOT an officially supported platform for running Mayan EDMS. If you run into production issues and log a Gitlab Issue we cannot guarantee that it will be resolved or that we will help you in a timely fashion. I do not recommend this for production enterprise deployments.
If you are an Enterprise that uses MacOS Server and wish to use it to host Mayan EDMS then please reach out to sales@mayan-edms.com where custom support/consulting packages can be discussed.
Why run on MacOS?
This is a very personal decision. A lot of us use MacOS as our daily driver so it would be nice to have the option of running Mayan EDMS on it for development/testing purposes. Macs also have some very nice hardware in them that can create a very responsive Mayan EDMS environment.
An old Mac Mini for example could be the perfect host for Mayan. Discreet; efficient and powerful.
But primarily; we look into running Mayan EDMS on MacOS because... we can!
Install on MacOS Catalina - Part 1
These instructions are based on MacOS Catalina but should also apply to older MacOS versions. There are some security features in newer MacOS that we work around later in the tutorial and where those do not apply to older MacOS versions it will be called out and you can skip that step.
All steps in this tutorial should be run as the user you're logged in as (E.G "rob"). Only run "sudo" or commands as root when directed to in the guide. Failing to follow this or trying to install as a separate non-login user will result in permissions issues
What are we going to install?
At the end of this tutorial you'll have installed and configured the following Mayan EDMS Architecture:
- Python 3.7
- Mayan EDMS 3.3.7 inside a virtualenv
- RabbitMQ
- Redis
- Postgresql 9.6
We're going to set it up as an "Advanced Direct Deployment" using RabbitMQ over Redis because MacOS machines are typically desktops or laptops and they shutdown/reboot a lot more than servers do. If we used Redis for Mayan's task queue we would loose all pending tasks upon a reboot.
It also means scaling up the environment later on is easy as you don't have to migrate to RabbitMQ then.
1. Install Homebrew
Homebrew is a package manager for MacOS. It allows us to install Linux and Mac applications on MacOS natively. You may have homebrew already set up. If you do not, load up a terminal window and run the following to install MacOS
Code: Select all
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Although MacOS has directories like /opt and /etc, MacOS security features prevent users (even root) from writing into them, so we have to use these "local" alternatives.
2. Install & Configure Python
MacOS comes with it's own version of Python. We want to avoid using that at all costs as it's usually not kept as up to date as the versions in homebrew. Managing everything in homebrew means we can update all dependencies at once.
Code: Select all
brew install python3
Any time you want to run python3 for Mayan EDMS we must use the full path to the /usr/local/bin/python3 binary otherwise we will use the system default python in error
We can now create our python3 virtual environment:
Code: Select all
cd /usr/local/opt
/usr/local/bin/python3 -m venv mayan-edms
3. Install & Configure Dependencies
First, let's install Postgres, Redis and RabbitMQ:
Code: Select all
brew install postgresql@9.6 redis rabbitmq
Code: Select all
echo "maxmemory-policy allkeys-lru" >> /usr/local/etc/redis.conf
echo "save \"\"" >> /usr/local/etc/redis.conf
echo "databases 2" >> /usr/local/etc/redis.conf
Code: Select all
brew services start rabbitmq
brew services start redis
brew services start postgresql@9.6
Now we need to configure RabbitMQ. We're going to remove the default insecure guest account, add an admin account that can access the web UI and add an account for Mayan to access RabbitMQ on a dedicated vhost.
If you want to change the passwords used feel free, but bear in mind you will have to update subsequent references in this tutorial also.
Code: Select all
rabbitmqctl delete_user guest
rabbitmqctl add_user admin youradminpassword
rabbitmqctl set_user_tags admin administrator
rabbitmqctl add_user mayan mayanrabbitmqpassword
rabbitmqctl add_vhost mayan
rabbitmqctl set_permissions -p mayan mayan ".*" ".*" ".*"
rabbitmqctl set_permissions -p mayan admin ".*" ".*" ".*"
Code: Select all
brew install exiftool gcc ghostscript tesseract gnupg graphviz libjpeg libmagic libpq libpng libtiff poppler sane-backends supervisor zlib lzlib
Code: Select all
brew cask install libreoffice
Code: Select all
brew cask install osxfuse
Code: Select all
ln -s /usr/local/bin/soffice /usr/local/bin/libreoffice
4. Install Mayan EDMS
Run the following to install Mayan. You may get some warnings in the console output about failure to build. This is okay as it will download precompiled versions for the dependencies it can't compile. If you get FAIL's, that's when you need to reply to this post for assistance.
Code: Select all
/usr/local/opt/mayan-edms/bin/pip install --no-use-pep517 mayan-edms
First run
Code: Select all
export CPPFLAGS="-I/usr/local/opt/openssl@1.1/include"
export LDFLAGS="-L/usr/local/opt/openssl@1.1/lib"
Then run
Code: Select all
/usr/local/opt/mayan-edms/bin/pip install --no-use-pep517 amqp==2.5.2 psycopg2==2.8.4 redis==3.3.11 psutil==5.6.2
Code: Select all
/usr/local/opt/postgresql@9.6/bin/psql postgres
Then run:
Code: Select all
CREATE USER mayan WITH password 'mayanuserpass';
\q
Then run:
Code: Select all
/usr/local/opt/postgresql@9.6/bin/createdb -O mayan mayan
5. Update literals (ONLY for Mayan 3.3.7 and below)
I submitted a patch to update Mayan to support the correct MacOS locations of certain dependencies (such as tesseract)
Until that is released with 3.3.8, you must update the following 3 files to add in Darwin as a supported OS.
Code: Select all
cd /usr/local/opt/mayan-edms/lib/python3.7/site-packages/mayan/apps
Code: Select all
vim ocr/backends/literals.py
from
Code: Select all
if platform.system() in ('FreeBSD', 'OpenBSD'):
Code: Select all
if platform.system() in ('FreeBSD', 'OpenBSD', 'Darwin'):
Code: Select all
vim ocr/file_metadata/literals.py
from
Code: Select all
if platform.system() in ('FreeBSD', 'OpenBSD'):
Code: Select all
if platform.system() in ('FreeBSD', 'OpenBSD', 'Darwin'):
Code: Select all
vim ocr/converter/literals.py
from
Code: Select all
if platform.system() in ('FreeBSD', 'OpenBSD'):
Code: Select all
if platform.system() in ('FreeBSD', 'OpenBSD', 'Darwin'):
6. Mayan EDMS Initial Setup
We're now ready to run the initialsetup command and prepare static commands for Mayan. If either of these fail, then something earlier in the process must have gone wrong and you should reply to this thread for assistance
Run the following:
Code: Select all
MAYAN_DATABASES="{'default':{'ENGINE':'django.db.backends.postgresql','NAME':'mayan','PASSWORD':'mayanuserpass','USER':'mayan','HOST':'127.0.0.1'}}" MAYAN_MEDIA_ROOT=/usr/local/opt/mayan-edms/media /usr/local/opt/mayan-edms/bin/mayan-edms.py initialsetup
Code: Select all
Installing package: Lato font ... Downloading... Extracting... Complete.
Superuser created successfully.
Next, we generate Mayans Static Media:
Code: Select all
MAYAN_MEDIA_ROOT=/usr/local/opt/mayan-edms/media \
/usr/local/opt/mayan-edms/bin/mayan-edms.py preparestatic --noinput
This concludes part one. We're not done just yet! - There's just a limit on the number of characters in a forum post so I'm going to continue it below in part 2: