diff --git a/README.md b/README.md index 5a031c48..4c2236df 100644 --- a/README.md +++ b/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. - -### 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 . -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. diff --git a/var/docs/README.md b/var/docs/README.md index 4f91c92f..b17bc61a 100644 --- a/var/docs/README.md +++ b/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. \ No newline at end of file +try to add it as soon as possible. + diff --git a/var/docs/developers.md b/var/docs/developers.md index d9e672c7..66e30b8a 100644 --- a/var/docs/developers.md +++ b/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: diff --git a/var/docs/faq.md b/var/docs/faq.md new file mode 100644 index 00000000..8805527f --- /dev/null +++ b/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) diff --git a/var/docs/installation.md b/var/docs/installation.md new file mode 100644 index 00000000..845f68ec --- /dev/null +++ b/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 . +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 +``` diff --git a/var/docs/migration_v1.md b/var/docs/migration_v1.md new file mode 100644 index 00000000..2cbcdd4f --- /dev/null +++ b/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.