Update documentation (#692)

.env.example

@@ -1,7 +1,8 @@
-# Two choices: local|production.
+# Two choices: local|production. Use local if you want to install Monica as a
+# development version. Use production otherwise.
 APP_ENV=local
 
-# true if you want to show debug information on error. For production, put this
+# true if you want to show debug information on errors. For production, put this
 # to false.
 APP_DEBUG=false
 
@@ -14,10 +15,6 @@ APP_KEY=ChangeMeBy32KeyLengthOrGenerated
 # The URL of your application.
 APP_URL=http://localhost
 
-# Frequency of creation of new log files.
-# Possible values: single|daily|syslog|errorlog
-APP_LOG=daily
-
 # Database information
 # To keep this information secure, we urge you to change the default password
 DB_CONNECTION=mysql
@@ -47,9 +44,14 @@ APP_EMAIL_NEW_USERS_NOTIFICATION=EmailThatWillSendNotificationsForNewUser
 # https://github.com/monicahq/monica/blob/master/resources/views/settings/index.blade.php#L70
 APP_DEFAULT_TIMEZONE=US/Eastern
 
-# Ability to disable signups on your instance. Can be true or false. Default to false.
+# Ability to disable signups on your instance.
+# Can be true or false. Default to false.
 APP_DISABLE_SIGNUP=true
 
+# Frequency of creation of new log files. Logs are written when an error occurs.
+# Possible values: single|daily|syslog|errorlog
+APP_LOG=daily
+
 # Specific to the hosted version on .com. You probably don't need those.
 # Let them empty if you don't need them.
 GOOGLE_ANALYTICS_APP_ID=

docs/contribute/contribute.md

@@ -1,55 +1,86 @@
 <!-- This uses the MarkdownTOC's Sublime Text plugin to autogenerate the TOC -->
-<!-- MarkdownTOC autolink="true" depth="4" -->
-
-- [Contribute as a developer][contribute-as-a-developer]
-    - [Testing environment][testing-environment]
-        - [Setup][setup]
-        - [Run the test suite][run-the-test-suite]
-    - [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]
-        - [Mix][mix]
-        - [Watching and compiling assets][watching-and-compiling-assets]
-        - [CSS][css]
-        - [JS and Vue][js-and-vue]
+<!-- MarkdownTOC autolink="true" depth="4" bracket="round" list_bullets="*" -->
+
+* [Contribute as a developer](#contribute-as-a-developer)
+  * [Considerations](#considerations)
+  * [Install Monica locally](#install-monica-locally)
+    * [Homestead \(macOS, Linux, Windows\)](#homestead-macos-linux-windows)
+    * [Valet \(macOS\)](#valet-macos)
+    * [Instructions](#instructions)
+  * [Testing environment](#testing-environment)
+    * [Setup](#setup)
+    * [Run the test suite](#run-the-test-suite)
+  * [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)
+    * [Mix](#mix)
+    * [Watching and compiling assets](#watching-and-compiling-assets)
+    * [CSS](#css)
+    * [JS and Vue](#js-and-vue)
 
 <!-- /MarkdownTOC -->
 
 # Contribute as a developer
 
 Are you interested in giving a hand? We can't be more excited about it. Thanks in advance! Here are some guidelines that could help you to get started quickly.
 
-The best way to contribute to Monica is to use [Homestead](https://laravel.com/docs/5.3/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.
+## 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.
+* 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.
+* 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.
+
+## Install Monica locally
+
+### 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.
 
-Steps to install Monica:
+### 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.
+
+### Instructions
+
+**Prerequisites**:
+* Git
+* [Node](https://nodejs.org/en/)
+* PHP 7.0+
+* [Composer](https://getcomposer.org/)
+
+**Steps to install Monica**
+
+Once the above softwares are installed (or if you've finished the installation of Homestead/Valet):
 
 1. `composer install` in the folder the repository has been cloned.
-1. `cp .env.example .env`
+1. `cp .env.example .env` to create your own version of all the environment variables needed for the project to work.
 1. Update `.env` to your specific needs.
 1. Run `php artisan key:generate` to generate an application key. This will set `APP_KEY` with the right value automatically.
-1. `npm install`.
+1. `npm install` to install all the front-end dependencies and tools needed to compile assets.
 1. Create a database called `monica` in your mySQL instance.
-1. `php artisan key:generate` to generate a random APP_KEY
-1. `php artisan setup:test` setup the database.
+1. `php artisan setup:test` to setup the database.
     1. By default this command will also populate the database with fake data.
     1. Use the `-- skipSeed` option to skip the process of adding fake data in your dev environment.
-1. `php artisan storage:link` to access the avatars.
-1. `php artisan passport:install` to create the access tokens required for the API.
+1. `php artisan storage:link` to symlink the avatars of the contacts.
+1. Optional: `php artisan passport:install` to create the access tokens required for the API.
 
-If you haven't skipped the seeding of fake data, we will create two accounts by default:
+If you haven't skipped the seeding of fake data, two accounts are created by default:
 
-* First account is `[email protected]` with the password `admin`. This account contains a lot of fake data that will let you play with the product. * Second account is `[email protected]` with the password `blank`. This account does not contain any data and shall be used to check all the blank states.
+* First account is `[email protected]` with the password `admin`. This account contains a lot of fake data that will let you play with the product.
+* Second account is `[email protected]` with the password `blank`. This account does not contain any data and shall be used to check all the blank states.
 
 ## Testing environment
 
@@ -67,7 +98,7 @@ To setup the test environment:
 
 To run the test suite:
 
-* `phpunit` or `./vendor/bin/phpunit`
+* `phpunit` or `./vendor/bin/phpunit` in the root of the folder containing Monica's code from GitHub.
 
 ## Backend
 
@@ -87,9 +118,10 @@ Emails are an important part of Monica. Emails are still the most significant me
 
 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. If you use Homestead to code on your local machine, you can use [mailhog](https://github.com/mailhog/MailHog) that is built-in. To use it, you first need to start mailhog (`sudo service mailhog restart`). Then, head up to http://localhost:8025 in your browser to load Mailhog's UI.
+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. If you use Homestead to code on your local machine, you can use [mailhog](https://github.com/mailhog/MailHog) that is 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.
 
-If you want to use mailhog, you need the following settings in your `.env` file:
+Note: if you want to use mailhog, you need the following settings in your `.env` file:
 
 ```
 MAIL_DRIVER=smtp

docs/installation/debian.md

@@ -76,21 +76,20 @@ exit
 
 #### 7. Configure Monica
 
-Run `composer install` in the folder the repository has been cloned to.
-Which in our case would be /var/www/monica.
+Run `composer install` in the folder the repository has been cloned to. Which in our case would be /var/www/monica.
 
 Create a copy of the example configuration file `cp .env.example .env`.
 
-Now Update `.env` with your specific needs. If you would run the setup
-with the exact commands used above your file should look like this:
+Now update `.env` with your specific needs. If you would run the setup with the exact commands used above your file should look like this:
 
 ```
-# Two choices: local|production.
+# Two choices: local|production. Use local if you want to install Monica as a
+# development version. Use production otherwise.
 APP_ENV=local
 
-# true if you want to show debug information on error. For production, put this
+# true if you want to show debug information on errors. For production, put this
 # to false.
-APP_DEBUG=true
+APP_DEBUG=false
 
 # The encryption key. This is the most important part of the application. Keep
 # this secure otherwise, everyone will be able to access your application.
@@ -101,17 +100,14 @@ APP_KEY=ChangeMeBy32KeyLengthOrGenerated
 # The URL of your application.
 APP_URL=http://localhost
 
-# Frequency of creation of new log files.
-# Possible values: single|daily|syslog|errorlog
-APP_LOG=daily
-
 # Database information
+# To keep this information secure, we urge you to change the default password
 DB_CONNECTION=mysql
 DB_HOST=127.0.0.1
 DB_PORT=3306
-DB_DATABASE=monicadb
-DB_USERNAME=monica
-DB_PASSWORD=strongpassword
+DB_DATABASE=monica
+DB_USERNAME=homestead
+DB_PASSWORD=secret
 DB_TEST_DATABASE=monica_test
 DB_TEST_USERNAME=homestead
 DB_TEST_PASSWORD=secret
@@ -131,36 +127,72 @@ APP_EMAIL_NEW_USERS_NOTIFICATION=EmailThatWillSendNotificationsForNewUser
 # application at their leisure.
 # Must be exactly one of the timezones used in this list:
 # https://github.com/monicahq/monica/blob/master/resources/views/settings/index.blade.php#L70
-APP_DEFAULT_TIMEZONE=America/New_York
-APP_DISABLE_SIGNUP=false
+APP_DEFAULT_TIMEZONE=US/Eastern
+
+# Ability to disable signups on your instance.
+# Can be true or false. Default to false.
+APP_DISABLE_SIGNUP=true
+
+# Frequency of creation of new log files. Logs are written when an error occurs.
+# Possible values: single|daily|syslog|errorlog
+APP_LOG=daily
 
 # Specific to the hosted version on .com. You probably don't need those.
+# Let them empty if you don't need them.
 GOOGLE_ANALYTICS_APP_ID=
 INTERCOM_APP_ID=
 
+# Error tracking. Specific to hosted version on .com. You probably don't need
+# those.
+SENTRY_SUPPORT=false
+SENTRY_DSN=
+
+# Send a daily ping to https://version.monicahq.com to check if a new version
+# is available. When a new version is detected, you will have a message in the
+# UI, as well as the release notes for the new changes. Can be true or false.
+# Default to true.
+CHECK_VERSION=true
+
+# Have access to paid features available on https://monicahq.com, for free.
+# Can be true or false. Default to false.
+# If set to true, that means your users will have to pay to access the paid
+# features. We use Stripe to do this.
+REQUIRES_SUBSCRIPTION=false
+
+# ONLY NECESSARY IF MONICA REQUIRES A SUBSCRIPTION TO WORK
+# Leave blank unless you know what you are doing.
+STRIPE_KEY=
+STRIPE_SECRET=
+PAID_PLAN_FRIENDLY_NAME=
+PAID_PLAN_ID=
+PAID_PLAN_PRICE=
+
 # Change this only if you know what you are doing
 CACHE_DRIVER=database
 SESSION_DRIVER=file
 QUEUE_DRIVER=sync
-```
 
-The next 5 lines are taken more or less 1:1 from the main generic installation
-guide. Mainly because the author was unsure about their purpose.
+# Default filesystem to store uploaded files.
+# Possible values: public|s3
+DEFAULT_FILESYSTEM=public
+
+# AWS keys for S3 when using this storage method
+AWS_KEY=
+AWS_SECRET=
+AWS_REGION=us-east-1
+AWS_BUCKET=
+AWS_SERVER=
+```
 
-Run `php artisan key:generate` to generate an application key. This will set `APP_KEY` with the right value automatically.
-* `php artisan migrate` to run all migrations.
-* `php artisan storage:link` to enable avatar uploads for the contacts.
-* `php artisan db:seed --class ActivityTypesTableSeeder` to populate the
-activity types.
-* `php artisan db:seed --class CountriesSeederTable` to populate the countries
-table.
-* `php artisan passport:install` to generate the secure asset tokens required
-for the API.
+Then run the following instructions:
+* Run `php artisan key:generate` to generate an application key. This will set `APP_KEY` with the right value automatically.
+* Open the file `.env` to set the different variables needed by the project. The file comes with predefined values - you won't have to change most of them.
+* Run `php artisan setup:production` to run the migrations, seed the database and symlink folders.
+* Optional: run `php artisan passport:install` to generate the secure asset tokens required for the API. If you don't plan to use the API, don't do this step.
 
 #### 8. Configure cron job
 
-As recommended by the generic installation instructions we create a
-cronjob which runs `artisan schedule:run` every minute.
+As recommended by the generic installation instructions we create a cronjob which runs `artisan schedule:run` every minute.
 
 For this execute this command:
 ```
@@ -201,8 +233,7 @@ and change it to:
 </Directory>
 ```
 
-Save the apache2.conf file and open `/etc/apache2/sites-enabled/000-default.conf`
-and look for this line:
+Save the apache2.conf file and open `/etc/apache2/sites-enabled/000-default.conf` and look for this line:
 
 ```
 DocumentRoot /var/www/html
@@ -212,8 +243,7 @@ and change it to:
 DocumentRoot /var/www/monica/public
 ```
 
-After you save the 000-default.conf file you can finally restart
-Apache and are up and running.
+After you save the 000-default.conf file you can finally restart Apache and are up and running.
 ```
 sudo service apache2 restart
 ```