MrDiderot/CRM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: replace custom CRM with Monica fork
Some checks failed
Build & Push Monica Image to Gitea Registry / build-and-push (push) Failing after 9s
Details

Browse Source
This commit is contained in:
Kroonk
2026-05-22 16:19:55 +02:00
parent 38cc4c09ca
commit a213a1dba0
2215 changed files with 242567 additions and 6015 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/installation/faq.md Normal file
View File

@@ -0,0 +1,6 @@
# Common problems FAQ
This document describes common errors/problems with a self hosted Monica installation.
## Q: What are the default user credentials?
A: Monica should open a browser after setup to create your first user. If this does not happen or during setup you see the output `Seeding: FakeUserTableSeeder` you possibly did forget to set `APP_ENV` within the `.env` file to value `production`

92
docs/installation/mail.md Normal file
View File

@@ -0,0 +1,92 @@
# Configuring a Mail Server <!-- omit in toc -->
- [Use SMTP with Monica](#use-smtp-with-monica)
- [Use Amazon SES with Monica](#use-amazon-ses-with-monica)
- [1. Obtain SES Credentials](#1-obtain-ses-credentials)
- [2. Verify the Address You'll be Sending From](#2-verify-the-address-youll-be-sending-from)
- [3. Allow SES to Send Emails Out](#3-allow-ses-to-send-emails-out)
- [4. Configure Monica to Use SES SMTP Server](#4-configure-monica-to-use-ses-smtp-server)
The Monica registration flow will send a validation email to the user who sent it. Whilst this is not required by default (see `APP_SIGNUP_DOUBLE_OPTIN` in your `.env` file), setting up a mail server is encouraged so that you can receive reminders.
For this, you will require an SMTP server. If you don't have one of these, your options include (but are not limited to):
* [Mailtrap](https://mailtrap.io/)
* [Postmark](https://postmarkapp.com/)
* [Mailgun](https://signup.mailgun.com/new/signup) (the [free plan](https://www.mailgun.com/pricing) should be sufficient)
* [Amazon Simple Email Service](https://aws.amazon.com/ses/)
* [Sendgrid](https://sendgrid.com)
## Use SMTP with Monica
The generic way to send emails with Monica is to provide a SMTP server, each one of the services mentioned above can provide you SMTP settings. While Amazon SES is a little bit custom, see bellow, here the configuration for a standard SMTP configuration.
You need to add few environment variables in your configuration (working in generic installation and Docker):
```
MAIL_MAILER: smtp
MAIL_HOST: smtp.service.com # ex: smtp.sendgrid.net
MAIL_PORT: 587 # is using tls, as you should
MAIL_USERNAME: my_service_username # ex: apikey
MAIL_PASSWORD: my_service_password # ex: SG.Psuoc6NZTrGHAF9fdsgsdgsbvjQ.JuxNWVYmJ8LE0
MAIL_ENCRYPTION: tls
MAIL_FROM_ADDRESS: no-reply@xxx.com # ex: email you want the email to be FROM
MAIL_FROM_NAME: Monica # ex: name of the sender
```
Restart Monica to take in effect the new settings, quickest option to confirm is to add someone to your account (add one of your own email) and you will receive the invitation!
## Use Amazon SES with Monica
Simple Email Service is a service provided through Amazon Web Services. This guide will assume that you have an [AWS Account](https://aws.amazon.com/) and have basic familiarity with the Management Console.
For more detailed information on SES, see the [Amazon SES Docs](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/choose-email-sending-method.html).
### 1. Obtain SES Credentials
The SES SMTP server will require Monica to authenticate with it. These are set through the `MAIL_USERNAME` and `MAIL_PASSWORD` fields in your `.env` file.
Go to the SES Console - and take note of which Region you're working in. You'll need this to configure the correct SMTP server later.
In the SES Console, go to "SMTP Settings", and select "Create My SMTP Credentials". This will take you into IAM (Identity and Access Management), which is where these credentials will be stored. The name is unimportant - just hit "Create".
### 2. Verify the Address You'll be Sending From
When using SES, you must verify that you own the email address that your email from Monica will appear to be from. This is the `MAIL_FROM_ADDRESS` in your `.env` file (Note that the `MAIL_FROM_NAME` can be whatever you like - and will be the "friendly name" that appears in your email client).
In the SES console, go to "Email Addresses" and "Verify a New Email Address". Follow that flow through until the "Verification Status" for your email shows up as "Verified".
### 3. Allow SES to Send Emails Out
SES does not, by default, allow you to send email to arbitrary addresses. If you're only planning on having a single user on your Monica Instance, with a single email address for notifications, you can simply Verify the Address you're planning on sending to, just like in Step 2 above.
If you're planning on having multiple users with unknown email addresses, you'll have to [move out of the SES Sandbox Environment](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html).
### 4. Configure Monica to Use SES SMTP Server
You now simply need to configure your `.env` file to use the SES SMTP server. Make sure you use the correct server for the Region where you've configured your email addresses, or this will not work!
```
# Mail credentials used to send emails from the application.
MAIL_MAILER=smtp
MAIL_HOST=email-smtp.us-east-1.amazonaws.com
MAIL_PORT=25
MAIL_USERNAME=<Step 1>
MAIL_PASSWORD=<Step 1>
MAIL_ENCRYPTION=tls
# Outgoing emails will be sent with these identity
MAIL_FROM_ADDRESS=<Step 2>
MAIL_FROM_NAME="Monica"
# New registration notification sent to this email
APP_EMAIL_NEW_USERS_NOTIFICATION=
```
Now you're all done! If you've changed your `.env` file since you last started Monica, use `php artisan setup:production -v` so that Monica reads your new configuration.

16
docs/installation/providers/cloudron.md Normal file
View File

@@ -0,0 +1,16 @@
# Installing Monica on Cloudron
Monica is available as a 1-click install on [Cloudron](https://cloudron.io). For those unaware,
Cloudron makes it easy to run web apps on your server and keep them up-to-date.
[![Install](https://cloudron.io/img/button.svg)](https://cloudron.io/button.html?app=com.monicahq.cloudronapp)
When you visit the app for the first time, you will be prompted to register a new account. Put in your email address
and password and you will be logged into the app. This is the only account that has access unless you invite other people.
There is a demo available at https://my.demo.cloudron.io (username: cloudron password: cloudron)
# Package source
The Cloudron package is developed [here](https://git.cloudron.io/cloudron/monica-app).

143
docs/installation/providers/cpanel.md Normal file
View File

@@ -0,0 +1,143 @@
# Installing Monica (cPanel Shared Hosting) <!-- omit in toc -->
- [Prerequisites](#prerequisites)
- [Installation steps](#installation-steps)
- [1. Download the repository](#1-download-the-repository)
- [2. Setup the database](#2-setup-the-database)
- [3. Configure Monica](#3-configure-monica)
- [4. Configure cron job](#4-configure-cron-job)
- [5. Configure cPanel webserver](#5-configure-cpanel-webserver)
- [Final step](#final-step)
## Prerequisites
Monica can be configured in shared hosting environments with a little differences that we can remedy easily. In this scenario, Monica depends on the following:
- A shared cPanel Server
- PHP 8.1+
- [Composer](https://getcomposer.org/)
- [MySQL](https://www.mysql.com/)
- SSH Access for an accont on the cPanel server
**Git:** Git should come pre-installed with your server. If it doesn't - use the installation instructions in the link.
**PHP:** Install php8.1 minimum. Generally cPanel will have a PHP 7 version installed, verify under the 'PHP Version' section from the cPanel section. Make sure these extensions are enabled:
- bcmath
- curl
- dom
- gd
- gmp
- iconv
- intl
- json
- mbstring
- mysqli
- opcache
- pdo_mysql
- redis
- sodium
- tokenizer
- xml
- zip
In most cases, this will be under the section called 'PHP Version' in cPanel where you can enable and disable modules.
**Composer:** After you're done installing PHP, you'll need the Composer dependency manager. Generally on most capable shared hosts, this is already installed. If it is not, please reference the below:
```sh
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin/ --filename=composer
php -r "unlink('composer-setup.php');"
```
**MySQL:** Almost every cPanel environment includes this by default, and this will be our desired DB
## Installation steps
Once the softwares above are installed:
### 1. Download the repository
You may install Monica by simply downloading the repository. You can download it by using the download button at the main repo page for Monica. Some people may want to use Git, and when you have properly logged into the cPanel server, issue the following commands:
```sh
cd /public_html/[subdomain you wish to install monica on]
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](https://github.com/monicahq/monica/releases).
```sh
cd /var/www/monica
# Get latest tags from GitHub
git fetch
# Clone the desired version
git checkout tags/v3.7.0
```
### 2. Setup the database
Use the cPanel database wizard to create a new database.
<ol>
<li>Search for 'Database Wizard' in the cPanel GUI. Click on that item. </li>
<li>Create a database name and click next. </li>
<li>Create a user name and password for the user to access the database. Click Next</li>
<li>Assign All Permissions to the user account.</li>
<li>Save the password to be referenced later</li>
### 3. Configure Monica
Open the cPanel file manager and navigate to the directory in which you want to install Monica. Then run these steps:
1. Duplicate `.env.example` to a file called `.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 above.
- DO NOT set a database prefix, as you will overrun the limit of table and constraint names.
- configure a [mailserver](/docs/installation/mail.md) for registration & reminders to work correctly. Generally you can configure a SMTP account within cPanel and be fine.
- 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. Log into the cPanel server via SSH and navigate to the directory in which you want to install Monica.
4. Run `composer install --no-interaction --no-dev` to install all packages.
5. Run `yarn install` to install frontend packages, then `yarn run production` to build the assets (js, css).
6. Run `php artisan key:generate` to generate an application key. This will set `APP_KEY` with the right value automatically.
7. Run `php artisan setup:production -v` to run the migrations, seed the database and symlink folders.
The `setup:production` command will run migrations scripts for database, and flush all cache for config, route, and view, as an optimization process.
As the configuration of the application is cached, any update on the `.env` file will not be detected after that. You may have to run `php artisan config:cache` manually after every update of `.env` file.
### 4. Configure cron job
Monica requires some background processes to continuously run. The list of things Monica does in the background is described [here](https://github.com/monicahq/monica/blob/main/app/Console/Kernel.php#L63).
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`.
1. Navigate to 'Cron Jobs' in the cPanel GUI:
2. On that screen add the following:
Under common settings, select 'Once Per Minute'
Paste the following in the 'Command' section
```
php /var/www/monica/artisan schedule:run >> /dev/null 2>&1
```
### 5. Configure cPanel webserver
1. Navigate to the 'Subdomain' section in the cPanel GUI:
2. Update the path of the domain you wish to assign to Monica to the following:
```sh
/public_html/[subdomain you installed the monica folders on]/public
```
### Final step
The final step is to have fun with your newly created instance, which should be up and running to `http://[domain you installed Monica on]`.
From there you will be able to create an account and use the platform as normal.

254
docs/installation/providers/debian.md Normal file
View File

@@ -0,0 +1,254 @@
# Installing Monica on Debian <!-- omit in toc -->
<img alt="Logo" src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/4a/Debian-OpenLogo.svg/109px-Debian-OpenLogo.svg.png" width="96" height="127" />
Monica can run on Debian Buster.
- [Prerequisites](#prerequisites)
- [Installation steps](#installation-steps)
- [1. Clone the repository](#1-clone-the-repository)
- [2. Setup the database](#2-setup-the-database)
- [3. Configure Monica](#3-configure-monica)
- [4. Configure cron job](#4-configure-cron-job)
- [5. Configure Apache webserver](#5-configure-apache-webserver)
- [Final step](#final-step)
## Prerequisites
Monica depends on the following:
- A Web server, like [Apache httpd webserver](https://httpd.apache.org/)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- PHP 8.1+
- [Composer](https://getcomposer.org/)
- [Node.js](https://nodejs.org)
- [Yarn](https://yarnpkg.com)
- MySQL / MariaDB
An editor like vim or nano should be useful too.
**Apache:** Install Apache with:
```sh
sudo apt update
sudo apt install -y apache2
```
**Git:** Install Git with:
```sh
sudo apt install -y git
```
**PHP:**
If you are using Debian 10 or lower, PHP 8.1 is not available from the Debian project directly. Instead use the [deb.sury.org](https://deb.sury.org/) package repository from Ondřej Surý, maintainer of the mainline Debian packages.
```sh
sudo apt install -y curl software-properties-common
curl -sSL https://packages.sury.org/php/apt.gpg | sudo tee /etc/apt/trusted.gpg.d/php-sury.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php-sury.list
sudo apt update
```
Install PHP 8.1 with these extensions:
- bcmath
- curl
- dom
- gd
- gmp
- iconv
- intl
- json
- mbstring
- mysqli
- opcache
- pdo_mysql
- redis
- sodium
- tokenizer
- xml
- zip
Run:
```sh
sudo apt install -y php8.1 php8.1-bcmath php8.1-curl php8.1-gd php8.1-gmp \
php8.1-intl php8.1-mbstring php8.1-mysql php8.1-redis php8.1-tokenizer php8.1-xml php8.1-zip
```
**Composer:** After you're done installing PHP, you'll need the Composer dependency manager.
```sh
curl -sSL https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin/ --filename=composer
```
**Node.js:** Install node.js with package manager.
```sh
curl -sSL https://deb.nodesource.com/setup_16.x | sudo bash -
sudo apt install -y nodejs
```
**Yarn:** Install yarn with npm.
```sh
sudo npm install --global yarn
```
**MariaDB:** Install MariaDB. Note that this only installs the package, but does not setup Mysql. This is done later in the instructions:
```sh
sudo apt install -y mariadb-server
```
## Installation steps
Once the softwares above are installed:
### 1. Clone the repository
You may install Monica by simply cloning the repository. Consider cloning the repository into any folder, example here in `/var/www/monica` directory:
```sh
cd /var/www/
sudo 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](https://github.com/monicahq/monica/releases)
```sh
cd /var/www/monica
# Get latest tags from GitHub
sudo git fetch
# Clone the desired version
sudo git checkout tags/v2.18.0
```
### 2. Setup the database
First make the database a bit more secure.
```sh
sudo mysql_secure_installation
```
Next log in with the root account to configure the database.
```sh
sudo mysql -uroot -p
```
Create a database called 'monica'.
```sql
CREATE DATABASE monica CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
Create a user called 'monica' and its password 'strongpassword'.
```sql
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.
```sql
GRANT ALL ON monica.* TO 'monica'@'localhost';
```
And finally we apply the changes and exit the database.
```sql
FLUSH PRIVILEGES;
exit
```
### 3. Configure Monica
`cd /var/www/monica` then run these steps with `sudo`:
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](/docs/installation/mail.md) 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](generic.md#setup-queues)
8. _Optional_: Setup the access tokens to use the API follow optional instruction of [generic installation](generic.md#setup-access-tokens)
### 4. Configure cron job
Monica requires some background processes to continuously run. The list of things Monica does in the background is described [here](https://github.com/monicahq/monica/blob/main/app/Console/Kernel.php#L63).
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:
```sh
sudo crontab -u www-data -e
```
Then, in the `crontab` editor window you just opened, paste the following at the end of the document:
```sh
* * * * * 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:
```sh
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:
```sh
sudo a2enmod rewrite
```
3. Configure a new monica site in apache by doing:
```sh
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:
```html
<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 reload Apache. You can do that by running:
```sh
sudo a2dissite 000-default.conf
sudo a2ensite monica.conf
sudo systemctl reload apache2
```
### Final step
The final step is to have fun with your newly created instance, which should be up and running to `http://localhost`.

44
docs/installation/providers/docker.md Normal file
View File

@@ -0,0 +1,44 @@
# Installing Monica on Docker <!-- omit in toc -->
<img alt="Logo" src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/4e/Docker_%28container_engine%29_logo.svg/915px-Docker_%28container_engine%29_logo.svg.png" width="290" height="69" />
Monica can run with Docker images.
- [Prerequisites](#prerequisites)
- [Use Monica docker image](#use-monica-docker-image)
- [Running the image with docker-compose](#running-the-image-with-docker-compose)
## Prerequisites
You can use [Docker](https://www.docker.com) and [docker-compose](https://docs.docker.com/compose/) to pull or build
and run a Monica image, complete with a self-contained MySQL database.
This has the nice properties that you don't have to install lots of software directly onto your system, and you can be up and running
quickly with a known working environment.
For any help about how to install Docker, see their [documentation](https://docs.docker.com/get-docker/).
## Use Monica docker image
The [standard `monica` image](https://hub.docker.com/_/monica/) can be run with the latest release of Monica.
Run the container with the command below (don't change the username/password):
```sh
mysqlCid="$(docker run -d \
-e MYSQL_RANDOM_ROOT_PASSWORD=true \
-e MYSQL_DATABASE=monica \
-e MYSQL_USER=homestead \
-e MYSQL_PASSWORD=secret \
"mysql:5.7")"
docker run -d \
--link "$mysqlCid":mysql \
-e DB_HOST=mysql \
-p 8080:80 \
monica
```
Wait for the migration db to complete, then go to [http://localhost:8080](http://localhost:8080).
## Running the image with docker-compose
See some examples of docker-compose possibilities in the [example section](https://github.com/monicahq/docker/tree/master/.examples).

319
docs/installation/providers/generic.md Normal file
View File

@@ -0,0 +1,319 @@
# Installing Monica (Generic) <!-- omit in toc -->
- [Prerequisites](#prerequisites)
- [Types of databases](#types-of-databases)
- [Installation steps](#installation-steps)
- [1. Clone the repository](#1-clone-the-repository)
- [2. Setup the database](#2-setup-the-database)
- [3. Configure Monica](#3-configure-monica)
- [4. Configure cron job](#4-configure-cron-job)
- [5. Configure Apache webserver](#5-configure-apache-webserver)
- [6. Optional: Setup the queues with Redis, Beanstalk or Amazon SQS](#6-optional-setup-the-queues-with-redis-beanstalk-or-amazon-sqs)
- [7. Optional: Setup the access tokens to use the API](#7-optional-setup-the-access-tokens-to-use-the-api)
- [Generate the encryption keys](#generate-the-encryption-keys)
- [Optional: Save the encryption keys as variable](#optional-save-the-encryption-keys-as-variable)
- [Optional: Generate a Password grant client](#optional-generate-a-password-grant-client)
- [Final step](#final-step)
## Prerequisites
If you don't want to use Docker, the best way to setup the project is to use the same configuration that [Homestead](https://laravel.com/docs/homestead) uses. Basically, Monica depends on the following:
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- PHP 8.1+
- [Composer](https://getcomposer.org/)
- [Node.js](https://nodejs.org)
- [Yarn](https://yarnpkg.com)
- [MySQL](https://www.mysql.com/)
- Optional: Redis or Beanstalk
**Git:** Git should come pre-installed with your server. If it doesn't - use the installation instructions in the link.
**PHP:** Install php8.1 minimum, with these extensions:
- bcmath
- curl
- dom
- gd
- gmp
- iconv
- intl
- json
- mbstring
- mysqli
- opcache
- pdo_mysql
- redis
- sodium
- tokenizer
- xml
- zip
**Composer:** After you're done installing PHP, you'll need the Composer dependency manager. It is not enough to just install Composer, you also need to make sure it is installed globally for Monica's installation to run smoothly:
```sh
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin/ --filename=composer
php -r "unlink('composer-setup.php');"
```
**Node.js:** Install node.js 16+ minimum
**Yarn:** Install yarn using npm
```sh
npm install --global yarn
```
**Mysql:** Install Mysql 5.7+
### 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](https://laravel.com/docs/database#configuration) 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, which is often pre-packaged with many common linux instances ([DigitalOcean](https://www.digitalocean.com/) droplets are one example), you need to clone the repository in a specific folder:
```sh
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](https://github.com/monicahq/monica/releases).
```sh
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.
```sh
mysql -u root -p
```
Create a database called 'monica'.
```sql
CREATE DATABASE monica CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
Create a user called 'monica' and its password 'strongpassword'.
```sql
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.
```sql
GRANT ALL ON monica.* TO 'monica'@'localhost';
```
And finally we apply the changes and exit the database.
```sql
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](/docs/installation/mail.md) 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.
The `setup:production` command will run migrations scripts for database, and flush all cache for config, route, and view, as an optimization process.
As the configuration of the application is cached, any update on the `.env` file will not be detected after that. You may have to run `php artisan config:cache` manually after every update of `.env` file.
### 4. Configure cron job
Monica requires some background processes to continuously run. The list of things Monica does in the background is described [here](https://github.com/monicahq/monica/blob/main/app/Console/Kernel.php#L63).
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`.
1. Open crontab edit for the apache user:
```sh
crontab -u www-data -e
```
2. Then, in the text editor window you just opened, copy the following:
```
* * * * * /usr/bin/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:
```sh
chgrp -R www-data /var/www/monica
chmod -R 775 /var/www/monica/storage
```
2. Enable the rewrite module of the Apache webserver:
```sh
a2enmod rewrite
```
2. Configure a new monica site in apache by doing:
```sh
nano /etc/apache2/sites-available/monica.conf
```
3. 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:
```html
<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:
```sh
a2dissite 000-default.conf
a2ensite monica.conf
service apache2 restart
```
<a id="setup-queues"></a>
### 6. Optional: Setup the queues with Redis, Beanstalk or Amazon SQS
Monica can work with a queue mechanism to handle different events, so we don't block the main thread while processing stuff that can be run asynchronously, like sending emails. By default, Monica does not use a queue mechanism but can be setup to do so.
We recommend that you do not use a queue mechanism as it complexifies the overall system and can make debugging harder when things go wrong.
This is why we suggest to use `QUEUE_CONNECTION=sync` in your .env file. This will bypass the queues entirely and will process requests as they come. In practice, unless you have thousands of users, you don't need to use an asynchronous queue.
That being said, if you still want to make your life more complicated, here is what you can do.
There are several choices for the queue mechanism:
- Database (this will use the database used by the application to act as a queue)
- Redis
- Beanstalk
- Amazon SQS
The simplest queue is the database driver. To set it up, simply change in your `.env` file the following `QUEUE_CONNECTION=sync` by `QUEUE_CONNECTION=database`.
To configure the other queues, refer to the [official Laravel documentation](https://laravel.com/docs/master/queues#driver-prerequisites) on the topic.
After configuring the queue, you'll have to run the queue worker, as described in the [Laravel documentation](https://laravel.com/docs/master/queues#running-the-queue-worker).
```sh
php artisan queue:work --sleep=3 --tries=3
```
Some process monitor such as [Supervisor](https://laravel.com/docs/master/queues#supervisor-configuration) could be useful to monitor the queue worker.
<a id="setup-access-tokens"></a>
### 7. Optional: Setup the access tokens to use the API
In order to use the Monica API for your instance, you will have to instantiate encryption keys first.
#### Generate the encryption keys
Run this command:
```sh
php artisan passport:keys
php artisan passport:client --personal --no-interaction
```
This command will generate encryption keys in the `storage` directory.
Be sure to backup the `oauth-private.key` and `oauth-public.key` files to maintain future access.
#### Optional: Save the encryption keys as variable
Instead of keeping the encryption keys as files, you can add them as environment variable. This is very useful for any environment where you cannot deploy these file in each server (heroku, fortrabbit, etc.).
- Output the private key:
```sh
sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' storage/oauth-private.key
```
Copy the output to an environment variable called `PASSPORT_PRIVATE_KEY` in your `.env` file.
```
PASSPORT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIJKAIBAAKCAgEAsC..."
```
- Do the same thing with the contents of the public key:
```sh
sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' storage/oauth-public.key
```
Copy the output to an environment variable called `PASSPORT_PUBLIC_KEY` in your `.env` file.
```
PASSPORT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhki..."
```
#### Optional: Generate a Password grant client
A [password grant client](https://laravel.com/docs/master/passport#creating-a-password-grant-client) can be generated in order to use the OAuth access (used in the mobile application for instance).
- Run this command to generate a password grant client:
```sh
php artisan passport:client --password --no-interaction
```
- This will display a client ID and secret:
```
Password grant client created successfully.
Client ID: 5
Client secret: zsfOHGnEbadlBP8kLsjOV8hMpHAxb0oAhenfmSqq
```
- Copy the two values into two new environment variables of your `.env` file:
- The value of `Client ID` in a `PASSPORT_PASSWORD_GRANT_CLIENT_ID` variable
- The value of `Client secret` in a `PASSPORT_PASSWORD_GRANT_CLIENT_SECRET` variable
- OAuth login can be access on `http://localhost/oauth/login`.
### Final step
The final step is to have fun with your newly created instance, which should be up and running to `http://localhost`.

137
docs/installation/providers/heroku.md Normal file
View File

@@ -0,0 +1,137 @@
# Installing Monica on Heroku <!-- omit in toc -->
Monica can be deployed on Heroku using the button below:
[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/monicahq/monica/tree/main)
- [Installation](#installation)
- [Configuration](#configuration)
- [Optional: Setup the access tokens to use the API](#optional-setup-the-access-tokens-to-use-the-api)
- [Optional: Generate a Password grant client for OAuth access](#optional-generate-a-password-grant-client-for-oauth-access)
- [Limitations](#limitations)
- [Updating Heroku instance](#updating-heroku-instance)
- [Update from 2.x to 3.x](#update-from-2x-to-3x)
## Installation
Before deployment, Heroku will ask you to define a few variables.
- Please ensure to enter a custom `APP_KEY` when asked (you can for instance copy and paste the output of `echo -n 'base64:'; openssl rand -base64 32`).
- In addition, you can edit the email address Monica will send emails to (`MAIL_FROM_ADDRESS`), the name of the sender (`MAIL_FROM_NAME`), where emails should link to (`APP_URL`) and some other important variables on that screen.
After deployment, click on ![Manage App](../../images/heroku_manage_app.png) to open the dashboard of your new application:
![Heroku Dashboard](../../images/heroku_dashboard.png)
Click on **Heroku Scheduler** to open scheduler dashboard. Create a new job, and define a new job to run this command every 10 minutes or every hour at 00 minutes:
```sh
php artisan schedule:run
```
You are now able to open the application and register a new user.
### Configuration
Your Monica instance will use a [JawsDB MySQL Kitefin Shared plan](https://elements.heroku.com/addons/jawsdb) (free) by default. Additional environment variables, such as details of the mail server, can be added after setup through the Heroku interface.
Monica doesn't require a lot of power - it will run perfectly fine on the free plan provided by Heroku.
After deployment, the configuration of your app should look like this:
![picture of configuration](https://raw.githubusercontent.com/monicahq/monica/main/docs/images/heroku_dashboard-resources.png)
Note that when you deploy with the "Deploy to Heroku" purple button, only 1 dyno ("web") is activated while the "queue" one is not. That is OK - the "queue" dyno is only helpful if you set `QUEUE_CONNECTION=database` (default is 'sync').
### Optional: Setup the access tokens to use the API
In order to generate personal access tokens from the UI, you need to:
* Install the [Heroku CLI](https://devcenter.heroku.com/categories/command-line) and log in.
* From your command line, run:
```sh
heroku run bash -a <APP-ID>
```
* Run:
```sh
php artisan passport:keys
php artisan passport:client --personal --no-interaction
```
This command will generate encryption keys in the `storage` directory.
The two keys `oauth-private.key` and `oauth-public.key` cannot be backup and recreate in heroku directly.
* Still in the Heroku CLI, run this command to output the private key:
```sh
sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' ~/storage/oauth-private.key
```
Copy the output to a new Heroku environment variable called `PASSPORT_PRIVATE_KEY`
* Do the same thing with the contents of the public key:
```sh
sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' ~/storage/oauth-public.key
```
Copy its contents to a new Heroku environment variable called `PASSPORT_PUBLIC_KEY`
Once Heroku is re-deploy, you should be able to use the 'Create new token' function in https://XXX.herokuapp.com/settings/api
Once you have the token, you can use the API with a command line:
```sh
curl -H "Authorization: Bearer $API_TOKEN" https://XXX.herokuapp.com/api
```
If everything is well, this call will return:
```json
{"success":{"message":"Welcome to Monica"}}
```
#### Optional: Generate a Password grant client for OAuth access
* Still in the Heroku CLI, run this command to generate a password grant client:
```sh
php artisan passport:client --password --no-interaction
```
* This will display a client ID and secret:
```
Password grant client created successfully.
Client ID: 5
Client secret: zsfOHGnEbadlBP8kLsjOV8hMpHAxb0oAhenfmSqq
```
* Copy the two values into two new environment variable of your `.env` file:
- The value of client ID in a `PASSPORT_PASSWORD_GRANT_CLIENT_ID` variable
- The value of client secret in a `PASSPORT_PASSWORD_GRANT_CLIENT_SECRET` variable
## Limitations
* No storage by default. It means you will not be able to upload photos, document, avatars for your contacts.
Follow [this documentation](/docs/installation/storage.md) to set an external storage.
* No email by default - email configuration isn't required to use Monica on Heroku, but it's useful for reminders. You can configure your own [mailserver](/docs/installation/mail.md), though the easiest way to go about this is to use Mailgun's [free email add-on on Heroku](https://elements.heroku.com/addons/mailgun):
* [Sign up for Mailgun](https://signup.mailgun.com/new/signup) (the [free plan](https://www.mailgun.com/pricing) is sufficient)
* Add a custom domain in mailgun.
* Add the "To" and "From" e-mail addresses you're going to use as verified e-mail addresses on mailgun, and then actually verifying them.
* Upgrade mailgun by entering a credit card (there is no charge, but they do require you enter it so you'll be upgraded to some other tier that enables you to actually send messages).
* Verify the custom domain via DNS (there are instructions on their site)
* In Heroku, go to your app, then to the Settings tab. In it, you will have a button that reads "Reveal Config Vars". Click it, and change the following vars:
* `MAIL_MAILER`: `mailgun`
* `MAILGUN_DOMAIN`: your Mailgun domain
* `MAILGUN_SECRET`: your Mailgun API key — find it [here](https://app.mailgun.com/app/account/security)
* `MAIL_FROM_ADDRESS`: email address to use for 'from' email (could just use your own)
* `MAIL_FROM_NAME`: name of the 'from' user (could just use "Monica")
## Updating Heroku instance
You can update your Monica instance to the latest version by cloning the repository and pushing it to Heroku git.
Clone the Monica repository to your local environment by `git clone https://github.com/monicahq/monica`, and add heroku git repository by `heroku git:remote -a (heroku app name)`. Then, push to heroku by `git push heroku main:master`. Heroku will build and update the repository, automatically.
See more information about updating Monica (including Heroku-specific things) [here](https://github.com/monicahq/monica/blob/main/docs/installation/update.md).
## Update from 2.x to 3.x
If you already deployed a 2.x Monica instance, when you will upgrade to 3.x, you will have to manually add `node.js` as a buildpack:
- Go to `Settings`
- Under `Buildpacks`, add a new buildpack, and select `nodejs`
- `heroku/nodejs` will be selected automatically

257
docs/installation/providers/ubuntu.md Normal file
View File

@@ -0,0 +1,257 @@
# Installing Monica on Ubuntu <!-- omit in toc -->
<img alt="Ubuntu" src="https://upload.wikimedia.org/wikipedia/commons/thumb/a/ab/Logo-ubuntu_cof-orange-hex.svg/120px-Logo-ubuntu_cof-orange-hex.svg.png" width="120" height="120" />
Monica can run on [Ubuntu 22.04 (Jammy Jellyfish)](http://releases.ubuntu.com/22.04/).
- [Prerequisites](#prerequisites)
- [Types of databases](#types-of-databases)
- [Installation steps](#installation-steps)
- [1. Clone the repository](#1-clone-the-repository)
- [2. Setup the database](#2-setup-the-database)
- [3. Configure Monica](#3-configure-monica)
- [4. Configure cron job](#4-configure-cron-job)
- [5. Configure Apache webserver](#5-configure-apache-webserver)
- [Final step](#final-step)
## Prerequisites
Monica depends on the following:
- [Apache httpd webserver](https://httpd.apache.org/)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- PHP 8.1+
- [Composer](https://getcomposer.org/)
- [Node.js](https://nodejs.org)
- [Yarn](https://yarnpkg.com)
- [MySQL](https://support.rackspace.com/how-to/installing-mysql-server-on-ubuntu/)
**Apache:** If it doesn't come pre-installed with your server, follow the [instructions here](https://www.digitalocean.com/community/tutorials/how-to-install-linux-apache-mysql-php-lamp-stack-on-ubuntu-16-04#step-1-install-apache-and-allow-in-firewall) to setup Apache and config the firewall.
**Git:** Git should come pre-installed with your server. If it's not, install it with:
```sh
sudo apt update
sudo apt install -y git
```
**Unzip:** Unzip is required but was not installed by default. Install it with:
```sh
sudo apt update
sudo apt install -y unzip
```
**Apache:** Apache should come pre-installed with your server. If it's not, install it with:
```sh
sudo apt update
sudo apt install -y apache2
```
**PHP 8.1+:**
First add this PPA repository:
```sh
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php
```
Then install php 8.1 with these extensions:
```sh
sudo apt update
sudo apt install -y php8.1-{bcmath,cli,curl,common,fpm,gd,gmp,intl,mbstring,mysql,opcache,redis,xml,zip}
```
**Composer:** After you're done installing PHP, you'll need the [Composer](https://getcomposer.org/download/) dependency manager.
```sh
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](https://getcomposer.org/download/) page)
**Node.js:** Install node.js with package manager.
```sh
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
```
**Yarn:** Install yarn with npm.
```sh
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:
```sh
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](https://laravel.com/docs/database#configuration) 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:
```sh
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](https://github.com/monicahq/monica/releases):
```sh
cd /var/www/monica
# Get latest tags from GitHub
git fetch
# Clone the desired version
git checkout tags/v4.0.0
```
### 2. Setup the database
Log in with the root account to configure the database.
```sh
mysql -u root -p
```
Create a database called 'monica'.
```sql
CREATE DATABASE monica CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
Create a user called 'monica' and its password 'strongpassword'.
```sql
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.
```sql
GRANT ALL ON monica.* TO 'monica'@'localhost';
```
And finally we apply the changes and exit the database.
```sql
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
- Update database information.
```diff
- DB_USERNAME=homestead
- DB_PASSWORD=secret
+ DB_USERNAME=monica
# Use the password you created.
+ DB_PASSWORD=strongpassword
```
- configure a [mailserver](/docs/installation/mail.md) 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.
4. Run `composer install --no-interaction --no-dev` to install all packages.
5. Run `yarn install` to install frontend packages, then `yarn run production` to build the assets (js, css).
6. Run `php artisan key:generate` to generate an application key. This will set `APP_KEY` with the right value automatically.
7. 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`
8. _Optional_: Setup the queues with Redis, Beanstalk or Amazon SQS: see optional instruction of [generic installation](generic.md#setup-queues)
9. _Optional_: Setup the access tokens to use the API follow optional instruction of [generic installation](generic.md#setup-access-tokens)
### 4. Configure cron job
Monica requires some background processes to continuously run. The list of things Monica does in the background is described [here](https://github.com/monicahq/monica/blob/main/app/Console/Kernel.php#L33).
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:
```sh
crontab -u www-data -e
```
Then, in the `crontab` editor window you just opened, paste the following at the end of the document:
```sh
* * * * * 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:
```sh
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:
```sh
sudo a2enmod rewrite
```
3. Configure a new monica site in apache by doing:
```sh
sudo nano /etc/apache2/sites-available/monica.conf
```
Then, in the `nano` text editor window you just opened, copy the following - swapping the `monica.example.com` with your server's IP address/associated domain:
```html
<VirtualHost *:80>
ServerName monica.example.com
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:
```sh
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`.

77
docs/installation/providers/vagrant.md Normal file
View File

@@ -0,0 +1,77 @@
# Installing Monica on Vagrant <!-- omit in toc -->
<img width="96" height="117" src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/87/Vagrant.png/197px-Vagrant.png" />
Monicahq vagrant box is available on [Vagrant Cloud](https://app.vagrantup.com/monicahq/boxes/monicahq).
The only provider for this box is virtualbox.
- [Run the monicahq vagrant box](#run-the-monicahq-vagrant-box)
- [Default Monica configuration in the VM](#default-monica-configuration-in-the-vm)
- [Database users](#database-users)
- [Apache configuration](#apache-configuration)
- [Build your own image](#build-your-own-image)
## Run the monicahq vagrant box
1. Download and install [Vagrant](https://www.vagrantup.com/) for your operating system
2. Create a folder to put the vagrant configuration files
```sh
mkdir ~/monica
cd ~/monica
```
3. Download the `Vagrantfile` script
```sh
curl -sS https://raw.githubusercontent.com/monicahq/monica/main/scripts/vagrant/Vagrantfile -o Vagrantfile
```
4. Edit Vagrantfile to set the appropriate host port number (default: 8080)
```
config.vm.network "forwarded_port", guest: 80, host: 8080
```
5. Launch the virtual machine with
```sh
vagrant up
```
The virtual machine will be created and pulled up with Vagrantfile script.
Once the process is complete you can either access the virtual machine by typing `vagrant ssh` in your terminal, or access the Monica web interface by opening [http://localhost:8080](http://localhost:8080) in your browser on your host machine.
## Default Monica configuration in the VM
### Database users
* Root database user
- Username: `root`
- Password: `changeme`
* Monica database user
- Username: `monica`
- Password: `changeme`
### Apache configuration
* The project is installed in `/var/www/html/monica`
* The root folder for the web server is `/var/www/html/monica/public`
## Build your own image
1. Download the `Vagrantfile` script
```sh
curl -sS https://raw.githubusercontent.com/monicahq/monica/main/scripts/vagrant/build/Vagrantfile -o Vagrantfile
curl -sS https://raw.githubusercontent.com/monicahq/monica/main/scripts/vagrant/build/install-monica.sh -o install-monica.sh
```
2. Run the box by calling:
```sh
vagrant up monicahq-latest
```
for the latest commit, or with a GIT_TAG to run a specific version:
```sh
GIT_TAG=$(GIT_TAG) vagrant up monicahq-stable
```
3. Package you own box
You can package it to use it more quickly later:
```sh
vagrant up monicahq-latest
vagrant package monicahq-latest --output ./my-monicahq.box
vagrant box add my-monicahq ./my-monicahq.box
```

48
docs/installation/readme.md Normal file
View File

@@ -0,0 +1,48 @@
# Installing Monica (Generic) <!-- omit in toc -->
Monica can be installed on a variety of platforms. The choice of the platform is yours.
- [Requirements](#requirements)
- [Installation instructions for specific platforms](#installation-instructions-for-specific-platforms)
- [Generic Linux instructions](#generic-linux-instructions)
- [Platforms](#platforms)
- [Other documentation](#other-documentation)
<a id="markdown-requirements" name="requirements"></a>
## Requirements
If you don't want to use [Docker](/docs/installation/providers/docker.md), the best way to setup the project is to use the same configuration that [Homestead](https://laravel.com/docs/homestead) uses. Basically, Monica depends on the following:
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* PHP 8.1+
* [Composer](https://getcomposer.org/)
* [MySQL](https://www.mysql.com/)
* Optional: Redis or Beanstalk
<a id="markdown-installation-instructions-for-specific-platforms" name="installation-instructions-for-specific-platforms"></a>
## Installation instructions for specific platforms
The preferred OS distribution is Ubuntu 18.04, simply because all the development is made on it and we know it works. However, any OS that lets you install the above packages should work.
<a id="markdown-generic-linux-instructions" name="generic-linux-instructions"></a>
### Generic Linux instructions
* [Generic Instructions](/docs/installation/providers/generic.md)
* [Ubuntu](/docs/installation/providers/ubuntu.md)
* [Debian](/docs/installation/providers/debian.md)
<a id="markdown-platforms" name="platforms"></a>
### Platforms
* [Docker](/docs/installation/providers/docker.md)
* [Heroku](/docs/installation/providers/heroku.md)
* [Vagrant](/docs/installation/providers/vagrant.md)
* [YunoHost](https://github.com/YunoHost-Apps/monica_ynh)
* [Cloudron](/docs/installation/providers/cloudron.md)
* [cPanel-based Shared Hosting](/docs/installation/providers/cpanel.md)
### Other documentation
* [Mail settings](/docs/installation/mail.md): allowing your instance to send mails. Useful for reminders.
* [Storage](/docs/installation/storage.md): define an external storage for your instance.
* [Ssl](/docs/installation/ssl.md): how to set ssl for your production-level instance.
* [FAQ](/docs/installation/faq.md): a list of common problems and solutions.

148
docs/installation/ssl.md Normal file
View File

@@ -0,0 +1,148 @@
# Using monica with HTTPS <!-- omit in toc -->
- [Local Installation](#local-installation)
- [With a proxy](#with-a-proxy)
- [Example: Docker Compose](#example-docker-compose)
When Monica is run with `APP_ENV=production`, it is required that Monica is running
with HTTPS. In order to satisfy this requirement, some additional configuration
needs to be performed.
## Local Installation
If you have Monica installed locally, and have HTTPS set up on your Apache server,
the only configuration required for Monica to support HTTPS is to set your `APP_URL`
to start with `https://`. This configuration parameter is used to generate external
links to your application for emails and such.
## With a proxy
Monica uses the [fideloper/proxy](https://packagist.org/packages/fideloper/proxy)
package to configure support *trusted proxies*. When enabled, Monica will trust
incoming headers like X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto in
order to dynamically determine the setup of your application.
You can configure this in your `.env` file:
``` bash
# Set trusted proxy IP addresses.
# To trust all proxies that connect directly to your server, use a "*".
# To trust one or more specific proxies that connect directly to your server, use a comma separated list of IP addresses.
APP_TRUSTED_PROXIES=
# Enable automatic cloudflare trusted proxy discover
APP_TRUSTED_CLOUDFLARE=false
```
Make sure that whatever proxy you are using is in your `APP_TRUSTED_PROXIES` list.
If you use Cloudflare, you can also simply set `APP_TRUSTED_CLOUDFLARE` to true to
automatically add cloudflare's IP addresses to the list.
If you fail to have `APP_TRUSTED_PROXIES` set correctly, Monica will generate internal links that
have the wrong protocol or host on them. This might seem to work if you have redirects set up,
but can fail with insecure form submission errors.
Remember to also update your `APP_URL` to correctly point to the HTTPS version of your application.
### Example: Docker Compose
If you are already using a dockerized version of Monica, you can use a Dockerized nginx
configuration to perform TLS termination.
For example, you could use an `nginx.conf` similar to:
``` nginx.conf
error_log stderr;
events { worker_connections 1024; }
http {
server {
listen [::]:443;
listen 443;
server_name monica.example.com;
ssl on;
ssl_certificate /https-cert.pem;
ssl_certificate_key /https-key.pem;
ssl_protocols TLSv1.2;
location / {
proxy_pass http://localhost:3001;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
server {
if ($host = monica.example.com) {
return 301 https://$host$request_uri;
}
listen 80 ;
listen [::]:80;
server_name monica.example.com;
return 404;
}
}
```
Or an apache.conf file similar to:
```virtual-site.conf
<VirtualHost *:80>
ServerAdmin you@domain.com
ServerName monica.yourdomain.com
RewriteEngine on
RewriteCond %{SERVER_NAME} =monica.yourdomain.com
# redirect all requests to port 80 to port 443 using 308 code
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,QSA,NE,R=308]
</VirtualHost>
```
```virtual-site-ssl.conf
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerAdmin you@domain.com
ServerName monica.yourdomain.com
ProxyPreserveHost On
ProxyRequests Off
ProxyPass / http://localhost:3001/
ProxyPassReverse / http://localhost:3001/
RequestHeader add X-Forwarded-Proto https
SSLCertificateFile /etc/letsencrypt/live/monica.yourdomain.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/monica.yourdomain.com/privkey.pem
SSLCACertificateFile /etc/letsencrypt/live/monica.yourdomain.com/chain.pem
Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
</IfModule>
```
And a `docker-compose.yml` like:
``` yaml
version: '3.4'
services:
monica:
image: monica
expose:
- 3001:80
volumes:
- '/var/monica-storage:/var/www/html/storage'
env_file: /etc/monica/monica.env
restart: unless-stopped
nginx:
image: nginx:alpine
volumes:
- '/etc/monica/nginx.conf:/etc/nginx/nginx.conf:ro'
- '/etc/monica/https-cert.pem:/https-cert.pem:ro'
- '/etc/monica/https-key.pem:/https-key.pem:ro'
ports:
- 443:443
depends_on:
- monica
restart: unless-stopped
```
You would also need to set `APP_TRUSTED_PROXIES=*` in your monica environment.

105
docs/installation/storage.md Normal file
View File

@@ -0,0 +1,105 @@
# External storage <!-- omit in toc -->
- [Configure an external storage](#configure-an-external-storage)
- [Add an external storage](#add-an-external-storage)
- [1. Create AWS S3 storage](#1-create-aws-s3-storage)
- [2. Create a user](#2-create-a-user)
- [3. Set environment variables](#3-set-environment-variables)
- [(Optional) Use another S3 provider](#optional-use-another-s3-provider)
- [Move avatars to S3 storage](#move-avatars-to-s3-storage)
Some times you want to add an external storage for your avatars, photos, or documents.
This is useful in particular if you install Monica on a stateless volatile instance, like Heroku, Platform.sh, etc.
We currently only support AWS S3 driver as external storage.
## Configure an external storage
You need to define at least these environment variables:
```
FILESYSTEM_DISK=s3
AWS_BUCKET=
AWS_DEFAULT_REGION=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
```
See below for more details about each environment variable.
## Add an external storage
### 1. Create AWS S3 storage
1. Go to the S3 [console](https://s3.console.aws.amazon.com/s3/home)
2. Add a new bucket
3. Save the name and location of the bucket in `AWS_BUCKET` and `AWS_DEFAULT_REGION` variables
```
AWS_BUCKET=my-bucket
AWS_DEFAULT_REGION=eu-west-3
```
You can also use [AWS CLI](https://docs.aws.amazon.com/cli/index.html) to create the bucket:
```sh
aws s3 mb s3://my-bucket
```
### 2. Create a user
1. Create a new user via the [console](https://console.aws.amazon.com/iam/home#/users).
2. Add the strategy for S3 access, for instance `AmazonS3FullAccess` is a good choice:
- add the user to a group with the right strategy
- or attach the strategy directly.
3. Save credentials of the user in `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` variables
```
AWS_ACCESS_KEY_ID=AKXA3E2NYF7NPDJVQSOU
AWS_SECRET_ACCESS_KEY=aASalDme6wB8kGC7Xla6K3pI+FiFylpCVnGCmdnD
```
You can also use [AWS CLI](https://docs.aws.amazon.com/cli/index.html) to set credentials:
```sh
aws iam create-user --user-name user-monica-test
aws iam attach-user-policy --user-name user-monica-test --policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess
aws iam create-access-key --user-name user-monica-test
```
Output:
```
{
"AccessKey": {
"UserName": "user-monica-test",
"AccessKeyId": "AKIAXE2N0F6NIMZXLCGB",
"Status": "Active",
"SecretAccessKey": "Lh5ValIoe9xlfrhkpqiZOub1TFFo4qn1sAdFvlOM",
"CreateDate": "2020-04-12T11:35:06+00:00"
}
}
```
Then save `AccessKeyId` and `SecretAccessKey` in `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` variables.
### 3. Set environment variables
Set the `FILESYSTEM_DISK` variable to use S3 storage:
```
FILESYSTEM_DISK=s3
```
### (Optional) Use another S3 provider
*AWS_ENDPOINT* variable can be used to define a S3-compatible provider other than Amazon, like [Digitalocean](https://www.digitalocean.com/products/spaces/), [Scaleway](https://www.scaleway.com) or [Minio](https://min.io/).
example: `AWS_ENDPOINT=nyc3.digitaloceanspaces.com`
### Move avatars to S3 storage
If you previously used local storage and want to move all avatars to a new S3 storage, use `monica:moveavatars` command once to move all files:
```sh
php artisan monica:moveavatars
```

237
docs/installation/update.md Normal file
View File

@@ -0,0 +1,237 @@
# Update your server <!-- omit in toc -->
- [Generic instructions](#generic-instructions)
- [Updating Heroku instance](#updating-heroku-instance)
- [Importing vCards (CLI only)](#importing-vcards-cli-only)
- [Importing SQL from the exporter feature](#importing-sql-from-the-exporter-feature)
- [Importing SQL into Heroku](#importing-sql-into-heroku)
- [WARNING: This will delete your current database. Only use on fresh installations, or if you know what you're doing.](#warning-this-will-delete-your-current-database-only-use-on-fresh-installations-or-if-you-know-what-youre-doing)
## Generic instructions
Monica uses the concept of releases and tries to follow
[Semantic Versioning](http://semver.org/) as much as possible. If you run the project locally,
or if you have installed Monica on your own server, you need to follow the steps below to update it, **every single time**, or you will run into problems.
1. Always make a backup of your data before upgrading.
2. Check that your backup is valid.
3. Read the [release notes](https://github.com/monicahq/monica/blob/main/CHANGELOG.md) to check for breaking changes.
4. Update sources:
1. Consider check out a tagged version of Monica since `main` branch may not always be stable.
Find the latest official version on the [release page](https://github.com/monicahq/monica/releases)
```sh
# Get latest tags from GitHub
git fetch
# Clone the desired version
git checkout tags/v2.18.0
```
2. Or check out `main`
```sh
git pull origin main
```
5. Update the dependencies of the project:
```sh
composer install --no-interaction --no-dev
```
6. Run `yarn install` to install frontend packages, then `yarn run production` to build the assets (js, css).
7. Then, run the following command to make the proper update:
```sh
php artisan monica:update --force
```
The `monica:update` command runs migration scripts for the database, and flushes all caches for config, route, and view as an optimization process. It’s easier than running every required command individually.
Note: if you have just change some setting in your `.env` file, as the configuration of the application is cached, any update on the `.env` file will not be detected after that. You may have to run `php artisan config:cache` manually after every update of `.env` file.
## Updating Heroku instance
You can update your Monica instance to the latest version by cloning the repository and pushing it to Heroku git.
1. Clone the Monica repository to your local environment by `git clone https://github.com/monicahq/monica.git`.
1. Add your app's heroku git repository by `heroku git:remote -a (heroku app name)` (this of course requires the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
1. Push to heroku by `git push heroku main:master`. Heroku will build and update the repository, automatically.
## Importing vCards (CLI only)
**Note**: this is only possible if you install Monica on your server or locally.
You can import your contacts in vCard format in your account with one simple
CLI command:
`php artisan import:vcard {email user} {filename}.vcf`
where `{email user}` is the email of the user in your Monica instance who will
be associated the new contacts to, and `{filename}` being the name of your .vcf file.
The .vcf file has to be in the root of your Monica installation (in the same directory
where the artisan file is).
Example: `php artisan import:vcard john@doe.com contacts.vcf`
The `.vcf` can contain as many contacts as you want.
## Importing SQL from the exporter feature
Monica allows you to export your data in SQL, under the Settings panel. When you
export your data in SQL, you'll get a file called `monica.sql`.
To import it into your own instance, you need to make sure that the database of
your instance is completely empty (no tables, no data).
Then, follow the steps:
* `php artisan migrate`
* Then import `monica.sql` into your database. Tools like phpmyadmin or Sequel
Pro might help you with that.
* Finally, sign in with the same credentials as the ones used on
https://monicahq.com and you are good to go.
There is one caveat with the SQL exporter: you can't get the photos you've uploaded for now.
### Importing SQL into Heroku
If you're running your own Monica Heroku instance as mentioned in the [Heroku Installation Documentation](https://github.com/monicahq/monica/blob/main/docs/installation/providers/heroku.md), you're not actually running your own SQL server, which means that the solutions above might not be of assistance.
Heroku dynos use a [ClearDB MySQL add-on](https://devcenter.heroku.com/articles/cleardb) as their database. You can still use an SQL admin tool (like phpMyAdmin or Sequel Pro) to interact with the database, as well as use the `mysql-client` command line tool, you just need to know where to look for the credentials.
If you open your app on the Heroku web interface, and click the "Settings" tab, you'll have an option to reveal your configuration vars. Do so, and look for the `CLEARDB_DATABASE_URL` variable. It's format should look like this:
`mysql://<USERNAME>:<PASSWORD>@<HOST>/<DATABASE>?reconnect=true`
Which are the database's `HOST` URL, its name (i.e. `DATABASE`) and your `USERNAME` and `PASSWORD`.
The `HOST` should be the region where the database is located (i.e. `us-cdbr-iron-east-01.cleardb.net`), the `DATABASE` should be prepended with `heroku_` (i.e. `heroku_xxxx`) and the `USERNAME` and `PASSWORD` should be strings of alphanumeric characters.
Now that you have the database's URL and access credentials, you can log into the database from your favorite database management tool. If you'd like to use a command-line tool, here are the step by step instructions for debian-based (e.g. Ubuntu) Linux:
#### WARNING: This will delete your current database. Only use on fresh installations, or if you know what you're doing.
1. **Update your Monica instance to the same version as the one you're importing into.** This will prevent nasty SQL mismatches later on.
2. Download your export file as explained above. Make sure you remember the username and password of the instance you **exported from**, as those will be your new sign-in information for the instance you're **importing into**.
3. Get `mysql-client` by `sudo apt-get install mysql-client`. Note you might need to first add the relevant repository using the instructions [here](https://downloads.mariadb.org/mariadb/repositories/#mirror=kku) (although don't follow them all the way, or you'll get a full running server on your own machine). If you're going to follow the scripted truncation listed on the steps below, you'll need access to the MySQL socket, which is only available if you also installed `mysql-server`. You can do so by `sudo apt-get install mysql-server`.
4. Connect to your database - `mysql --host=<HOST> --user=<USERNAME> --password=<PASSWORD> --reconnect <DATABASE>`. You should see something like this in your terminal:
```
mysql: [Warning] Using a password on the command line interface can be insecure.
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A
```
We are indeed using the password on the CLI, so disregard the warning. The `Reading table....` part should only take 10-20 seconds or so, wait it out. After that you should be prompted by your installation's MySQL database:
```
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 195775195
Server version: 5.5.62-log MySQL Community Server (GPL)
Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
```
5. Take a look around, if you'd like. If you'll enter `SHOW DATABASES` you'll see:
```
Connection id: 195779265
Current database: heroku_xxxxxxxxx
+------------------------+
| Database |
+------------------------+
| information_schema |
| heroku_xxxxxxxxx |
+------------------------+
2 rows in set (19.85 sec)
```
Where `heroku_xxxxxxxxx` is `DATABASE`, your database's name. Note that the `Current database` is your Monica database, `DATABASE`.
We're now done looking around and you can disconnect from the database by entering `quit` and hitting the return key.
**Note:** If at any point the server disconnects, you'll see something like this:
```
mysql> SHOW DATABASES;
ERROR 2013 (HY000): Lost connection to MySQL server during query
mysql> SHOW DATABASES;
ERROR 2006 (HY000): MySQL server has gone away
No connection. Trying to reconnect...
```
This is perfectly fine, and the reason behind the `--reconnect` flag you saw earlier.
6. **DANGER: This will delete all the things.** Make sure you're not connected to the database anymore (i.e. you entered `quit` and got back to your own machine).
Empty out all tables by running the following few lines of code (slightly modified from [this SO question](https://stackoverflow.com/questions/1912813/truncate-all-tables-in-a-mysql-database-in-one-command)), where all the credentials are the same as mentioned earlier. You can also copy and paste it into a `.sh` file, `chmod 777 <FILE_NAME>` and then run it by `./<FILE_NAME>`.
```
# USAGE: mysql_run_query <QUERY>
mysql_run_query() {
# Connect to the database silently (-N and -s) and execute the given command (-e)
mysql --host=<HOST> --user=<USERNAME> --password=<PASSWORD> --reconnect <DATABASE> -Nse "$1"
}
# The command below lists all the tables in your database, and pipes it to this while loop
echo "Getting all of the database's table names..."
mysql_run_query "SHOW TABLES;" |
while read table; do
# Empty out (i.e. "TRUNCATE" each table)
echo "Emptying out $table..."
mysql_run_query "SET FOREIGN_KEY_CHECKS = 0;TRUNCATE TABLE $table;SET FOREIGN_KEY_CHECKS = 1;"
done
echo "Done!"
```
This should take a bit of time to run, but you should be able to see the process as the truncated table go by. Wait for the `Done!` message.
**Notes:**
* This script performs the table truncations independent of one another, and one by one - on different connections. This is done on purpose, to avoid any catastrophic finger-slips on the actual database's MySQL console. If something bad happens, this should allow you to kill the terminal in time, or at least `CTRL+C` out of there. If you know what you're doing, then you can just connect to the database and follow [this article](https://tableplus.com/blog/2018/08/mysql-how-to-truncate-all-tables.html) on how to truncate all the tables with one SQL query.
* If you get the following error:
```
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
```
This probably means you have not installed `mysql-server` as mentioned before. Please do so now, and repeat the process.
* The `SET_FOREIGN_KEYS` part above relieves you of facing these type of errors:
```
ERROR 1701 (42000) at line 1: Cannot truncate a table referenced in a foreign key constraint
```
Due to the database's schema. If you do end up seeing those types of errors, please open an issue.
7. On your own machine (i.e. not on the remote database) import the fresh database into your installation (blatantly copied from this [SO answer](https://stackoverflow.com/questions/11803496/dump-sql-file-to-cleardb-in-heroku)):
```
mysql ---host=<HOST> --user=<USERNAME> --password=<PASSWORD> --reconnect <DATABASE> < monica.sql
```
If you get an error of the following format:
```
ERROR 1452 (23000) at line 8: Cannot add or update a child row: a foreign key constraint fails
```
Than open up `monica.sql` and at the following at the start of the file, right before the first `INSERT INTO...` statement:
```
SET FOREIGN_KEY_CHECKS = 0;
```
And this, at the very end of the file (after the last `INSERT INTO...` statement:
```
SET FOREIGN_KEY_CHECKS = 1
```
**Notes:**
* If you get an error of the following format:
```
ERROR 1064 (42000) at line 264: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near .....
```
It means that the database schema you're trying to import into does not match the schema of that database you've exported from. This is usually due to a change in the schema between Monica version, and should only happen if you're migrating from an old, unupdated version of Monica to a new version on a new machine. Please file an issue if you see this error and we will attempt to assist you.
You should now be able to access your Monica instance with the same credentials used for the old instance.