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

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
```