jjsm01/kimai2
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

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

Browse Source 
* 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
This commit is contained in:
Kevin Papst
2018-07-12 22:34:34 +02:00
committed by GitHub
parent e68bef7ea7
commit d8f7a5dfa4
6 changed files with 197 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
README.md
View File

@@ -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.
### 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):
Make sure the [file permissions are correct](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.
Please create your database and configure the connection string in your environment, e.g. with the `.env` file (more examples in `.env.dist`):
It's up to you which database server you want to use, Kimai v2 supports MySQL/MariaDB and SQLite.
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.

6
var/docs/README.md
View File

@@ -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.

4
var/docs/developers.md
View File

@@ -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:

32
var/docs/faq.md Normal file
View File

@@ -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)

118
var/docs/installation.md Normal file
View File

@@ -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
```

25
var/docs/migration_v1.md Normal file
View File

@@ -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.