added FAQ and database requirement docu #196 (#210)

* added FAQ and database requirement docu - fixes #196
* added FTP installation docu - see #199
* moved migration guide from Kimai v1 to its own docu chapter

README.md

@@ -10,9 +10,10 @@ Kimai v2 - the open source time-tracking application with a mobile-first approac
 ## Introduction
 
 This is the reloaded version of the open source timetracker Kimai.
-Kimai v2 has nothing in common with its predecessor [Kimai v1](http://www.kimai.org) besides the basic ideas of time-tracking and the current development team.
+The new version has not much in common with its predecessor [Kimai v1](http://www.kimai.org) besides the basic ideas of time-tracking and the current development team.
 
-Right now its in an early development phase, its usable but some advanced features from Kimai v1 are missing by now.
+Right now its in an early development phase, its usable but some advanced features from Kimai v1 are missing by now (like export and ODT invoices). 
+But we already support to [import your timesheets](migration_v1.md) from Kimai v1.
 
 It is developed with modern frameworks like [Symfony v4](https://github.com/symfony/symfony), [Doctrine](https://github.com/doctrine/),
 [AdminLTE](https://github.com/kevinpapst/AdminLTEBundle/) and [many](composer.json) [more](package.json)...
@@ -23,7 +24,7 @@ It is developed with modern frameworks like [Symfony v4](https://github.com/symf
 - One PHP extension of [PDO-SQLite](https://php.net/manual/en/ref.pdo-sqlite.php) or [PDO-MySQL](https://php.net/manual/en/ref.pdo-mysql.php) enabled (it might work with PostgreSQL and Oracle as well, but that wasn't tested and is not officially supported)
 - The PHP extension [intl](https://php.net/manual/en/book.intl.php)
 - The [usual Symfony application requirements](http://symfony.com/doc/current/reference/requirements.html)
-- If you use MariaDB, make sure its at least v10.7.2 (see #191)
+- If you use MariaDB, make sure its at least v10.7.2 (see [FAQ](var/docs/faq.md))
 - Kimai needs to be installed in the root directory of a domain or you need to [recompile the frontend assets](var/docs/developers.md)
 - A modern browser, Kimai v2 might be broken on old browsers like IE 9
 
@@ -37,93 +38,26 @@ Our roadmap is open for changes and input from the community, please [sent us](i
 
 ## Installation
 
-First, install Git and [Composer](https://getcomposer.org/doc/00-intro.md) if you haven't already. Then clone this repo:
+There are [further infos about installation](var/docs/installation.md) if you have to use FTP or want to develop with Kimai. 
+
+If you want to install Kimai v2 in your production environment, then SSH into your server and change to your webserevr root.
+You need to install Git and [Composer](https://getcomposer.org/doc/00-intro.md) if you haven't already. 
+
+First clone this repo:
 
 ```bash
 git clone https://github.com/kevinpapst/kimai2.git
 cd kimai2/
 ```
 
-The next steps depend in which environment you want to use Kimai, you can choose between development or production mode.
+Make sure the [file permissions are correct](https://symfony.com/doc/current/setup/file_permissions.html):
-
-### Installation (development)
-
-Lets prepare the environment by installing all dependencies:
-
-```bash
-composer install
-```
-
-The default installation uses a SQLite database, so there is no need to create a database for your first tests.
-Our default settings will work out-of-the-box, but you might want to adjust the `.env` values to your needs.
-You can configure your database through your environment (e.g. Webserver, Cloud-Provider) or in your `.env` file:
-```
-DATABASE_PREFIX=kimai2_
-DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/kimai.sqlite
-APP_ENV=dev
-APP_SECRET=some_random_secret_string_for_your_installation
-```
-
-The next command will create the database and the schema:
-```bash
-bin/console doctrine:database:create
-bin/console doctrine:schema:create
-```
-
-Lets bootstrap your environment by executing this commands (which is only available in dev environment):
-```bash
-bin/console kimai:reset-dev
-```
-
-You just imported demo data, to test the application in its full beauty and with several different user accounts and permission sets.
-
-You can now login with these accounts:
-
-| Username | Password | Role |
-|---|:---:|---|
-| clara_customer | kitten | Customer |
-| john_user | kitten | User |
-| chris_user | kitten | User (deactivated) |
-| tony_teamlead | kitten | Teamlead |
-| anna_admin | kitten | Administrator |
-| susan_super | kitten | Super-Administrator |
-
-Demo data can always be deleted by dropping the schema and re-creating it.
-ATTENTION - this will erase all your data:
-
-```bash
-bin/console doctrine:schema:drop --force
-bin/console doctrine:schema:create
-```
-
-The `kimai:reset-dev` command can always be executed later on to reset your dev database and cache.
-
-There is no need to configure a virtual host in your web server to access the application for testing.
-Just use the built-in web server for your first tests:
-
-```bash
-bin/console server:run
-```
-
-This command will start a web server for Kimai. Now you can access the application in your browser at <http://127.0.0.1:8000/>.
-You can stop the built-in web server by pressing `Ctrl + C` while you're in the terminal.
-
-To re-generate the frontend assets ([more information here](var/docs/developers.md)), execute:
-```bash
-yarn install
-npm run prod
-```
-
-### Installation (production)
-
-Make sure the [directories are read and writable by your webserver](https://symfony.com/doc/current/setup/file_permissions.html):
 ```bash
 chown -R www-data var/
 chmod -R 777 var/
 ```
 
-The database is up to you, but we would not recommend using the default SQLite database for production usage.
+It's up to you which database server you want to use, Kimai v2 supports MySQL/MariaDB and SQLite.
-Please create your database and configure the connection string in your environment, e.g. with the `.env` file (more examples in `.env.dist`):
+Create your database and configure the connection string in your environment, e.g. with the `.env` file (more examples in `.env.dist`):
 ```
 APP_ENV=prod
 APP_SECRET=insert_a_random_secret_string_for_production
@@ -147,7 +81,7 @@ Create your first user with the following command. You will be asked to enter a
 ```bash
 bin/console kimai:create-user username admin@example.com ROLE_SUPER_ADMIN
 ```
-_Tip: You can skip the "create user" step, if you are going to import data from Kimai v1._
+_Tip: You can skip the "create user" step, if you are going to [import data from Kimai v1](migration_v1.md)._
 
 For available roles, please refer to the [user documentation](var/docs/users.md).
 
@@ -160,32 +94,6 @@ For available roles, please refer to the [user documentation](var/docs/users.md)
 
 That's it, you can start time-tracking :-)
 
-### Importing data from Kimai v1
-
-Before importing your data from a Kimai v1 installation, please read the following carefully:
-
-- Data from the existing v1 installation is only read and will never be changed
-- Data can only be imported from a Kimai installation with at least `v1.0.1` and database revision `1388` (check your `configuration` table)
-- Kimai v1 has support for activities without project assignment, which Kimai v2 doesn't support. Unattached activities will be created for every project that has a linked activity in any of the imported timesheet records
-- Rates and fixed-rates are handled in a completely different way and for now only the timesheet record total amounts are imported
-- Customers cannot login and no user accounts will be created for them
-- The customers country has to be manually assigned afterwards, as there is no field in Kimai v1 for that
-- You have to supply the default password that is used for every imported user, as their password will be resetted
-- Data that was deleted in Kimai v1 (user, customer, projects, activities) will be imported and set to `invisible` (if you don't want that, you have to delete all entries that have the value `1` in the `trash` column before importing)
-
-A possible full command for import:
-```bash
-bin/console kimai:import-v1 "mysql://user:password@127.0.0.1:3306/database?charset=utf8" "db_prefix" "password" "country"
-```
-
-It is recommended to test the import in a fresh database. You can test your import as often as you like and fix possible problems in your installation.
-A sample command could look like that:
-```bash
-bin/console doctrine:schema:drop --force && bin/console doctrine:schema:create && bin/console kimai:import-v1 "mysql://kimai:test@127.0.0.1:3306/kimai?charset=latin1" "kimai_" "test123" "de"
-```
-That will drop the configured Kimai v2 database schema and re-create it, before importing the data from the `mysql` database at `127.0.0.1` on port `3306` authenticating the user `kimai` with the password `test` for import.
-The connection will use the charset `latin1` and the default table prefix `kimai_` for reading data. Imported users can login with the password `test123` and all customer will have the country `de` assigned.
-
 ## Extensions for Kimai 2
 
 As Kimai 2 was built on top of Symfony, it can be extended like every other Symfony application.

var/docs/README.md

@@ -7,6 +7,9 @@ The first chapters are meant for developers and administrators:
 - [Kimai configurations](configurations.md) - the Kimai core configurations, which can only be set in configuration files 
 - [Developer docu](developers.md) - information for developer who would like to extend Kimai  
 - [User and Security](users.md) - everything related to user and security, like authentication and roles  
+- [FAQ](faq.md) - some frequently asked questions and their with answers 
+- [Installation](installation.md) - instructions about several installation methods
+- [Importing data](migration_v1.md) - how to import your timesheets from Kimai v1
 
 The following chapters are meant for users:
 
@@ -15,3 +18,4 @@ The following chapters are meant for users:
 We know there is a lot missing right now and would appreciate [any help](https://github.com/kevinpapst/kimai2/pulls) in writing. 
 If you need information which is not available right now, [ask us](https://github.com/kevinpapst/kimai2/issues) and we 
 try to add it as soon as possible. 
+

var/docs/developers.md

@@ -5,7 +5,7 @@ This page is dedicated to all developers who want to contribute to Kimai. You ar
 # Setting up your environment
 
 All you need is:
-- PHP >= 7.1 
+- PHP >= 7.1.3
 - PHP extension: `PDO-SQLite` enabled
 
 Optional requirement:
@@ -14,6 +14,8 @@ Optional requirement:
 
 You could even test PostgreSQL and tell us how it works!
 
+Read how to [install Kimai v2 in your dev environment](installation.md). 
+
 ## Frontend dependencies 
 
 If you want to make changes to CSS / Javascripts, you need:

var/docs/faq.md

@@ -0,0 +1,32 @@
+# Frequently asked questions
+
+## I have only FTP available ...
+
+So you want to install Kimai v2 but have no SSH access to your server? 
+There is a workaround available, read the additional [installation instructions](installation.md). 
+
+## Error on bin/console doctrine:schema:create
+
+If you get an error during the installation of the database schema that mentions `DC2Type:json_array`, e.g. like the following: 
+
+```
+In PDOConnection.php line 109:
+
+  SQLSTATE[42000]: Syntax error or access violation: 1064 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 'JSON
+   NOT NULL COMMENT '(DC2Type:json_array)', UNIQUE INDEX UNIQ_B9AC5BCE5E237E06' at line 1
+```
+
+Then the most likely case is that you are using a MariaDB database which is too old. You can find out which version is 
+used by executing `mysql --version` or by checking the server information e.g. with PHPMyAdmin.
+
+There is a [discussion in the issue tracker](https://github.com/kevinpapst/kimai2/issues/191) about this topic.
+
+There are two solution for this: 
+
+- Update your MariaDB server to at least 10.7.2
+- Switch to SQLite (that can be changed in your `.env` file)
+
+Further readings:
+
+- [MariaDB - JSON support was added with 10.7.2](https://mariadb.com/kb/en/library/json-data-type/)
+- [Using JSON fields with Doctrine ORM on PostgreSQL & MySQL](https://symfony.fi/entry/using-json-fields-with-doctrine-orm-on-postgresql-mysql)

var/docs/installation.md

@@ -0,0 +1,118 @@
+# Installation
+
+If you want to install Kimai v2 in your production environment and have SSH access, then switch to the official 
+installation instruction in our[README](https://github.com/kevinpapst/kimai2/blob/master/README.md).
+
+You need GIT and [Composer](https://getcomposer.org/doc/00-intro.md) on the machine where you want to install Kimai. 
+
+## FTP installation
+
+If you have no SSH access to your server (e.g. when you use a shared hosting package) then you need to install Kimai locally and upload it afterwards.
+
+Before I start to explain how to apply this workaround let me briefly explain the problem:
+Kimai has no [web-based installer](https://github.com/kevinpapst/kimai2/issues/209) for now and you have to create the first user with a console command.
+It also does not come as pre-built ZIP file, so you have to install the dependencies manually.
+
+These are the steps you have to perform:
+
+```
+git clone https://github.com/kevinpapst/kimai2.git
+cd kimai2/
+```
+
+Create the `.env` file, using the `prod` environment and SQLite as database:
+```
+APP_ENV=prod
+APP_SECRET=insert_a_random_secret_string_for_production
+DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/kimai.sqlite
+```
+The file `var/data/kimai.sqlite` will hold all your data, so make sure to include it in your backups!
+
+Prepare the environment by installing all dependencies:
+
+```bash
+composer install --no-dev
+```
+
+Create the database schemas:
+```bash
+bin/console doctrine:schema:create
+```
+
+And create your first user with the following command. You will be asked to enter a password afterwards.
+
+```bash
+bin/console kimai:create-user username admin@example.com ROLE_SUPER_ADMIN
+```
+
+Now you can upload the `kimai2/` directory to your hosting environment and point your domain (document root) to `kimai2/public/`.
+
+## Development installation
+
+Clone the repository and install all dependencies:
+
+```bash
+git clone https://github.com/kevinpapst/kimai2.git
+cd kimai2/
+composer install
+```
+
+The default installation uses a SQLite database, so there is no need to create a database for your first tests.
+Our default settings will work out-of-the-box, but you might want to adjust the `.env` values to your needs.
+You can configure your database through your environment (e.g. Webserver, Cloud-Provider) or in your `.env` file:
+```
+DATABASE_PREFIX=kimai2_
+DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/kimai.sqlite
+APP_ENV=dev
+APP_SECRET=some_random_secret_string_for_your_installation
+```
+
+The next commands will create the database and the schema:
+```bash
+bin/console doctrine:database:create
+bin/console doctrine:schema:create
+```
+
+Lets bootstrap your environment by executing this commands (which is only available in dev environment):
+```bash
+bin/console kimai:reset-dev
+```
+
+You just imported demo data, to test the application in its full beauty and with several different user accounts and permission sets.
+
+You can now login with these accounts:
+
+| Username | Password | Role |
+|---|:---:|---|
+| clara_customer | kitten | Customer |
+| john_user | kitten | User |
+| chris_user | kitten | User (deactivated) |
+| tony_teamlead | kitten | Teamlead |
+| anna_admin | kitten | Administrator |
+| susan_super | kitten | Super-Administrator |
+
+Demo data can always be deleted by dropping the schema and re-creating it.
+ATTENTION - this will erase all your data:
+
+```bash
+bin/console doctrine:schema:drop --force
+bin/console doctrine:schema:create
+```
+
+The `kimai:reset-dev` command can always be executed later on to reset your dev database and cache.
+
+There is no need to configure a virtual host in your web server to access the application for testing.
+Just use the built-in web server for your first tests:
+
+```bash
+bin/console server:run
+```
+
+This command will start a web server for Kimai. Now you can access the application in your browser at <http://127.0.0.1:8000/>.
+You can stop the built-in web server by pressing `Ctrl + C` while you're in the terminal.
+
+To re-generate the frontend assets ([more information here](var/docs/developers.md)), execute:
+```bash
+yarn install
+npm run prod
+```

var/docs/migration_v1.md

@@ -0,0 +1,25 @@
+# Importing data from Kimai v1
+
+Before importing your data from a Kimai v1 installation, please read the following carefully:
+
+- Data from the existing v1 installation is only read and will never be changed
+- Data can only be imported from a Kimai installation with at least `v1.0.1` and database revision `1388` (check your `configuration` table)
+- Kimai v1 has support for activities without project assignment, which Kimai v2 doesn't support. Unattached activities will be created for every project that has a linked activity in any of the imported timesheet records
+- Rates and fixed-rates are handled in a completely different way and for now only the timesheet record total amounts are imported
+- Customers cannot login and no user accounts will be created for them
+- The customers country has to be manually assigned afterwards, as there is no field in Kimai v1 for that
+- You have to supply the default password that is used for every imported user, as their password will be resetted
+- Data that was deleted in Kimai v1 (user, customer, projects, activities) will be imported and set to `invisible` (if you don't want that, you have to delete all entries that have the value `1` in the `trash` column before importing)
+
+A possible full command for import:
+```bash
+bin/console kimai:import-v1 "mysql://user:password@127.0.0.1:3306/database?charset=utf8" "db_prefix" "password" "country"
+```
+
+It is recommended to test the import in a fresh database. You can test your import as often as you like and fix possible problems in your installation.
+A sample command could look like that:
+```bash
+bin/console doctrine:schema:drop --force && bin/console doctrine:schema:create && bin/console kimai:import-v1 "mysql://kimai:test@127.0.0.1:3306/kimai?charset=latin1" "kimai_" "test123" "de"
+```
+That will drop the configured Kimai v2 database schema and re-create it, before importing the data from the `mysql` database at `127.0.0.1` on port `3306` authenticating the user `kimai` with the password `test` for import.
+The connection will use the charset `latin1` and the default table prefix `kimai_` for reading data. Imported users can login with the password `test123` and all customer will have the country `de` assigned.