Monica is a web app for managing your personal connections. The official website for the project describes it this way:
Monica helps you have more meaningful relationships.
Monica is a simple, open source, personal CRM. For your personal life, not your business.
The project looks very interesting, and it sparked a ton of interest on is official GitHub page. That’s right, because Monica, besides offering a hosted version (both with a free and a paid tier) also decided to make the code completely open source so you can install it and download it on your own server (which is something that is definitely going to be appreciated by a lot of folks, looking at the intrinsically personal data that Monica will store).
Unfortunately, at the time of writing this article, the instructions to install the app on your own server are either outdated or incomplete, making the installation process not very simple (also considering all the tools necessary to get it up and running). This article seeks to solve this issue with some step-by-step instructions.
Therefore, let’s install Monica on your Ubuntu 16.04 machine together.
Step 1 – Installing Apache
This is a simple step. We will need to install a web server for this project. Let’s start by updating the Ubuntu repositories so we can make sure to download the latest version of every package, Apache included.
sudo apt-get update
And now install Apache:
sudo apt-get install apache2
Step 2 – Installing MySQL
Monica needs a database to store your information. We are going to use MySQL, so let’s install it:
sudo apt-get install mysql-server mysql-client
We are installing the mysql-client too, as we will need to connect to this database to get it ready for installation later on.
Step 3 – Installing PHP 7.1
The latest version of Monica, at the time of writing, requires PHP version 7.1 and it will not work with previous PHP versions, not even with PHP 7.0.
Php 7.1, however, is not available in the official Ubuntu repositories, so we will have to add a repository specifically for this:
sudo add-apt-repository ppa:ondrej/php sudo apt-get update sudo apt-get install php7.1
Step 4 – Installing all of the other prerequisites
In addition to Apache, MySQL and PHP, which are typical for a web app to work, Monica requires some additional software and PHP extensions to work. You can install all of them with this single command:
sudo apt-get install curl git php7.1-cli php7.1-intl php7.1-simplexml php7.1-gd php7.1-mbstring php7.1-curl php7.1-zip php7.1-mysql
Step 5 – Installing composer
Finally, to install Monica, you will need one more tool: composer. The quickest way to install it is to use the official installer, which is a one-liner:
sudo curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
Step 6 – Configuring the database
Now that we have taken care of all the prerequisites, we can move on with the configuration of the MySQL database. First of all, connect to it using username root and the root password you chose when you installed the mysql-server package:
mysql -u root -p
Once logged in, create a new database specifically for Monica:
CREATE DATABASE monica;
Then create the database user that the app is going to use to connect to the database:
CREATE USER 'monica'@'localhost' IDENTIFIED BY ‘userpassword’;
Give this user permissions to do everything on the monica database:
GRANT ALL ON monica.<em> TO 'monica'@'localhost';
Finally, apply these privileges:
You can now exit the MySQL CLI and go back to your shell:
Step 7 – Installing Monica
We can now, finally, install Monica by cloning the official GitHub repository:
cd /var/www/html sudo git clone https://github.com/monicahq/monica.git
Let’s make sure that the apache www-data user can write to the project directory by making it the owner of the directory created by the previous command:
sudo chown -R www-data:www-data /var/www/html/monica
Now cd to the project directory and use composer to install Monica:
cd monica/ composer install
Note 1: do not run composer as root, run it as your non-root user
Note 2: go grab a coffee or something, as composer will take a good few minutes to install everything, but it will print out the progress status on stdout if you prefer to keep an eye on it.
At the end of the process, if everything completed successfully, you should see something like this in your terminal:
default: Discovered Package: intervention/image default: Discovered Package: jenssegers/date default: Discovered Package: laravel/cashier default: Discovered Package: laravel/passport default: Discovered Package: laravel/socialite default: Package manifest generated successfully. default: > IlluminateFoundationComposerScripts::postInstall default: > @php artisan optimize
Step 8 – Configuring Monica
The project configuration goes into a .env file in the main project directory. You should still be here from the previous step, so start by copying the default template:
sudo -u www-data cp .env.example .env
Now open this file with your favourite editor and make sure to change the following information at a minimum:
- Your database user
- Your database user password
- Your SMTP settings for email notifications
- Change the line APPDISABLESIGNUP=true to APPDISABLESIGNUP=false so you can actually create a new user on first launch, or the feature will be hidden and you will have no way to login
And now, onto the final configuration steps, which will be all automatic:
sudo -u www-data php artisan key:generate sudo -u www-data php artisan migrate sudo -u www-data php artisan storage:link sudo -u www-data php artisan db:seed --class ActivityTypesTableSeeder sudo -u www-data php artisan db:seed --class CountriesSeederTable sudo -u www-data php artisan passport:install
Step 9 – Configuring cron
Monica requires a cron script to run every minute to run correecly, so launch the cron editor with
And add this line at the end of it:
* * * * * sudo -u www-data /usr/bin/php /var/www/html/artisan schedule:run
Step 10 – Configuring Apache
Apache needs URL rewriting enabled so that Monica can work correctly, so let’s enable it:
sudo a2enmod rewrite
Now open the file
/etc/apache2/sites-enabled/000-default.conf and replace the root directory from
/var/www/html/monica/public so that the relevant section of the configuration file looks like this:
ServerAdmin webmaster@localhost DocumentRoot /var/www/html/monica/public
Now open the file
/etc/apache2/apache2.conf and look for the directory block for
/var/www/. Here, replace
/var/www/html/monica/ and, inside this code block, replace
AllowOverride None with
AllowOverride All, so that this section looks like this:
<Directory /> Options FollowSymLinks AllowOverride None Require all denied </Directory> <Directory /usr/share> AllowOverride None Require all granted </Directory> <Directory /var/www/html/monica/> Options Indexes FollowSymLinks AllowOverride All Require all granted </Directory>
Finally, restart Apache to apply the changes:
sudo systemctl restart apache2
Access Monica and create your user account
If everything has been installed and configured correctly, you will now be able to access Monica at your web server’s URL (http://localhost in my case, since all of this is running in a VM with a NAT network interface):
Click on the Sign up link and you will be brought to a page where you can create your Monica account:
Note: if you click on the account creation button without having configured your SMTP settings in the .env file, you will receive an error message:
This error page doesn’t tell us much about what might be happening, but if you enable debug mode in the .env file, you will see that this error message is indeed related to not having configured your SMTP settings (yes, I have checked for you ;) ).
In this case, it’s not a big problem because the account has been created successfully anyway. If you go back to the home page, you will be able to login with the credentials you have chosen and you will see the Monica dashboard:
From here, you are on your own and are free to play around with the software.
In this article I have tried to explain all the steps necessary to install the very promising Monica project. The installation process is not the simplest I have ever encountered, so I thought that having an article with step-by-step instructions to walk potential users through the installation process could be useful (especially because the official installation instructions at the time of writing are quite lacking).
While I was trying to get this to work, I have stumbled upon a bunch of issues myself, so if you run into something weird, please feel free to let me know in the comments below and I’ll do my best to help you out (but please note that I am in no way affiliated with the project so the official support channels might give you an overall better support experience).
I would also be very interested to know what you think about the Monica project itself. I personally think that the project has a ton of potential and could be extremely useful for some folks. As usual, the comments below are open for you.