monica/docs/installation/providers/ubuntu.md

Installing Monica on Ubuntu

Monica can run on Ubuntu 18.04 (Bionic Beaver).

• Prerequisites
  • Types of databases
• Installation steps
  • 1. Clone the repository
  • 2. Setup the database
  • 3. Configure Monica
  • 4. Configure cron job
  • 5. Configure Apache webserver
  • Final step

Prerequisites

Monica depends on the following:

• Apache httpd webserver
• Git
• PHP 8.1+
• Composer
• Node.js
• Yarn
• MySQL

Apache: If it doesn't come pre-installed with your server, follow the instructions here to setup Apache and config the firewall.

Git: Git should come pre-installed with your server. If it's not, install it with:

sudo apt update
sudo apt install -y git

Apache: Apache should come pre-installed with your server. If it's not, install it with:

sudo apt update
sudo apt install -y apache2

PHP 8.1+:

First add this PPA repository:

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php

Then install php 8.1 with these extensions:

sudo apt update
sudo apt install -y php8.1 php8.1-bcmath php8.1-cli php8.1-curl php8.1-common \
    php8.1-fpm php8.1-gd php8.1-gmp php8.1-intl php8.1-json php8.1-mbstring \
    php8.1-mysql php8.1-opcache php8.1-redis php8.1-xml php8.1-zip

Composer: After you're done installing PHP, you'll need the Composer dependency manager.

cd /tmp
curl -s https://getcomposer.org/installer -o composer-setup.php
sudo php composer-setup.php --install-dir=/usr/local/bin/ --filename=composer
rm -f composer-setup.php

(or you can follow instruction on getcomposer.org page)

Node.js: Install node.js with package manager.

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs

Yarn: Install yarn with npm.

sudo npm install --global yarn

Mysql: Install Mysql 5.7. Note that this only installs the package, but does not setup Mysql. This is done later in the instructions:

sudo apt update
sudo apt install -y mysql-server

Types of databases

The official Monica installation uses Mysql as the database system and this is the only official system we support. While Laravel technically supports PostgreSQL and SQLite, we can't guarantee that it will work fine with Monica as we've never tested it. Feel free to read Laravel's documentation on that topic if you feel adventurous.

Installation steps

Once the softwares above are installed:

1. Clone the repository

You may install Monica by simply cloning the repository. In order for this to work with Apache, you need to clone the repository in a specific folder:

cd /var/www
git clone https://github.com/monicahq/monica.git

You should check out a tagged version of Monica since main branch may not always be stable. Find the latest official version on the release page:

cd /var/www/monica
# Get latest tags from GitHub
git fetch
# Clone the desired version
git checkout tags/v2.18.0

2. Setup the database

Log in with the root account to configure the database.

mysql -u root -p

Create a database called 'monica'.

CREATE DATABASE monica CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Create a user called 'monica' and its password 'strongpassword'.

CREATE USER 'monica'@'localhost' IDENTIFIED BY 'strongpassword';

We have to authorize the new user on the monica db so that he is allowed to change the database.

GRANT ALL ON monica.* TO 'monica'@'localhost';

And finally we apply the changes and exit the database.

FLUSH PRIVILEGES;
exit

3. Configure Monica

cd /var/www/monica then run these steps:

1. cp .env.example .env to create your own version of all the environment variables needed for the project to work.
2. Update .env to your specific needs
   • set DB_USERNAME and DB_PASSWORD with the settings used behind.
   • configure a mailserver for registration & reminders to work correctly.
   • set the APP_ENV variable to production, local is only used for the development version. Beware: setting APP_ENV to production will force HTTPS. Skip this if you're running Monica locally.
3. Run composer install --no-interaction --no-dev to install all packages.
4. Run yarn install to install frontend packages, then yarn run production to build the assets (js, css).
5. Run php artisan key:generate to generate an application key. This will set APP_KEY with the right value automatically.
6. Run php artisan setup:production -v to run the migrations, seed the database and symlink folders.
   • You can use email and password parameter to setup a first account directly: php artisan setup:production --email=your@email.com --password=yourpassword -v
7. Optional: Setup the queues with Redis, Beanstalk or Amazon SQS: see optional instruction of generic installation
8. Optional: Setup the access tokens to use the API follow optional instruction of generic installation

4. Configure cron job

Monica requires some background processes to continuously run. The list of things Monica does in the background is described here. Basically those crons are needed to send reminder emails and check if a new version is available. To do this, setup a cron that runs every minute that triggers the following command php artisan schedule:run.

Run the crontab command:

crontab -u www-data -e

Then, in the crontab editor window you just opened, paste the following at the end of the document:

* * * * * php /var/www/monica/artisan schedule:run >> /dev/null 2>&1

5. Configure Apache webserver

1. Give proper permissions to the project directory by running:

sudo chown -R www-data:www-data /var/www/monica
sudo chmod -R 775 /var/www/monica/storage

2. Enable the rewrite module of the Apache webserver:

sudo a2enmod rewrite

3. Configure a new monica site in apache by doing:

sudo nano /etc/apache2/sites-available/monica.conf

Then, in the nano text editor window you just opened, copy the following - swapping the **YOUR IP ADDRESS/DOMAIN** with your server's IP address/associated domain:

<VirtualHost *:80>
    ServerName **YOUR IP ADDRESS/DOMAIN**

    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/monica/public

    <Directory /var/www/monica/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

4. Apply the new .conf file and restart Apache. You can do that by running:

sudo a2dissite 000-default.conf
sudo a2ensite monica.conf

# Enable php8.1 fpm, and restart apache
sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.1-fpm
sudo service php8.1-fpm restart
sudo service apache2 restart

Final step

The final step is to have fun with your newly created instance, which should be up and running to http://localhost.