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

24
docs/administrators/deployment.md Normal file
View File

@@ -0,0 +1,24 @@
This document is aimed at the people deploying Monica on https://monicahq.com, and does not apply to the people installing Monica for their own use.
## Before deploying a new version
* Make sure `config/monica.php` contains the number of the new release you are about to create.
* Update `CHANGELOG.md` accordingly.
* Create a new release on https://version.monicahq.com with the release notes.
* Create a new release on https://github.com/monicahq/monica/releases, which will also automatically create a new tag.
* Write the release note with the tool hosted on https://monicahq.com/login
* Push the code to production.
## Deployment of the Docker images
This guide has been posted by [kstrauser](https://github.com/monicahq/monica/issues/676#issuecomment-352047750) - thanks for his help. Here are the steps necessary to deploy Monica on Docker hub:
* You need an account on [Docker hub](https://hub.docker.com).
* You need to have Docker installed on your machine.
* Run the following commands (example for the version 3.4.5):
```
git reset --hard v3.4.5
make docker_build docker_tag docker_push
```
The image should be up on the Docker Hub.

15
docs/administrators/press.md Normal file
View File

@@ -0,0 +1,15 @@
# Press articles
Here are all the mentions of Monica we've found on the web somewhere. Feel free to edit this list and submit new ones if you find any.
* https://blog.desdelinux.net/gestione-relaciones-personales-monica/
* https://tideways.io/profiler/blog/profiling-laravel-applications-using-the-open-source-monica-crm-as-example
* https://laravel-news.com/monica
* https://sivers.org/dbt
* https://medevel.com/monica-is-your-own-persona-crm-assistant-solution/
* https://www.cloudron.io/store/com.monicahq.cloudronapp.html
* https://bestlaravel.com/p/monica
* https://betalist.com/startups/monicahq
* https://www.bypeople.com/free-personal-crm/
* https://steemhunt.com/author/@mindblast/monica-open-source-personal-crm
* https://osinum.fr/monica/

34
docs/administrators/tips.md Normal file
View File

@@ -0,0 +1,34 @@
This document lists some tips that developers can use to add new content in Monica and contains the solution to uncommon problems.
## Add a new changelog entry
Changelog entries are used to describe what's new in the product. Each time an entry is created, we also need to create an association between users of the instance and the entry that has been created. This association is stored in `changelog_user`.
To add a new changelog entry, you need to:
* create a new entry in the `changelog.json` file in the public folder.
* make sure your new entry is at the TOP of the file, not the bottom.
### When is it relevant to create a changelog entry
We should not create a changelog entry every single time we make a change to the platform. The rule is to warn users only when we introduce something that they will benefit from. A bug fix is not something they will benefit from and is not worth mentioning. Simple visual changes, unless they drastically change the UI, should not be mentioned. Anything made on the Docker image or a packaging issue should not be mentioned.
## Failed Jobs queue
PostgreSQL users who previously failed Monica's update may receive errors similar to these:
> SQLSTATE[Number]: Duplicate table: 7 ERROR: relation "**failed_jobs**" already exists (SQL: create table "failed_jobs" ("id" bigserial primary key not null, "connection" text not null, "queue" text not null, "payload" text not null, "exception" text not null, "failed_at" timestamp(0) without time zone default CURRENT_TIMESTAMP not null))
> SQLSTATE[Number]: Duplicate table: 7 ERROR: relation "**failed_jobs**" already exists
The problem is solved by running the command:
```
php artisan queue:flush
```
...with the appropriate privileges.
Immediately after (through a tool like `psql`) access the Monica database and run this command:
```
DROP TABLE "failed_jobs";
```
This will ensure that the failed job table has actually been deleted.

55
docs/contribute/docker.md Normal file
View File

@@ -0,0 +1,55 @@
# Build Docker image for Monica
If you want to build your own docker image for Monica, follow these steps:
## Use docker-compose to build and run your own image
Use this process if you want to modify Monica source code and build
your image to run.
Edit `.env` to set `DB_HOST=mysql` (as `mysql` is the creative name of the MySQL container).
Then run:
```sh
docker-compose -f docker-compose.dev.yml build
docker-compose -f docker-compose.dev.yml up
```
## Use Docker directly to run with your own database
Use this process if you're a developer and want complete control over
your Monica container.
If you aren't using docker-compose, edit `.env` again to set the `DB_*` variables to match your database. Then run:
```sh
scripts/docker/build.sh
```
You can add the tag name as a parameter:
```sh
scripts/docker/build.sh monica-dev
```
Run monica with:
```sh
docker run --env-file .env -p 80:80 monica-dev
```
Or run a command in the container:
```sh
docker run --env-file .env -it monica-dev bash
```
There's a bunch of [docker-compose examples here.](https://github.com/monicahq/docker/tree/master/.examples)
Note that uploaded files, like avatars, will disappear when you
restart the container. Map a volume to
`/var/www/monica/storage/app/public` if you want that data to persist
between runs. See `docker-compose.yml` for examples.
## Other documents to read
[Connecting to MySQL inside of a Docker container](/docs/installation/docker-mysql.md)
[Use mobile app with standalone server](/docs/installation/mobile.md)

365
docs/contribute/readme.md Normal file
View File

@@ -0,0 +1,365 @@
# Contribute as a developer <!-- omit in toc -->
- [Considerations](#considerations)
- [Design rules](#design-rules)
- [Install Monica locally](#install-monica-locally)
- [Homestead (macOS, Linux, Windows)](#homestead-macos-linux-windows)
- [Valet (macOS)](#valet-macos)
- [asdf (macOS)](#asdf-macos)
- [Instructions](#instructions)
- [Testing environment](#testing-environment)
- [Setup](#setup)
- [Run the test suite](#run-the-test-suite)
- [Run browser tests](#run-browser-tests)
- [Mocking HTTP calls](#mocking-http-calls)
- [Coding guidelines](#coding-guidelines)
- [Feature branch](#feature-branch)
- [Conventional commits](#conventional-commits)
- [Backend](#backend)
- [Things to consider when adding new code](#things-to-consider-when-adding-new-code)
- [Add a new table to the database schema](#add-a-new-table-to-the-database-schema)
- [Manipulating data during a migration](#manipulating-data-during-a-migration)
- [Email testing](#email-testing)
- [Email reminders](#email-reminders)
- [Statistics](#statistics)
- [Database](#database)
- [Connecting to mySQL](#connecting-to-mysql)
- [Front-end](#front-end)
- [Considerations](#considerations-1)
- [Mix](#mix)
- [Watching and compiling assets](#watching-and-compiling-assets)
- [CSS](#css)
- [JS and Vue](#js-and-vue)
- [Localization (i18n)](#localization-i18n)
- [Application](#application)
- [Laravel](#laravel)
- [VueJS](#vuejs)
Are you interested in giving a hand? We can't be more excited about it. Thanks in advance!
Notes:
* _we are doing everything we can to review pull requests submitted by the community as soon as possible. It can take days (or weeks) to finalize a review, going through rounds of changes, etc... This is why we kindly ask you to be patient during this process._
* _no changes are too small. If you want to contribute, even fixing a typo will help._
Here are some guidelines that could help you to get started quickly.
<a id="markdown-considerations" name="considerations"></a>
## Considerations
* Monica is written with a great framework, [Laravel](https://github.com/laravel/laravel). We care deeply about keeping Monica very simple on purpose. The simpler the code is, the simpler it will be to maintain it and debug it when needed. That means we don't want to make it a one page application, or add any kind of complexities whatsoever.
* That means we won't accept pull requests that add too much complexity, or written in a way we don't understand. Again, the number 1 priority should be to simplify the maintenance on the long run.
* It's better to move forward fast by shipping good features, than waiting for months and ship a perfect feature.
* Our product philosophy is simple. Things do not have to be perfect. They just need to be shipped. As long as it works and aligns with the vision, you should ship as soon as possible. Even if it's ugly, or very small, that does not matter.
<a id="markdown-design-rules" name="design-rules"></a>
## Design rules
* **Keep it simple**. No new options, please. Options are evil. It creates a bloated software. Not everything should be configurable.
* **Use what already exists in the current stack**. When adding a feature, do not introduce a new software in the existing stack. For instance, at the moment, the current version does not require Redis to be used. If we do create a feature that (for some reasons) depends on Redis, we will need all existing instances to install Redis on top of all the other things people have to setup to install Monica (there are thousands of them). We can't afford to do that.
* **Always think about the API**. When introducing new classes and concepts in the app, your changes should always be implemented as well. Everything that we do should be accessible through the API.
<a id="markdown-install-monica-locally" name="install-monica-locally"></a>
## Install Monica locally
<a id="markdown-homestead-macos-linux-windows" name="homestead-macos-linux-windows"></a>
### Homestead (macOS, Linux, Windows)
The best way to contribute to Monica is to use [Homestead](https://laravel.com/docs/homestead) as a development environment, which is an official, pre-packaged Vagrant box that provides you a wonderful development environment without requiring you to install PHP, a web server, and any other server software on your local machine. The big advantage is that it runs on any Windows, Mac, or Linux system.
This is what is used to develop Monica and what will provide a common base for everyone who wants to contribute to the project. Once Homestead is installed, you can pull the repository and start setting up Monica.
Note: the official Monica installation uses mySQL as the database system. 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/5.5/database#configuration) on that topic if you feel adventurous.
<a id="markdown-valet-macos" name="valet-macos"></a>
### Valet (macOS)
We've installed the development version with [Valet](https://laravel.com/docs/valet), which is a Laravel development environment for Mac minimalists. It works really well and is extremely fast, much faster than Homestead.
<a id="markdown-instructions" name="instructions"></a>
### asdf (macOS)
You can use [asdf](https://asdf-vm.com/#/) to install a version of php for monica:
```bash
asdf install
asdf reshim
pecl install redis
echo "extension=redis.so" > $(asdf where php)/conf.d/php.ini
```
You'll need to run the installation instructions below and setup a local mysql installation. After completing the application installation process you can run `php artisan serve` to get a local development server.
### Instructions
**Prerequisites**:
* Git
* [Node](https://nodejs.org/en/)
* PHP 8.1+
* [Composer](https://getcomposer.org/)
* GNU Make
**Steps to install Monica**
Once the above softwares are installed (or if you've finished the installation of Homestead/Valet):
1. Create a database called `monica` in your mySQL instance.
1. `mysql -e "CREATE DATABASE monica";` inside mySQL.
2. If you use Homestead (which uses Vagrant under the hood), `vagrant ssh` will let you login as root inside your VM.
2. Setup the application environment:
1. `composer install --no-interaction` to install all packages.
- Due to an issue with VirtualBox, you may encounter an error at this step due to a plug-in called `package-versions`. If this happens, delete the /vendor folder that was created and run `composer install --no-interaction --no-plugins --no-scripts` instead.
- See this [GitHub Issue](https://github.com/laravel/homestead/issues/1240) for more information.
- Run `cp .env.example .env` to create your own version of all the environment variables needed for the project to work.
2. `yarn install` to install all the front-end dependencies and tools needed to compile assets.
- If you experience an error related to `EPROTO: protocol error, symlink`, see [here](https://github.com/yarnpkg/yarn/issues/4908).
3. `yarn run dev` to compile js and css assets.
4. `php artisan key:generate` to generate an application key. This will set `APP_KEY` with the right value automatically.
5. `php artisan setup:test` to setup the database.
- By default this command will also populate the database with fake data.
- Use the `--skipSeed` option to skip the process of adding fake data in your dev environment.
6. `php artisan passport:install` to create the access tokens required for the API (Optional).
3. Update `.env` to your specific needs.
If you haven't skipped the seeding of fake data, two accounts are created by default:
* First account is `admin@admin.com` with the password `admin0`. This account contains a lot of fake data that will let you play with the product.
* Second account is `blank@blank.com` with the password `blank0`. This account does not contain any data and shall be used to check all the blank states.
To update a current installation with the latest dependencies, just run `make update` to run
1. `composer install --no-interaction`
1. `yarn upgrade`
1. `yarn run dev`
1. `php artisan migrate`
<a id="markdown-testing-environment" name="testing-environment"></a>
## Testing environment
We try to cover most features and new methods with unit and functional tests. Any pull request submitted on GitHub will have to go through Travis and pass before being merged. Moreover, we **strongly** encourage adding unit tests for every new method added to the codebase to ensure code stability, and we will probably refuse a pull request if there is no tests for it.
<a id="markdown-setup" name="setup"></a>
### Setup
To setup the test environment:
* Create a database `mysql -e "CREATE DATABASE monica_test;"`
* `php artisan migrate --database testing`
- If this fails due to the `oauth_auth_codes_table` already existing, edit `config/passport.php` to update the storage driver so `'connection' => 'testing'`, then run `php artisan migrate --database testing` again.
- For more information, see this [GitHub Issue](https://github.com/laravel/passport/issues/1370).
* `php artisan db:seed --database testing`
<a id="markdown-run-the-test-suite" name="run-the-test-suite"></a>
### Run the test suite
The test suite uses Phpunit. It's mainly used to perform unit tests or quick, small functional tests.
To run the test suite:
* `phpunit` or `./vendor/bin/phpunit` in the root of the folder containing Monica's code from GitHub.
<a id="markdown-run-browser-tests" name="run-browser-tests"></a>
### Run browser tests
Browsers tests simulate user interactions in a live browser.
* To run browser tests, first you need to install chrome
```sh
curl -sS -o - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt -y update
sudo apt -y -f install google-chrome-stable fonts-liberation libappindicator1
```
* Then you can run the test suite:
`php artisan dusk`
<a id="markdown-mocking-http-calls" name="mocking-http-calls"></a>
### Mocking HTTP calls
You should never make real HTTP calls in your unit tests - like querying an external API that is not linked to Monica.
You can mock http calls by mocking calls made by Guzzle.
You can find an example of how mocking is done in the `GetWeatherInformationTest.php` file.
You need to provide a sample response of the external call that you are mocking in the Fixtures folder.
<a id="markdown-coding-guidelines" name="coding-guidelines"></a>
## Coding guidelines
<a id="markdown-feature-branch" name="feature-branch"></a>
### Feature branch
We follow [GitHub Flow](https://guides.github.com/introduction/flow/) to manage the development of features.
<a id="markdown-conventional-commits" name="conventional-commits"></a>
### Conventional commits
We follow the [conventional commit message](https://conventionalcommits.org/) syntax for our commits. For instance, `feat: allow provided config object to extend other configs` or `feat(lang): added polish language`.
Every feature branch that is squashed onto main branch must follow these rules.
The benefits are:
* a standard way of writing commit messages for every contributor,
* a way to quickly see and understand what the commit does and what it affects,
* automatic changelog creation based on those keywords.
The keywords that support (heavily inspired by [config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)):
* `ci`,
* `chore`,
* `docs`,
* `feat`,
* `fix`,
* `perf`,
* `refactor`,
* `revert`,
* `style`,
* `test`.
Moreover, every commit message needs to be written in lowercase.
* ✅ feat(lang): added polish language
* ❌ feat(lang): Added polish language
All the commits in a pull request are squashed when merged into main branch. That means *only the commit message of the squashed branch needs to follow this commit message convention*. That also means that you don't need to follow this convention for commits within a branch, which will usually contains a lot of commits with a `wip` title.
<a id="markdown-backend" name="backend"></a>
## Backend
The project follows strict [object calisthenics](http://www.slideshare.net/guilhermeblanco/object-calisthenics-applied-to-php), as much as possible and more and more over time. We will soon implement those rules in the Linters and will block a pull request for the code that does not follow those guidelines.
Here are the rules (adapted for PHP):
* Only one indentation level per method,
* Do not use the "else" keyword,
* Do not chain different objects, unless if the execution includes getters and setters,
* Keep your entities small: 100 lines per class and no more than 15 classes per package,
* Any class that contains a collection (or array) cannot use any other properties,
* Document your code.
<a id="markdown-things-to-consider-when-adding-new-code" name="things-to-consider-when-adding-new-code"></a>
### Things to consider when adding new code
<a id="markdown-add-a-new-table-to-the-database-schema" name="add-a-new-table-to-the-database-schema"></a>
#### Add a new table to the database schema
If you add a new table, make sure there is a column called `account_id` in this new table. That way, we will make sure that the script responsible for resetting or deleting a user account will go take this new table into consideration while running.
<a id="markdown-manipulating-data-during-a-migration" name="manipulating-data-during-a-migration"></a>
#### Manipulating data during a migration
Sometimes you need to manipulate and move data around when you decide to change the database structure. In that case, as much as possible, do not use Eloquent to change the data. Use either [raw SQL queries](https://laravel.com/docs/5.5/database#running-queries) or the [Query builder](https://laravel.com/docs/5.5/queries) to do it. This is due to the fact that objects might change overtime or even be deleted, which would break the migrations entirely.
<a id="markdown-email-testing" name="email-testing"></a>
### Email testing
Emails are an important part of Monica. Emails are still the most significant mean of communication and people like receiving them when they are relevant. That being said, you will need to test emails to make sure they contain what they should contain.
For development purposes, you have two choices to test emails:
1. You can use [Mailtrap](https://mailtrap.io/). This is an amazing service that provides a free plan that is plenty enough to test all the emails that are sent.
1. You can use [mailhog](https://github.com/mailhog/MailHog) to test locally. On macOS, you can install via Homebrew (`brew install mailhog`). Then, run `mailhog` and point the browser to `http://127.0.0.1:8025` ([more complete instructions](https://github.com/maijs/homebrew-mailhog)).
1. If you use [Homestead](https://laravel.com/docs/homestead), [mailhog](https://github.com/mailhog/MailHog) is actually built-in. To use it, you first need to start mailhog (`sudo service mailhog restart`) inside your Vagrant. Then, head up to [http://localhost:8025](http://localhost:8025) in your local browser to load Mailhog's UI.
Note: if you want to use mailhog, you need the following settings in your `.env` file:
```
MAIL_MAILER=smtp
MAIL_HOST=0.0.0.0
MAIL_PORT=1025
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=
```
<a id="markdown-email-reminders" name="email-reminders"></a>
### Email reminders
Monica sends two types of emails: reminders, and notifications. Notifications are sent 7 and 30 days before an event happens, while reminders are sent the day the event happens.
Reminders are generated and sent using an Artisan command `send:reminders`. Notifications are sent using `send:notifications`. Those commands are scheduled to be triggered every hour in `app/console/Kernel.php`.
<a id="markdown-statistics" name="statistics"></a>
### Statistics
Monica calculates every night (ie once per day) a set of metrics to help you understand how the instance is being used by users. That will also allow to measure growth over time.
Statistics are generated by the Artisan command `monica:calculatestatistics` every night at midnight and this cron is defined in `app/console/Kernel.php`.
<a id="markdown-database" name="database"></a>
## Database
As said above, Monica uses mySQL by default. While Laravel supports multiple DBMS, we can't assure you it will work with any other DBMS than mySQL.
<a id="markdown-connecting-to-mysql" name="connecting-to-mysql"></a>
### Connecting to mySQL
If you want to connect directly to Monica's MySQL instance read [_Connecting to MySQL inside of a Docker container_](./docs/database/connecting.md).
<a id="markdown-front-end" name="front-end"></a>
## Front-end
<a id="markdown-considerations-1" name="considerations-1"></a>
### Considerations
* If your contribution involves a change in the UI (even if it's very small), please ping @djaiss in an issue *before* you start working on it, explaining what you want to achieve, why and how. We want to maintain a high level of visual quality in the software and we will dismiss all pull requests that change the front end that have not been discussed before-hand.
* That being said, we'll probably receive pull requests that change the front end before any previous discussion on the topic. In this case, we do not guarantee that we'll accept the pull request, but in order to increase the chances that it will:
* Make sure to follow the current visual style and layout.
* Make sure you do not introduce new colors in the UI.
* Make sure the user experience is consistent with the rest of the application (ie buttons behave the same, modals are like other modals,...).
* Make sure you don't introduce new CSS classes, unless they are absolutely necessary. Use the classes provided by [Tachyons](https://tachyons.io) which is the functional CSS framework we currently use.
* Do not use Jquery. When needed, use VueJS.
The above comments can seem harsh and we apologize in advance. However you have to understand that we deeply care about providing the best user experience to our users. Features that are purely backend do not have the same impact as the ones that the user interacts with. Features that modify the front end will have a tremendous impact on how users perceive the software. Therefore we want to make sure that anything that touches the frontend is perfect and aligned with our vision.
<a id="markdown-mix" name="mix"></a>
### Mix
We use [mix](https://laravel.com/docs/5.5/mix) to manage the front-end and its dependencies, and also to compile and/watch the assets. **Please note that we should do our best to prevent introducing new dependencies if we can prevent it**.
Mix should be available in your development environment if you have installed Monica locally and ran `yarn install` in the first place.
If you need to add a new dependency, update `package.json` to add it and make sure you commit `package-lock.json` once `package.json` is updated.
<a id="markdown-watching-and-compiling-assets" name="watching-and-compiling-assets"></a>
### Watching and compiling assets
CSS is written in SASS and therefore needs to be compiled before being used by the application. To compile those front-end assets, use `yarn run dev`.
To monitor changes and compile assets on the fly, use `yarn run watch`.
<a id="markdown-css" name="css"></a>
### CSS
At the current time, we are using a mix of Bootstrap 4 and [Tachyons](https://tachyons.io). We aim to use [Atomic CSS](https://adamwathan.me/css-utility-classes-and-separation-of-concerns/) instead of having bloated, super hard to maintain CSS files. We'll get rid of Bootstrap entirely over time.
This means that we should add new CSS classes only if it's absolutely necessary.
<a id="markdown-js-and-vue" name="js-and-vue"></a>
### JS and Vue
We are using [Vue.js](https://vuejs.org/) in some parts of the application, and we'll use it more and more over time. Vue is very simple to learn and use, and with [Vue Components](https://vuejs.org/v2/guide/components.html), we can easily create isolated, reusable components in the app. If you want to add a new feature, you don't need to use Vue.js - you can use plain HTML views served by the backend. But with Vue.js, it'll be a nicer experience.
<a id="markdown-localization-i18n" name="localization-i18n"></a>
### Localization (i18n)
<a id="markdown-application" name="application"></a>
#### Application
Localization of the application is handled by the [default i18n helper provided by Laravel](https://laravel.com/docs/5.5/localization). When adding or modifying strings, you only have to handle the `en` language, which is stored in `resources/lang/en/`. The other locales are going to be handled by Crowdin, our translation platform.
We also have [a dedicated page](/docs/contribute/translate.md) for our translators, just in case you need it.
<a id="markdown-laravel" name="laravel"></a>
##### Laravel
We use the default Laravel helper: `trans('app.save')`.
<a id="markdown-vuejs" name="vuejs"></a>
##### VueJS
For everything that is in VueJS though, things are a bit different. We have to use a special library to allow translated strings to be available in the javascript views. The helper in Vue is slightly different.
You can use these replacements instead of the regular (php) definition:
* `trans('file.string')` is written `$t('file.string')`.
* `trans('file.string', ['param' => $value])` is written `$t('file.string', {param: value})`.
* `trans_choice('file.string', $count)` is written `$tc('file.string', count)` or `$tc('file.string', count, {param: value})`.
Important note: every time a string changes in a translation file, you need to regenerate all the strings so they can be made available in JS. To do this,
* use `php artisan lang:generate`
* then compile all the JS assets `yarn run prod`, and commit the whole.

70
docs/contribute/translate.md Normal file
View File

@@ -0,0 +1,70 @@
# External translators <!-- omit in toc -->
- [Crowdin](#crowdin)
- [Support a new language](#support-a-new-language)
- [Rules](#rules)
- [With Laravel](#with-laravel)
- [With Vue.js](#with-vuejs)
- [Rules for translation](#rules-for-translation)
- [Punctuation](#punctuation)
First of all, thanks a lot for considering helping the project by translating it. We truly appreciate it.
## Crowdin
All translations are done with [crowdin](https://crowdin.com/project/monicahq) - we'd like to thank them for their gracious help with this project by providing us a free account.
## Support a new language
You can [open an issue](https://github.com/monicahq/monica/issues/new) to request a new language.
⚠️ Do not edit languages file directly.
To enable a new language in Monica:
* we have to configure it in Crowdin first. This is something we must do ourselves (we: members of the project). To do it, we need to go to Settings > Translations > Target Languages and add the new locale here.
* add the name of the language in [the main English settings file](https://github.com/monicahq/monica/blob/main/resources/lang/en/settings.php).
* update the [lang-detector.php file](https://github.com/monicahq/monica/blob/main/config/lang-detector.php) by adding the new locale abbreviation (please add it in alphabetic order).
* add the locale in the [webpack.mix.js file](https://github.com/monicahq/monica/blob/main/webpack.mix.js) (please add it in alphabetic order).
* (optional) when adding a country-specific language (like 'en-GB'), you may need to update the [crowdin.yml config file](https://github.com/monicahq/monica/blob/main/crowdin.yml).
Then, submit your PR for review. A good example of adding a new locale can [be found here](https://github.com/monicahq/monica/pull/3356).
## Rules
Translation appears in two types of files in the codebase: in Laravel (php) and VueJS.
### With Laravel
- **simple string**
- **string with parameters**: see [laravel doc](https://laravel.com/docs/5.6/localization#replacing-parameters-in-translation-strings).
To translate: integrate the text replacement in your translation, like ":param".
Example: `:name’s birthday` => `anniversaire de :name`
- **plural forms**: see [laravel doc](https://laravel.com/docs/5.6/localization#pluralization) for documentation. It supports basic and occidental plural variations, each one being defined in [here](https://github.com/laravel/framework/blob/5.6/src/Illuminate/Translation/MessageSelector.php#L110).
Example: `1 message|:count messages` => `:count message|:count messages`, or: `{1}:count message|[2,*]:count messages`
- **format strings**: we use [Carbon](http://carbon.nesbot.com/docs/#api-commonformats) to handle dates. [format.php](https://github.com/monicahq/monica/blob/main/resources/lang/en/format.php) file contains format we use to export dates as strings in the right localized format. See [php doc](http://www.php.net/manual/en/function.date.php) to know which format you can use.
### With Vue.js
We use the [vue-i18n](https://www.npmjs.com/package/vue-i18n) package.
- **simple string**
- **string with parameters**: see [vue-i18n doc](http://kazupon.github.io/vue-i18n/en/formatting.html#html-formatting).
- To translate: integrate the text replacement in your translation, like `{param}`.
- Example: `{name}’s birthday` => `anniversaire de {name}`
- Other example: `{{ $t('people.stay_in_touch_frequency', { count: frequency }) }}`
- **plural forms**: See [vue-i18n doc](http://kazupon.github.io/vue-i18n/en/pluralization.html).
Pluralization is customized in the [pluralization.js](https://github.com/monicahq/monica/blob/main/resources/js/pluralization.js) file. This should fit your language pluralization form. Messages must be separated by a pipe, but you cannot define the number of occurrences it applies to like with Laravel translation (no brackets or braces).
Example: `1 message|{count} messages` => `{count} message|{count} messages` in French, or: `{count}条消息` in Chinese (only 1 form)
## Rules for translation
Please respect typographic rules in your language.
### Punctuation
See https://en.wikipedia.org/wiki/Punctuation
- [Apostrophe](https://en.wikipedia.org/wiki/Apostrophe): use real apostrophe character `’` instead of simple quote `'`
- [Quotes](https://en.wikipedia.org/wiki/Quotation_mark): use real quotation marks like `“ ”` or `« »` instead of double quote `"`
- [Dash](https://en.wikipedia.org/wiki/Dash): use en dash `—` instead of hyphen `-` when it’s necessary
- [Interpuct](https://en.wikipedia.org/wiki/Interpunct) for separate some lists: `·`

BIN
docs/images/carddav_davx5_1.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
docs/images/carddav_davx5_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/images/carddav_token1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 KiB

BIN
docs/images/carddav_token2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.1 KiB

BIN
docs/images/carddav_url.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.7 KiB

BIN
docs/images/heroku_dashboard-resources.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/images/heroku_dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/images/heroku_manage_app.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 710 B

BIN
docs/images/logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/images/main-app.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

BIN
docs/images/screenshot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
docs/images/windows10_contacts_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

BIN
docs/images/windows10_contacts_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

BIN
docs/images/windows10_contacts_3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/images/windows10_wheel.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 445 B

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.

40
docs/readme.md Normal file
View File

@@ -0,0 +1,40 @@
# Monica Documentation
Welcome to Monica - a great, simple yet complete, open-source personal relationship manager platform.
This doc is the main source of documentation for developers working with (or contributing to) the Monica project, and advanced users who want to install Monica on their servers. If this is your first time hearing about Monica, we recommend starting with [Monica website](https://monicahq.com).
## Table of content
* [Use Monica](/docs/user/readme.md)
* Install Monica on your server
* [Install a new instance](/docs/installation/readme.md)
* [Maintain your server](/docs/installation/update.md)
* Contribute to Monica
* [Contribute as a developer](/docs/contribute/readme.md)
* [Help translate the application](/docs/contribute/translate.md)
**Specific to Monica's core contributors**
* [Add content](/docs/administrators/tips.md)
* [Deployment instructions](/docs/administrators/deployment.md)
## Thanks to companies and open source projects
The Monica project is extremely grateful for the help provided by the following companies and open source projects.
### Companies
Those companies have graciously offered a paid plan for free.
| **Supported by** | **Description** |
|----------------------------------|-----------------------------------------------------------------------------------------------|
| Sentry | [Sentry](https://sentry.io) is a cross-platform crash reporting and aggregation platform. We use it to analyze what's going on in production. |
| Crowdin | [Crowdin](https://crowdin.com/project/monicahq) is a translation platform. |
| Cypress | [Cypress](https://dashboard.cypress.io/projects/q8h6k9/runs) is an end-to-end test platform. |
### Open source projects
Monica is built upon the shoulders of incredible open source projects. We simply wouldn't exist without them.
* [Laravel](http://laravel.com/)
* [Git](http://git-scm.com/)
* [Linux](http://linux.org/)

146
docs/user/carddav.md Normal file
View File

@@ -0,0 +1,146 @@
# CardDAV and CalDAV <!-- omit in toc -->
**Using Monica as a CardDAV and CalDAV server**
- [Authentication](#authentication)
- [CardDAV and CalDAV urls](#carddav-and-caldav-urls)
- [Clients](#clients)
- [Android](#android)
- [iPhone](#iphone)
- [Apple iOS](#apple-ios)
- [Thunderbird](#thunderbird)
- [Windows 10 Contacts application](#windows-10-contacts-application)
- [Outlook (Microsoft Office)](#outlook-microsoft-office)
CardDAV is a protocol based on WebDAV, allowing you to **synchronize your contacts** between multiple devices (mobile phone, mail software, etc.).
CalDAV is pretty much the same, with Calendars. In Monica it allows you to synchronize the birthdays anniversary of your contacts, and the task list (which uses the same CalDAV protocol).
CardDAV and CalDAV for Monica are implemented with [sabre/dav](https://sabre.io/) library.
## Authentication
To authenticate with the server, you'll need to create an API token.
Go to the [Settings > API](https://app.monicahq.com/settings/api) page, and Create a new token.
![Create a token](/docs/images/carddav_token1.png)
![Create a token](/docs/images/carddav_token2.png)
Save this token to authenticate with CardDAV and CalDAV.
The login is your email login.
## CardDAV and CalDAV urls
On the [Settings > DAV Resources](https://app.monicahq.com/settings/dav) page of your instance you will find some help about the URL to use.
**In most of the cases, the base url should work.** So just copy/paste it to your client app to see the magic happen !
![Base url](/docs/images/carddav_url.png)
## Clients
This is some example of clients configuration.
This list is not exhaustive, as the synchronisation can work on every CardDAV compatible device.
### Android
Android devices do not support CardDAV natively, so you'll need to install a third-party application to use CardDAV.
We recommend installing [DAVx5](https://www.davx5.com/) which is a great CardDAV client. You will find the application on the [Google Play store](https://play.google.com/store/apps/details?id=at.bitfire.davdroid) or even on [F-Droid store](https://f-droid.org/fr/packages/at.bitfire.davdroid/) for free.
To add an account:
- Click on the `+` button
- Choose **Connection with URL and username.**, and enter the following details:
- **URL**: Enter the `/dav` base url, i.e. `https://app.monicahq.com/dav`
- **Username**: Your email login address
- **Password**: The token you've created on the API settings page.
![Davx5 config](/docs/images/carddav_davx5_1.png)
- Chose the option **Groups are per-contact categories**
- Click on **Connect**
- Select the data you want to sync
After that, you can use any Contacts application on your phone. Be sure to display your Monica account on the list of contacts, and to use it by default for new contacts.
### iPhone
### Apple iOS
### Thunderbird
[Thunderbird](https://www.thunderbird.net) supports CardDAV natively as of version 91.
For older versions, or enhanced functionality, we recommend installing [CardBook](https://addons.thunderbird.net/thunderbird/addon/cardbook/).
Download the add-on and install it through Thunderbird's add-on manager.
To add an account:
- Create a new Address Book.
- Choose **Remote**
- Choose **CardDAV** and enter the following details:
- **URL**: Paste the `/dav` base url, i.e. `https://app.monicahq.com/dav`
- **Username**: Your email login address
- **Password**: The token you've created on the API settings page.
- Click **Validate** to check the credentials, then click on the **Next** button
- You can now see the address book, and the color to associate with. Select `4.0` as vCard format if you want.
- Click **Next** and **Finish**
### Windows 10 Contacts application
Windows 10 Contacts application support CardDAV. It is used to synchronize iCloud kind account.
- Open **Contacts** application
- Click on **Import contacts** or **Add an account** on the parameters
- Choose **iCloud** account kind and enter the following details:
- **User name**: your Monica email login address
- **Name**: enter your full name
- **Password**: write some scrap (do **not** enter Monica credentials for now)
![](/docs/images/windows10_contacts_1.png)
- Click on **Connect**, then **OK**
After this step, the application will try to synchronize with iCloud servers. It will fail, but it's normal as we don't have an account on it.
Fix the settings:
- Open the **Mail** application
- Open on the wheel ![wheel](/docs/images/windows10_wheel.png) to go to the settings. If the settings are not reachable, add a fake POP, IMAP account
- Click on your Monica account settings — it is named _iCloud_ at this point — and select **Change parameters**
- Enter the following details:
- **User name**: your Monica email login address
- **Password**: The token you've created on the API settings page
- **Account name**: enter the description for this account, like "Monica"
![](/docs/images/windows10_contacts_2.png)
- Click on **Change mailbox sync settings, Options for syncing your content**, and change the following settings
- **Download new email**: select `manually` as we don't sync emails here
- **Sync options**: unselect **Email**, and select **Calendar** and **Contacts**
- Click on **Advanced mailbox settings, Contacts (CardDAV) and Calendar (CalDAV) server settings**, and change the following settings
- **Incoming email server**: enter `localhost`
- **Outgoing (SMTP) email server**: enter `localhost`
- **Contacts server (CardDAV)**: Paste the `/dav` base url, i.e. `https://app.monicahq.com/dav`
- **Calendar server (CalDAV)**: Paste the `/dav` base url, i.e. `https://app.monicahq.com/dav`
![](/docs/images/windows10_contacts_3.png)
- Click on **Done** button, then **Save**
Your contacts and calendar are now syncing.
- On **Contacts** application, be sure to display your Monica contacts account on the **Filter**
- On **Calendar** application, display your Contacts' Anniversary calendar
### Outlook (Microsoft Office)

12
docs/user/readme.md Normal file
View File

@@ -0,0 +1,12 @@
# Use Monica <!-- omit in toc -->
Monica is a personal relationship manager platform.
It helps you organize the social interactions with your loved ones.
You can use a bunch of nice [features](https://www.monicahq.com/features), or use our [API](https://www.monicahq.com/api).
See the recent [changelog](https://www.monicahq.com/changelog) to track every changes with it.
See documentations about:
- [Setup your phone, or desktop app to sync contacts](carddav.md)
- [Enhance security of your account](security.md)

8
docs/user/security.md Normal file
View File

@@ -0,0 +1,8 @@
# Security
If the option is set, you can add a [Multi Factor Authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication) device to secure your connection.
You can either:
- add a 2FA security device, using an OTP application on your mobile phone
- or add a [Security Key](https://en.wikipedia.org/wiki/Universal_2nd_Factor) key. Monica provides [WebAuthn](https://en.wikipedia.org/wiki/WebAuthn) support. It's supported on most recent browsers. Be aware the instance must run in `https`.