Manual Installation¶

Requirements¶

MAD requires the following things to be installed available on your server:

A server/computer running Linux. RaspberryPis do work, but aren’t recommended
A 64-bit CPU for MAD is also highly recommended since some optional parts of MAD do require to run on 64-bit. It does have a fallback for 32-bit CPUs though
MariaDB server
Python 3.9 or newer and Python’s package manager command line tool pip3.
Use a venv (virtualenv) to install dependencies. Have a look at this and this if you’re new to virtualenv

System preparation¶

Note

This whole article assumes a fresh installed Ubuntu 22.04 Server. If you’re running a more recent version of Ubuntu or another Linux distribution - that’s totally fine, but keep in mind there may be some difference in your setup.

First let’s install all the needed packages from Ubuntu repository - there will be more description later what they do, but for now let’s just install everything in one go to save time - if future apt install commands returns XXX is already the newest version then it’s good - we already have that one.

sudo apt update
sudo apt install mariadb-server default-libmysqlclient-dev mariadb-client python3-venv python3-pip python3-wheel python3-dev tesseract-ocr python3-opencv redis build-essential pkg-config

MariaDB¶

You need a Database with full permissions. That DB can be located on a different Server, but needs to be accessible by your MAD server.

If you are planning to use PMSF as a webfrontend: use at least MariaDB 10.2 or higher!

sudo apt install mariadb-server mariadb-client
sudo mysql_secure_installation

Log in to your Database and create a dedicated user for MAD. To create a new database and grant permissions for your dedicated MAD database user you must run the following command (make sure to change “my_database_user” and “password” to the correct values):

CREATE DATABASE my_database_name;
CREATE USER 'my_database_user'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON my_database_name.* TO 'my_database_user'@'localhost';
FLUSH PRIVILEGES;

Install client libraries¶

sudo apt install default-libmysqlclient-dev

Database schema¶

MAD will install the latest database schema automatically on initial boot and no additional steps are required. If you encounter any issues the base schema can be found here.

The up-to-date models used by MAD can viewed in mapadroid/db/model.py.

Python¶

Install additional python dependencies:

sudo apt install python3-pip python3-wheel python3-dev

Make sure you have the right version installed, since even if python3.9 is installed, the python3 command could still point to python3.5 or below! ls -lah $(which python3) will show the current symlink of Python

Check if pip and python is installed correctly by running:

python3 --version - should return 3.9.x or newer (3.10.X etc)
pip3 --version - If it returns a version that is related to your python version, it is working.

Virtual Environment¶

A virtual environment is a way to install python packages in a different location to avoid potential version conflicts with other software like RocketMAD or MADevice. It’s like a standalone version of python, independent of your “normal” python. Install it with:

sudo apt install python3-venv

MAD¶

MAD will also check the screen on your device every now and then to check for errors. Make sure you have the required dependencies installed on your system. Unfortunately, there’s no package for opencv on RaspberryPi which means you have to build it on your own. You should be able to find out how with a quick search on the web.

sudo apt install tesseract-ocr python3-opencv

Steps below should be run as normal, non-privileged user. It’s a bad practice to run everything as root (Administrator in Windows world). Create a new virtual environment called mad_env in your home directory:

python3 -m venv ~/mad_env

Whenever you see python3 or pip3 in the documentation, use ~/mad_env/bin/python3 and ~/mad_env/bin/pip3 instead. And, of course, use a different environment location for different python projects. For example if you are also using RocketMAD - have additional dedicated virtual environment for RocketMAD like ~/rm_env.

You can activate the virtual environment via source ~/mad_env/bin/activate. This makes sure you can simply call python3 or pip3 wherever you are and it will perform all commands with the Python version and the dependencies form your virtualenvironment. Have a look at this or this link for more information.

Next Step is to clone this repository and install all the required pip3 packages:

git clone https://github.com/Map-A-Droid/MAD.git

Change into in the directory of MAD and run:

pip3 install -r requirements.txt

Another but optional dependency you may want to install is ortools. MAD utilizes ortools to generate more optimized routes for your areas and it is as quick as MAD’s built-in routing algorithm if not even faster. The downside of this as states in the requirements is, that you need a 64-bit server.

pip3 install ortools

Configuration¶

Copy config.ini.example (from the configs folder in the MAD repo) to “config.ini” (also in the configs folder):

cp configs/config.ini.example configs/config.ini

and then edit the config file accordingly.

The next step is to configure MAD. This will only start MAD’s web frontend called MADmin.

Warning

MAD will not actually scan in configmode! The mode is for the first configuration only. Remove the -cm when you are done.

python3 start.py

By default MADmin will be available on http://your_server_ip:5000.

Running¶

If everything is set up correctly, you can start MAD:

python3 start.py

Further steps¶

Review and implement anything related to the security section.

Table Of Contents