Knowledgebase

Monica is an open source personal relationship management system. Think of it as a CRM (a popular tool used by sales teams in the corporate world) for your friends or family. Its source code is publicly hosted on GitHub. In this guide, we will go over the installation process of a Monica application.

Requirements

• FreeBSD 12 system
• Git
• PHP version 7.2 or greater with the following PHP extensions:
• json
• iconv
• intl
• opcache
• mbstring
• xml
• mysqli
• pdo_mysql
• bcmath
• curl
• gmp
• zip
• gd
• MariaDB
• Nginx
• Composer

Before you begin

Check the FreeBSD version.

uname -ro
# FreeBSD 12.0-RELEASE

Ensure that your FreeBSD system is up to date.

freebsd-update fetch install
pkg update && pkg upgrade -y

Install the necessary packages.

pkg install -y sudo vim unzip curl wget bash socat git libpng-dev

Create a new user account with your preferred username. We will use johndoe.

adduser

# Username: johndoe
# Full name: John Doe
# Uid (Leave empty for default): <Enter>
# Login group [johndoe]: <Enter>
# Login group is johndoe. Invite johndoe into other groups? []: wheel
# Login class [default]: <Enter>
# Shell (sh csh tcsh nologin) [sh]: bash
# Home directory [/home/johndoe]: <Enter>
# Home directory permissions (Leave empty for default): <Enter>
# Use password-based authentication? [yes]: <Enter>
# Use an empty password? (yes/no) [no]: <Enter>
# Use a random password? (yes/no) [no]: <Enter>
# Enter password: your_secure_password
# Enter password again: your_secure_password
# Lock out the account after creation? [no]: <Enter>
# OK? (yes/no): yes
# Add another user? (yes/no): no
# Goodbye!

Run the visudo command and uncomment the %wheel ALL=(ALL) ALL line, to allow members of the wheel group to execute any command.

visudo

# Uncomment by removing hash (#) sign
# %wheel ALL=(ALL) ALL

Now, switch to your newly created user with su.

su - johndoe

NOTE: Replace johndoe with your username.

Set up the timezone.

sudo tzsetup

Install PHP

Install PHP, as well as the necessary PHP extensions.

sudo pkg install -y php72 php72-mbstring php72-tokenizer php72-pdo php72-pdo_mysql php72-openssl php72-hash php72-json php72-phar php72-filter php72-zlib php72-dom php72-xml php72-xmlwriter php72-xmlreader php72-pecl-imagick php72-curl php72-session php72-ctype php72-iconv php72-gd php72-simplexml php72-zip php72-filter php72-tokenizer php72-calendar php72-fileinfo php72-intl php72-phar php72-soap php72-xmlrpc php72-opcache php72-mysqli php72-bcmath php72-gmp

Check the version.

php --version

# PHP 7.2.19 (cli) (built: Jun 20 2019 01:25:01) ( NTS )
# Copyright (c) 1997-2018 The PHP Group
# Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies

Soft-link php.ini-production to php.ini.

sudo ln -s /usr/local/etc/php.ini-production /usr/local/etc/php.ini

Enable and start PHP-FPM.

sudo sysrc php_fpm_enable=yes
sudo service php-fpm start

Install MariaDB and setup a database

Install MariaDB.

sudo pkg install -y mariadb102-client mariadb102-server

Check the version.

mysql --version
# mysql  Ver 15.1 Distrib 10.2.24-MariaDB, for FreeBSD12.0 (amd64) using readline 5.1

Start and enable MariaDB.

sudo sysrc mysql_enable="yes" 
sudo service mysql-server start

Run the mysql_secure_installation script to improve the security of your installation.

sudo mysql_secure_installation

Log into MariaDB as the root user.

mysql -u root -p
# Enter password:

Create a new database and user. Remember the credentials for this new user.

CREATE DATABASE dbname;
GRANT ALL ON dbname.* TO 'username' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;
exit;

Install and configure Nginx

Install Nginx.

sudo pkg install -y nginx

Check the version.

nginx -v
# nginx version: nginx/1.14.2

Enable and start Nginx.

sudo sysrc nginx_enable=yes
sudo service nginx start

Run sudo vim /usr/local/etc/nginx/monica.conf and set up Nginx for Monica.

server {

  listen 80;
  listen [::]:80;
  server_name example.com;
  root /usr/local/www/monica/public;

  index index.php;

  location / {
    try_files $uri $uri/ /index.php?$args;
  }

  location ~ \.php$ {
    try_files $uri =404;
    include fastcgi_params;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass 127.0.0.1:9000;
  }

}

Save the file and exit.

Now we need to include monica.conf in the main nginx.conf file.

Run sudo vim /usr/local/etc/nginx/nginx.conf and add the following line to the http {} block.

include monica.conf;

Test the configuration.

sudo nginx -t

Reload Nginx.

sudo service nginx reload

Install Composer

Install Composer globally.

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('SHA384', 'composer-setup.php') === '48e3236262b34d30969dca3c37281b3b4bbe3221bda826ac6a9a62d6444cdb0dcd0615698a5cbe587c3f0fe57a54d8f5') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

Check the version.

composer --version
# Composer version 1.8.6 2019-06-11 15:03:05

Install and configure Monica

Create an empty document root folder where Monica should be installed.

sudo mkdir -p /usr/local/www/monica

Navigate to the document root folder.

cd /usr/local/www/monica

Change ownership of /usr/local/www/monica folder to user johndoe.

sudo chown -R johndoe:johndoe /usr/local/www/monica

Clone the Monica repository to it.

git clone https://github.com/monicahq/monica.git .
git checkout tags/v2.14.0

NOTE: Find the latest official version on the releases page on GitHub and update the version number above to the latest release.

Run the following to create your own version of the environment variables needed for the project.

cp .env.example .env

Update the .env file to your specific needs. Don't forget to set DB_USERNAME and DB_PASSWORD with the settings used previously.

Install all the packages.

composer install --no-interaction --no-suggest --no-dev

Generate an application key. This will set APP_KEY to the correct value automatically.

php artisan key:generate

Run the migrations and seed the database and symlink folders.

php artisan setup:production -v

Change ownership of the /usr/local/www/monica directory to www.

 sudo chown -R www:www /usr/local/www/monica

The installation is complete. Open your domain in your web browser and follow the instructions shown on screen.