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

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:
 
@@ -14,4 +17,5 @@ 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. 
+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.