# Welcome to Monica
Monica is an open-source personal CRM. It lets you document your life and your contacts. We've been doing this project since 2017 as a side project, and it has grown beyond our expectations.
It is accessible from .
### Personal CRM?
A CRM is a Customer Relationship Management software. It is used in the sales world to keep track of who you've spoken to, who's ready to buy your stuff and follow up during the entire customer lifecycle. A CRM however, is not suited for documenting your contacts or your life, although the intention is similar. A personal CRM is a set of tools that let you mimic this behaviour and document your personal contacts, but not in a business context.
### **Open source?**
**Open-source** means that the code is free, and freely available for everyone to read or change. The code [is available on Github](https://github.com/monicahq/chandler).
It also means that Monica can be host by anyone **for free**, on your server or wherever you want. We provide an official Docker image for the software that you can use, and we also have a bunch of other non official installation methods. The only thing that you can't do is try to make money out of it. Apart from that, there is no limitations.
In fact, even this documentation is open source and [hosted on Github](https://github.com/monicahq/docs-gitbook). If you see something that seems wrong, or inaccurate, you can update its content yourself and request a change.
### Side project
Monica is born out of our passion to work on tools that improve people's lives. We, the authors ([Regis](https://twitter.com/maazarin) and [Alexis](https://twitter.com/asbin)) as well as the hundred of contributors around the world, work most of the evenings and weekends on this project.
We aim to offer a tool that everyone can use to their advantage. Hearing your stories about how Monica improved your life brings us immense joy.
We’re not a typical project. We don’t prioritize revenue or marketing—we care about our users and whether our project is useful, cool, and fun. Other founders might focus on the amount of money they’ve raised, but we measure success by the number of stars our GitHub repository has. We want to create a tool that people love and find cool.
The primary benefit of Monica being a side project is the heightened creativity and freedom it offers. Side projects are not tied to the same commercial demands as traditional business projects, allowing us to explore new concepts and take risks we may not have taken otherwise. It also provides more autonomy and control over the project’s direction and outcome. We are only accountable to our users (and ourselves).
# Meet Monica
## Key concepts
Monica strives to document people’s lives. Your life is composed of events that occur to you and interactions with those close to you, both personally and professionally. By recording what happens to you and to others, we believe we can significantly enhance your life.
At its core, Monica has a few key concepts:
* [accounts](/getting-started/accounts)
* [vaults](/vaults/introduction)
* contacts
When users register for Monica, they create an account. This account is the foundation for managing all their data. The person who creates the account is the first administrator. If desired, additional administrators can be added later. Other users can also be added to the account, but they won’t have the same privileges as administrators, which prevents them from making unwanted changes.
Vaults host users’ data, such as contacts and documents. An account can have multiple vaults. Vaults are private within an account, so other users in the account, even if they are administrators, cannot read the data in a vault unless they are part of that vault. They cannot even see that the vault exists.
A contact is the core data of Monica. It's someone you know (or think you know). A contact lives inside a vault. Monica lets you document everything about this contact, including their social graph: children, family, and so on.
The idea is for you to create contact sheets for each of the people you want to document in your life. Every piece of information you want to remember about the contact can then be added to the contact entry in Monica.
## Principles
Your life is one-of-a-kind. Nobody else in the entire universe has the same life and values as you. That’s why we created Monica based on these values:
* We do not discriminate based on race, color, religion, gender, national origin (ancestry), disability, marital status or sexual orientation. Everything we do at Monica is in support of this commitment. We do not judge.
* Customizable: We believe every piece of information in Monica should be tailored to your preferences. Whenever possible, we let you personalize your experience based on your lifestyle.
* Monica is simple and powerful. It’s easy to use for everyone, even those without technical skills. And if you need more power, we provide tools to customize it to your needs.
* Monica is and always will be open source. Everyone can read the source code and contribute to make the software better. However, not all contributions will be accepted. We care deeply about the experience we offer our community and may reject contributions that don’t align with our vision. If you’re unsure, please ask us before submitting.
* Private: Monica is for you alone. Your data is yours. We don’t display ads and never will. We have never sold your data and never will. We have never done so and never will.
# Accounts
## What is an account?
In Monica, an account serves as the central repository for all your information. This includes vaults, which in turn house your contacts. Simply put, an account is the foundation upon which Monica is built, allowing you to organize and access your data with ease.
## How do we create an account?
To use Monica, you need an account. To create an account, a few information are required:
* the full name
* a valid email address
* a password.
{% hint style="info" %}
**Why do we require a valid email address?** We do not spam. Your email address is not used for any marketing purposes whatsoever. We have never done it, and never will.
That being said, we still need to make sure that you are not a bot, and that we will be able to send you reminders that will arrive in your inbox safely. That's as simple as that.
{% endhint %}
The full name is necessary since we will create a contact entry that represents you in the system.
When you create an account, you will be asked to create your first vault, and we'll create your first contact inside this vault. The name that you use on the signup form will be used to create this first contact.
You can have as many users as needed in an account. We have a [dedicated documentation about managing users](/user-and-account-settings/manage-users) if you need more information on that part.
## Accounts are populated with default options
Upon creating an account, you can quickly get started with Monica thanks to its pre-loaded default settings. This means you can be up and running in a matter of seconds, without the need for extensive setup or configuration.
For instance, genders are already defined, as well as pronouns, relationship types, and a lot of other options.
These default settings are what most people would want to have in a tool like Monica.
**You are not stuck with these defaults**. At Monica, we understand that documenting one’s life is a highly personal endeavor. That’s why we’ve gone to great lengths to ensure that you have complete control over every aspect of your account. With Monica, you have the ability to customize every detail to your liking, allowing you to create a truly personalized experience.
# Introduction
In Monica, vaults serve as the central repository for your private data, including contacts, documents, photos, journal entries, and more. Without a vault, you cannot store any information in Monica. By organizing your data into vaults, you can easily manage and access your information in a structured and secure manner.
Vaults are private by design.
Inside the same account, users who not part of a vault can't see the content of a vault, even if they are administrators of the account.
Creating a vault is the first step every new user of Monica should do.
There are no limits on the number of vaults in an account. The typical use case, though, is to have one vault per user in the account, and possibly a shared vault as well.
### A note about vault visibility and permissions
A vault can have one or more users. Those users must be in the same account.
If you are not part of the vault, you can’t access it – and you can’t even see the vault on your dashboard.
Let's be clear: **even if you are the account administrator, you won’t be able to access a vault if you are not part of that vault**. And you won’t see the vault on your dashboard as well.
This makes vaults super flexible. For instance, if you are part a family, you can have your own vault with your work contacts, your spouse can have her own vault and you can have a shared vault with data that need to be shared.
# Customizing a vault
## Introduction
Monica’s vaults offer a wide range of features, and you may find that some are more relevant to your needs than others. Fortunately, you have complete control over which features you use, and can choose to show or hide them as desired. This allows you to tailor your experience to your specific needs and preferences, ensuring that you can work efficiently and effectively within the vault.
There are also some settings that are unique to a vault, while other settings are account-wide.
**Why are not all settings account-wide?**
Some settings should affect everything in an account, while some settings should only have an effect on a specific vault.
## Vault settings
### Manage vault users
There are several pieces of data that you should keep an eye on:
1. Contacts that were last updated.
2. Reminders in the next 30 days.
3. Open tasks.
## Last updated contacts
This widget contains the last 5 contacts that were updated by any users in the vault. Updating means any information that was added, edited or removed in the contact entry.
There is no way to define the number of contacts that are shown here.
# Dashboard
# Journals
## Introduction
Monica, as stated in our [introduction page](/getting-started/readme-1), is about documenting your life. It lets you document your contacts, but it should also let you document what you do with your life. Journals let you do that.
In Monica, a journal is a personal diary that you can use to document anything you wish. We understand that journals are deeply personal, and that’s why we’ve designed a flexible structure that allows you to format your journal in any way you choose. Whether you prefer to document your life through daily entries, or use a structured format like a travel journal with entries for each day, Monica can accommodate your needs.
Additionally, you can create predefined content for each entry, giving you even more control over the structure and content of your journal. With Monica, the possibilities are endless, and you are only limited by your imagination.
### Differences with other diary apps
We believe Monica is in a unique position to offer something drastically different from any other diary applications out there. Monica is a tool to document your life, including your contacts. We offer some great tool to let you write down what you do with your contacts.
Now imagine an application where you can mix your contact's data with a journal. Every post you write can be linked to a contact. Every activity you do can be linked to a journal entry.
With Monica, you can have an extremely tight integration with all your contacts. No other apps can do that.
### Posts, templates and sections
To understand all the possibilities of the journal in Monica, you have to understand its structure, as it's a tiny bit complex.
A journal has **posts**. A **post** is the core of your journal, obviously. This is where you write things down.
A post follows a **template**. A **template** represents the structure of a post.
Your Monica account comes with a **default template**, that you can't modify or delete. The default template is composed of a title, and the body of the post.
However, you can create **other templates** that have a different structure. Imagine you want to document a road trip. Or you want to ask yourself a set of questions every day: for instance, how did you feel today, or what are the five positive things that you've done today.
Templates allow you to do that. In each template, you can add **sections**. A section is one part of a post, and will have a name that you will see when you create the post.
For instance, if you want to document a trip, you can have a template called *Trip* which will have the following sections:
* New food you've eaten today
* Things you've done
* People you've meet
If you want to follow a positive mindset and use the journal to help you be more positive, you could have a template called *Positive attitude* with the following sections:
* What will I do today to make it great?
* 3 things I'm grateful for
* etc...
This makes it a very flexible structure that let you have the kind of posts that you want, and make your journal unique to you and your needs.
## Managing journals
### Creating a journal
[A vault](/vaults/introduction) can have as many journals as you want.
To create a journal, head over the vault, and click on the Journals link in the menu.
{% hint style="info" %}
A journal can be read by anyone who has access to the vault. However, only contributors and administrators of the vault can manage the journal or the posts.
{% endhint %}
To create a vault, you need:
* a name,
* and optional description.
\[IMAGE]
## Customizing posts
As [explained above](#posts-templates-and-sections), posts are not limited to a single structure. You can customize the structure at will, and define a structure per post. This is what we call **post templates**.
Monica comes by default with a template that you can't delete or modify. This is the base template, which contains a text area, and that's it. This is a post in its most basic form.
It also comes with another type of inspirational template. This one can be modified or even deleted if you want.
However, you can create other post templates, and make them as complex as you want them to be, matching your needs.
Monica comes with two default templates
### Creating a post template
To create a post template, head over to the `Settings / Personalize your account / Post templates` section.
Click on the Add a post template above and give the template a name.
### Managing post templates
Once the template has been created, you can edit it to manage **post sections**. A post section is simply a part of the post. You can have as many sections in a post as needed.
A post template needs **at least** one post section. If a post has no section, there will be simply no place for you to enter any text, therefore defeating the purpose.
To prevent that from ever happening, a post template comes with one post section that you can't delete.
Each post section can have a **label**. Those labels will be displayed when you create a post. However, if a post template has only one section, the label won't be displayed.
You can reposition sections by drag and dropping each section inside a template.
### Deleting a post template
You can choose to delete a post template any time you want.
{% hint style="success" %}
It's important to understand that deleting a post template won't delete all the posts that match this template. Once a post is created with a template, it will keep this template forever – even if the template is deleted. This is to make sure that no content is ever deleted from your posts.
{% endhint %}
To delete a post template, head over to the `Settings / Personalize your account / Post templates` section, and click on the Delete button next to a post template.
# Introduction
We’ve learned over the years that people want to customize their Monica experience. It’s deeply personal, and everyone’s needs are different. That’s why we take pride in allowing every part of Monica to be tailored to each individual.
Yes, that makes building the product more complicated, but the benefits for the users are immense. Monica is a true personal CRM, and we don't dictate how the product should be used.
This is where the Settings page on Monica truly shines - you will be able to customize almost everything in the product.
Settings are divided into two categories:
* User settings
* Account settings
{% hint style="info" %}
**User settings** apply only to the logged in user.
**Account settings** apply to everyone on the account.
{% endhint %}
User settings can only be changed by the logged in user. Account settings can only be changed by users with account administration permissions.
# Manage currencies
There are several parts in Monica where you can indicate a currency (loans, for instance). There are [many, many currencies](https://en.wikipedia.org/wiki/List_of_circulating_currencies) in the world – 130 in fact. There are very good chances that you don't need all those currencies in your account, even though Monica supports them all.
In your `Settings > Personalize your account > Currencies` page, you can enable or disable the currencies you want to use in your account. Every user in the account will inherit these settings.
You can also disable them all, or enable them all. It's up to you.
If you disable a currency that were previously used, for instance in a loan, your currency will still be available when editing this loan.
# Notification channels
Monica lets you setup reminders. You can read more about reminders here.
Reminders, by nature, are meant to be sent somehow, once they are triggered. Monica provides several ways for all users in the account to be notified: via email and Telegram for now, and perhaps in the future: Messenger, Teams, Slack, SMS.
We call this a notification channel. You, as a user, can setup as many notification channels as you like. Also, each user in the account will have different notification channels. It's up to each user of an account to setup their own notification channels.
By default, upon account creation, each user will have to register an account with their email address. This email address will be used as the first notification channel for this user in the account. You can, of course, disable this notification channel if you so desire.
### Email notification channel
Email is the most natural notification channel. You can define as many emails as you want, and reminder will be sent to each defined email address.
For each email address, you can indicate the precise hour and minute you would like to receive the notification the day the reminder is supposed to be sent. This time will take your timezone into account, if it's defined, of course.
#### Anatomy of the notification channel list
#### Adding a new email address
To add a new email address, click on the Add an email button.
* You need to specify the email address. The email address should not be used in the account already.
* You need to specify a label for this address. This is like a friendly name that we will use to identify the email address.
* You need to indicate the time for when you would like to receive the notification.
Once this is setup, Monica will send a verification email to this email address, so we know that you own it. No reminders will be sent to the address if it's not verified first.
#### Deleting an email address
You can delete an email address. Once it's deleted, you'll stop receiving notifications to that address entirely.
#### Activating/deactivating an email address
Sometimes, you want to be able to deactivate an email address from receiving a notification. Simply click on Deactivate to do so. If it's deactivated, no notification will be sent. You can reactivate it anytime you want.
### Send tests and logs
If you want to test a notification channel, you can send a test notification and your channel should receive it, regardless of what the channel is. This lets you verify that the channel actually works.
Another useful tool is the ability to see the logs of all the notifications we have sent through the given notification channel. For instance, the email notification channel logs page looks like the following:
We keep the history of all the logs that have been sent forever, unless the notification channel is deleted - in this case, logs will be also lost forever.
# Manage users
In Monica, we support multiple users per account. Users can have two different permissions:
* administrator: they have the ability to manage other users, manage billing and manage account settings
* regular user: they have the ability to create their own vaults and do whatever they like with them
### Adding users
Adding users to your account in Monica can only be done by an account administrator. The flow for adding users is simple:
* you need to enter an email address where the invitation will be sent to.
* you need to indicate which permission the user will have.
* you click on Send, and if the email address is valid, the person will receive a link that will allow them to create their account.
Note that the email address of the person should not already exist in Monica by someone else, even in another account.
Once the invited user clicks on the invitation link, this is the form that they will have to complete.
### Deleting users
Deleting users in Monica is a little bit complex as it follows a certain set of rules:
* only administrators can delete another user
* as an administrator, you can't delete yourself
There are also additional rules about vaults. When you delete another user, Monica will delete all the vaults where:
* the given user is the manager of the vault
* and the vault has no other vault managers other than the given user
{% hint style="warning" %}
To be clear: all the vaults for which the user was the sole manager of will be completely deleted. For all the other vaults, the user will simply be removed from the vault.
{% endhint %}
To delete a user, you need to use the Delete option on the `Settings > Manage users` screen.
Deleting a user happens immediately.
# Manage preferences
In the Settings section, every user in the account can customize their account in order to match their taste. This happens under `Settings > User preferences`.
{% hint style="info" %}
Each setting under this section is defined per user, and won't affect other users of the same account.
{% endhint %}
### Help display
While we hope Monica is easy to use and doesn't need any explanation, there might be some time where you will want to have more information about a feature. This is exactly why we have this documentation portal.
We've tried to write some help documentation for every feature. Next to each feature, we've added a little question mark, as shown below.
An example of the question mark linking to the documentation
Clicking on a link will send you to the right place in the documentation.
For advanced users, this might not be an option that you will use. This is why we've included the possibility to hide the help link completely in the user interface.
### Language
Monica's original language is in English, but our community has translated the application into other languages. You can change the language whenever you want, and the change will take effect immediately.
{% hint style="info" %}
While we do our best for the translations to be accurate, sometimes they are simply not.
This is because we rely on two things for the translations:
* some of them are done automatically by either ChatGPT or Google Translate,
* the other ones are done by humans who speak the language.
We can't guarantee that what you read means actually what it's supposed to mean, because of the two reasons above. We are deeply sorry if a translation is offending to you or your culture, this is 100% not our intention.
If you do find errors, please contact us with the errors and we'll fix them.
{% endhint %}
### Customize contact names[](https://docs.monicahq.com/docs/account-settings/manage-preferences#customize-contact-names)
In the US, contacts are represented by ``, like James Bond. However, not everyone lives in the US, and the way names should be ordered is different amongst the different cultures on Earth.
We want Monica to be as flexible as possible, so we invented a way, perhaps a bit complex, to let you manage this at your leisure.
Under `Settings > User preferences`, you can define how Monica should represent names for you.
{% hint style="success" %}
This setting is a personal setting, not an account-wide setting. The way names should be represented is not necessarily the way other users in the same account want to see how names should be displayed. In the same account, users can have different ways of displaying contact names.
{% endhint %}
#### Use a preset
By default, users can use one of the presets we've put at your disposal, but you can create your own preset if you want. Let's take an example with a contact to illustrate what we mean, with the following example:
First name
Last name
Maiden name
Nickname
Middle name
James
Bond
John
007
W.
The default presets would give the following results:
* ``: **James Bond**
* ``: **Bond James**
* ``: **James Bond 007**
* ``: **James 007 Bond**
#### Create your own preset
You can create your own name order, if you want. This is a bit complex, but worth it if it's important to you.
To create your own name order, you have to compose the name using variables, like this:
```
%first_name% %last_name% (%nickname%)
```
You can also add as many characters as you want (spaces, parenthesis,…), and these characters will be represented in the name as well.
The code above will generate the following name `James Bond (007)`.
Here are the different variables we currently support that you can use to compose your preset with:
* `%first_name%`
* `%last_name%`
* `%nickname%`
* `%maiden_name%`
* `%middle_name%`
You can also add as many characters as you want (spaces, parenthesis,…), and these characters will be represented in the name as well.
{% hint style="success" %}
Make sure to always use the `%` character for each variable name, otherwise it won't work.
{% endhint %}
If the contact doesn't have one of those field filled, we'll simply ignore the field when the name is displayed.
### Date format
Dates, like contact names, are culture-based. Because of that, we've added the possibility the customize the way all the dates are displayed in the application. Once it's set, all the dates, throughout the entire application, will be displayed using your own preference.
You can choose between four different formats:
* Aug 01, 2022 `(MM DD, YYYY)`
* 01 Aug 2022 `(DD MM YYYY)`
* 2022/08/01 `(YYYY/MM/DD)`
* 01/08/2022 `(DD/MM/YYYY)`
When relevant, those dates also take into account the timezone that you've chosen.
### Numerical format[](https://docs.monicahq.com/docs/account-settings/manage-preferences#numerical-format)
You can choose to display numerical values in the format that you want. Monica currently supports the following format:
* `1,234.56`
* `1 234,56`
* `1234.56`
Every single number displayed in the app (except phone numbers) will be displayed using the format you chose above.
### Timezone
Not everyone lives in the UTC timezone. Monica's users come from all over the world. Therefore, we need to let users manage their timezones. By default, UTC is the timezone for all users.
Changing timezone will affect all the dates that are displayed in the application, and will dictate at which time of the day we should send you the different reminders that you might define in your account.
### Maps preferences
Monica uses maps here and there for some features. For instance, an address is clickable and will open a map.
Maps can be opened using two services and you have to choose one:
* Google Maps
* Open Street Maps (the default value)
Google Maps is way more precise, but is a nightmare for privacy. Basically, all your searches will end up in the ads business that Google runs. If that's ok with you, use this option.
Open Street Maps is more private friendly, but way less precise.
# Manage templates
## Introduction
What you want to record about your contacts differs from what I want to record about mine. We can go further: you may want to approach professional contacts differently than personal ones.
To help you with this, Monica comes with different concepts: templates, pages and modules.
Let’s analyze that.
* Templates show us what data to display when viewing a contact and how it should be displayed. Each contact is associated with a single template, which can be changed at any time.
* Templates contain pages. Each page represents a category of data that we group together. Think of them as "tabs". For example, a page named "Social" might contain activities and a list of friends associated with a contact.
* Finally, we have modules. A module is a set of data about a contact: life events, reminders, photos etc…
Monica comes with a default template, pages, and modules. We suggest taking some time to create additional templates to customize it to your liking.
Once you have at least two templates in your account, you can decide which contacts should be assigned with which templates. This is defined at the contact level, when viewing the contact page.
## Managing contact templates
### Create a template
To create a template, head over to Settings > Personalize your account > Templates. This is what you will see.
Then, click on the Add a new template button.
Here, you simply need to add the name of the template to create the template.
You can have as many templates as you want in your account.
### Renaming a template
A template can be renamed any time you want. This can only be done by the account administrator.
To rename a template, go to Settings > Personalize your account > Templates and find the template you would like to rename. Then, click on the Rename button to edit the template’s name.
{% hint style="info" %}
The change will take effect immediately. Renaming the template won't affect the content of the template or any contacts that use it.
{% endhint %}
### Deleting a template
To delete a template, go to Settings > Personalize your account > Templates and find the template you would like to delete. Locate the Delete button and click on it to proceed.
{% hint style="warning" %}
Deleting a template has a single consequence: all contacts associated with it will no longer have a template. Technically, a contact needs one template before it can be displayed. If you click on a contact that has no template, Monica will ask you to assign a new one.
{% endhint %}
# Account deletion
In the Settings section, you can delete your account under `Settings > Cancel your account`.
{% hint style="info" %}
Only an account administrator can delete the account.
{% endhint %}
**Deleting an account takes a few seconds, then everything is gone. Forever.**
## What happens if you have a subscription?
If you have a subscription with Monica and delete your account, please note that your subscription will not be cancelled automatically. This is not intended to cause inconvenience, but rather due to the fact that we manage all subscriptions on a separate platform. Therefore, if you wish to cancel your subscription, you will need to do so manually through the platform where you originally subscribed. We apologize for any inconvenience this may cause and appreciate your understanding.
You can manage your subscriptions on [the customer portal (https://customers.monicahq.com)](https://customers.monicahq.com). By the way, you can cancel your account whenever you want on this portal.
Cancelling your subscription will not delete your account on Monica. It will simply prevent you from using your account completely with the current limit of the free plan.
## Behind the scenes
When you delete your account, here is what happens behind the scenes:
* all the contacts are immediately deleted from the database
* all the photos, documents and uploaded files are immediately deleted from the server
* all the journal entries are deleted from the database
* all the vaults are deleted from the database
* all the users are deleted and therefore, won't have access to the account anymore
* the account is deleted
To be completely transparent, all these information are deleted from the main database. However, we do have backups. Let me explain.
Every day, the database is backed up in a gigantic zip file (technically, a tgz file but it's the same concept). Everything in the database is in this zip file. Files (like documents, photos and avatars) are NOT in this backup. This backup is kept for 30 days, then it's deleted forever. The backups are stored in a separate server.
When you delete an account in Monica, all associated information is deleted from the database. However, the data remains in the backup file for the next 30 days. While it is technically possible to restore this data from the backup, **it is a complex and difficult process that we do not undertake for individual users**. Backups are primarily kept in case of emergency server crashes, and are not intended for individual data restoration. Please ensure that you have exported and saved your data before deleting an account, as it cannot be recovered after the 30-day backup retention period has expired.
# Setup local development
These are the steps required to setup the local development.
Monica is a Laravel application. That means it requires this setup:
* PHP 8.1 or newer
* HTTP server with PHP support (eg: Apache, Nginx, Caddy)
* Composer
* MySQL
You can find more details on the [Laravel documentation website](https://laravel.com/docs/master/installation).
Here are the steps that we suggest you to follow:
1. Install PHP and a web server like Nginx. If you are on macOS, we recommend [Valet](https://laravel.com/docs/9.x/valet).
2. Install [SQLite](https://formulae.brew.sh/formula/sqlite) or MySQL.
3. `composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader`
4. `yarn install --frozen-lockfile`
5. `cp .env.example .env` and configure `.env` file
1. `php artisan key:generate --no-interaction` (generates APP\_KEY)
2. `touch monica.db` (if you use SQLite) and add the path to DB\_DATABASE
6. `php artisan monica:setup --force -vvv`
7. Optional: generate dummy data
1. `php artisan monica:dummy --force -vvv`
8. Optional: make the search work:
1. Install and run [meilisearch](https://www.meilisearch.com/) locally
2. Configure and run a queue (`php artisan queue:listen --queue=high,low,default`)
9. `yarn build` to generate the proper JS and CSS files
10. `yarn dev` and head to your browser to play with Monica
# Docker
{% hint style="info" %}
The current [`official Docker image`](https://hub.docker.com/_/monica/) hosted on DockerHub is based on the previous major version of Monica. We'll update it soon to the new version, codename Chandler.
{% endhint %}
We have a [docker image](https://github.com/monicahq/chandler/pkgs/container/monica-next) that you can use to run this project locally.
First you need setup [authentication to the Container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry).
Then play with the image:
```sh
docker run -p 8080:80 ghcr.io/monicahq/monica-next:main
```
This runs the image locally on port 8080 and using sqlite. You can then access the application at .
#### Configuration
Note that you'll need to setup a mail mailer to be able to register a user. You can try to use the `log` mailer like this:
```sh
docker run -p 8080:80 -e MAIL_MAILER=log ghcr.io/monicahq/monica-next:main
```
For more complex scenario (database setup, queue, etc.) see
#### Build it yourself
You can also build your image locally using `yarn docker:build` and run it with `yarn docker:run`.
# Contribution guide
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.
## 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.
## Design rules
* **Keep it simple**. No new options, please. If you want new options, please talk to use first.
* **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.
## Feature branches
We follow [GitHub Flow](https://guides.github.com/introduction/flow/) to manage the development of features.
## 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.
## Backend
### Convention
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.
### Services
Monica is architected around **services**. A service is a single class that does one thing, like `CreateAccount`. The same service is called from the web application as well as the (future) API. A service does one thing, and one thing only (even though this thing can be complex). A service is fully unit tested.
The code is somehow based on domains.
### Unit testing
All the backend must and should be 100% unit tested. To run the test locally, you need to setup a test database, document it in the `.env` file, and run `yarn test` locally, which will run the test suit.
## Front end
### 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. In theory, you shouldn't have to use custom CSS.
* Do not use Jquery. Use plain JS if strictly needed.
* Unless absolutely necessary, do not add a new package to the front end.
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.
### Vite
We use Vite 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**.
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.
### CSS
We use [Tailwind](https://tailwindcss.com/) extensively and prune any unused CSS in views. To compile and run assets on the fly, use `yarn dev`.
### VueJS
We use VueJS to power the frontend. The interaction between the frontend and the backend is done with [InertiaJS](https://inertiajs.com/). Inertia is pretty transparent and there is nothing specific that you need to learn, if you know already Laravel and Vue.
### Architecture
We use the following architecture to serve views from the backend.
* **Controllers** call a view helper, sometimes a [service](#services) and render a view.
* If the view needs data, **view velpers** prepare the data that is needed. No data should be prepared in a controller directly, so we can test the view helper in isolation.
* Views are VueJS files.
### Localization
Translation is a very important part of the application. No code should be put in production if it contains bits and pieces of text that is not translated. We have [a dedicated guide](/developers/translation) for this.
# Setup Telegram
Users can setup Telegram to receive notifications. This is a bit tricky to set up from an instance's administration point of view if you want to test locally.
First of all, you need to setup a Telegram bot to be able to receive notifications. Then you need to configure Monica with the right .env variables. Finally, you need to send the webhook URL to Telegram so Telegram can communicate with your local setup.
#### First, create your Telegram bot
Follow the first steps described in so you can create a bot. Note that **you will need the token that Telegram will send you right after creating your bot**.
#### Fill in your Telegram .env variables
Locate the .env file and fill these three variables that are about Telegram.
```shell
TELEGRAM_BOT_TOKEN=393828013:AAEaw8ewefwhKIdkW2E
TELEGRAM_BOT_URL=https://t.me/monicahq_bot
TELEGRAM_BOT_WEBHOOK_URL=lkjl2kjl2k3232IOWEJFkek
```
The *bot token* is given by Telegram after you create the bot.
The *bot URL* is the URL of your bot. It's derivated from the name of your bot (for us, it's `monicahq_bot`), prefixed by `https://t.me/`. The name of your bot is the username that you've chosen upon the creation of your bot.
The *webhook URL* is not an URL per se. It's a random string, as long as possible, that will be used to sign the webhooks sent by Telegram. You have to defined it yourself.
#### Setup Telegram
We now need to inform Telegram which webhook URL it should use to send notifications.
{% hint style="info" %}
If you need to configure Telegram for development purposes, your Monica instance will likely not have an external URL. You would have to use either [ngrok](https://ngrok.com/) or [Expose](https://expose.dev/) to have a public URL that Telegram will use to send you notifications. If you use one of these, simply use the URL they give you in the `public url` parameter below.
{% endhint %}
The structure of the webhook URL should be as follow
```bash
https://[PUBLIC URL].'/telegram/webhook/'.[TELEGRAM_BOT_WEBHOOK_URL]
```
Let's assume your public URL is (our instance). If we take this URL and the .env variables set above, the webhook URL will be:
```
https://app.monicahq.com/telegram/webhook/lkjl2kjl2k323oIOWEJFkek
```
Now, we need to inform Telegram of this webhook URL. Telegram needs this structure:
```
https://api.telegram.org/bot[TELEGRAM_BOT_TOKEN]/setWebhook?url=[https://[PUBLIC URL].'/telegram/webhook/'.[TELEGRAM_BOT_WEBHOOK_URL]]
```
In our case, we would have this URL
```
https://api.telegram.org/bot393828013:AAEaw8ewefwhKIdkW2EIy23ksVY51XQqsV7o_3M/setWebhook?url=https://app.monicahq.com/telegram/webhook/lkjl2kjl2k323oIOWEJFkek
```
Simply copy and paste the URL above in your browser and Telegram should send you this JSON back.
```json
{"ok":true,"result":true,"description":"Webhook was set"}
```
That means your URL is registered, and Telegram will work.
# Translation
How we manage translation (or i18n) in the app
We are proud to say that we support many languages in Monica. Nothing should go in production without being translated.
## Add a new language
When we want to add a new language that is not yet supported, we should run the following command line (`fr` being the two letter codes identifying the language, here `fr` meaning French).
```sh
php artisan lang:add fr
```
Then we need to translate the default Laravel language files (like the generic error messages) in the new language. We have a package for that, which will let us focus our efforts in something else.
```
php artisan lang:update
```
Once done, you will find a new folder for the new language, and find a set of new files within this directory.
## Translating strings
The core of the work of translating an application is actually about extracting strings to translate from either the Vue or from the backend (sometimes).
To translate a string in a Vue file, you should import the i18n library, then use it to translate:
```javascript
import { trans } from 'laravel-vue-i18n';
// in a method
trans('Are you sure? This action cannot be undone.')
// inside the actual HTML
{{ $t('This is a string to translate') }}
```
Then, each string should be put in the translation files (`fr.json`, `de.json`, ...) like the following:
```json
{
"This is a string to translate": "C'est une chaîne de caractères à traduire",
}
```
Putting this new string in each translation file can be super time consuming. This is why we have a script that will extract translation files in each view, and put it inside the translation files for you.
```
php artisan monica:localize
```
This script also does one magic thing: it translates all the empty strings in all the locales supported by the app.
Basically, you don't have to do anything anymore once you add new strings to the application. Monica will automatically pulls all the strings to translate in the dedicated locale files, find the new empty strings and use Google Translate to translate them for us.
{% hint style="info" %}
Do not submit a PR with new strings that are not translated in every language that we support.
{% endhint %}