2016-10-22 22:12:32 +00:00
# Kimai v2 - Time Tracking
2016-10-20 20:10:41 +00:00
2018-06-23 19:20:20 +00:00
Kimai v2 - the open source time-tracking application with a mobile-first approach, read more at the [official website ](http://v2.kimai.org ).
2016-10-20 20:10:41 +00:00
2018-06-07 22:16:12 +00:00
[](https://travis-ci.org/kevinpapst/kimai2)
[](https://scrutinizer-ci.com/g/kevinpapst/kimai2/?branch=master)
[](https://scrutinizer-ci.com/g/kevinpapst/kimai2/?branch=master)
[](https://scrutinizer-ci.com/g/kevinpapst/kimai2/build-status/master)
2016-10-20 20:10:41 +00:00
2016-10-22 22:12:32 +00:00
## Introduction
2018-06-23 19:20:20 +00:00
This is the reloaded version of the open source timetracker Kimai.
2018-06-18 19:37:39 +00:00
Right now its in an early development phase, its usable but some advanced features from Kimai v1 are missing by now.
2018-06-07 22:16:12 +00:00
2018-06-23 19:20:20 +00:00
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.
It is based on a lot of great frameworks. Special thanks to [Symfony v4 ](https://github.com/symfony/symfony ), [Doctrine ](https://github.com/doctrine/ ),
[AdminThemeBundle ](https://github.com/avanzu/AdminThemeBundle/ ) (based on [AdminLTE ](https://github.com/almasaeed2010/AdminLTE/ )).
2016-10-22 22:12:32 +00:00
2018-06-23 19:20:20 +00:00
### Requirements
2016-10-20 20:10:41 +00:00
2018-06-23 19:20:20 +00:00
- PHP 7.1.3 or higher
2018-01-27 10:21:52 +00:00
- One PHP extension of PDO-SQLite or PDO-MySQL enabled (it might work with PostgreSQL and Oracle as well, but that wasn't tested and is not officially supported)
2018-02-01 21:26:19 +00:00
- the [usual Symfony application requirements ](http://symfony.com/doc/current/reference/requirements.html )
2018-06-18 19:37:39 +00:00
- Kimai needs to be installed in the root directory of a domain or you need to [recompile the frontend assets ](var/docs/developers.md )
2018-06-26 18:18:08 +00:00
- a modern browser, Kimai v2 might be broken on old browsers like the IE 9
2016-10-20 20:10:41 +00:00
2018-06-23 19:20:20 +00:00
## Documentation & Roadmap
Looking for more information about using Kimai? Check out our more detailed [documentation ](var/docs/ ).
You can see our development roadmap for the future in the [Milestones ](milestones/ ) sections,
current work is organized in the [Project ](projects/ ) planning boards.
Our roadmap is open for changes and input from the community, please [sent us ](issues/ ) your ideas and questions.
2018-01-10 22:20:36 +00:00
## Installation
2016-10-20 20:10:41 +00:00
2018-06-23 19:20:20 +00:00
First, install Git and [Composer ](https://getcomposer.org/doc/00-intro.md ) if you haven't already. Then clone this repo:
2016-10-20 20:10:41 +00:00
```bash
2018-02-01 21:26:19 +00:00
git clone https://github.com/kevinpapst/kimai2.git
cd kimai2/
2016-10-20 20:10:41 +00:00
```
2018-06-18 21:13:29 +00:00
The next steps depend in which environment you want to use Kimai, you can choose between development or production mode.
### Installation (development)
2018-02-01 21:26:19 +00:00
Lets prepare the environment by installing all dependencies:
2018-01-09 12:09:33 +00:00
2016-10-22 22:12:32 +00:00
```bash
2018-02-01 21:26:19 +00:00
composer install
2016-10-22 22:12:32 +00:00
```
2018-02-01 21:26:19 +00:00
The default installation uses a SQLite database, so there is no need to create a database for your first tests.
2018-06-18 19:37:39 +00:00
Our default settings will work out-of-the-box, but you might want to adjust the `.env` values to your needs.
2018-02-01 21:26:19 +00:00
You can configure your database through your environment (e.g. Webserver, Cloud-Provider) or in your `.env` file:
2018-01-27 10:21:52 +00:00
```
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
```
2018-02-01 21:26:19 +00:00
The next command will create the database and the schema:
```bash
bin/console doctrine:database:create
bin/console doctrine:schema:create
```
2018-06-05 19:28:25 +00:00
Lets bootstrap your environment by executing this commands (which is only available in dev environment):
2018-01-06 17:53:15 +00:00
```bash
2018-02-01 21:26:19 +00:00
bin/console kimai:reset-dev
2016-10-20 21:19:06 +00:00
```
2018-01-06 17:53:15 +00:00
2018-01-10 22:20:36 +00:00
You just imported demo data, to test the application in its full beauty and with several different user accounts and permission sets.
2018-01-09 12:09:33 +00:00
You can now login with these accounts:
2016-10-20 21:19:06 +00:00
2018-01-10 22:20:36 +00:00
| 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 |
2018-01-06 17:53:15 +00:00
2018-01-09 12:09:33 +00:00
Demo data can always be deleted by dropping the schema and re-creating it.
ATTENTION - this will erase all your data:
2018-01-06 17:53:15 +00:00
```bash
2018-02-01 21:26:19 +00:00
bin/console doctrine:schema:drop --force
bin/console doctrine:schema:create
2018-01-06 17:53:15 +00:00
```
2016-10-20 21:19:06 +00:00
2018-01-14 00:36:07 +00:00
The `kimai:reset-dev` command can always be executed later on to reset your dev database and cache.
2018-01-27 10:21:52 +00:00
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:
2018-01-14 00:36:07 +00:00
```bash
2018-02-01 21:26:19 +00:00
bin/console server:run
2018-01-14 00:36:07 +00:00
```
2018-01-09 12:09:33 +00:00
2018-02-10 18:11:30 +00:00
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 / > .
2018-01-27 10:21:52 +00:00
You can stop the built-in web server by pressing `Ctrl + C` while you're in the terminal.
2018-06-05 19:28:25 +00:00
To re-generate the frontend assets ([more information here](var/docs/developers.md)), execute:
```bash
yarn install
npm run prod
```
2018-01-27 10:21:52 +00:00
2018-06-05 19:28:25 +00:00
### Installation (production)
2018-06-18 21:13:29 +00:00
Lets prepare the environment by installing all dependencies:
```bash
composer install --no-dev
```
2018-06-05 19:28:25 +00:00
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/
```
2018-01-27 10:21:52 +00:00
2018-02-10 18:11:30 +00:00
The database to use is up to you, but we would not recommend using the default SQLite database for production usage.
2018-01-27 10:21:52 +00:00
Please create your database and configure the connection string in your environment, e.g. with the `.env` file:
2018-01-14 00:36:07 +00:00
```
2018-01-27 10:21:52 +00:00
APP_ENV=prod
2018-06-01 13:06:29 +00:00
DATABASE_URL=mysql://db_user:db_password@127.0.0.1:3306/db_name
2018-01-27 10:21:52 +00:00
APP_SECRET=insert_a_random_secret_string_for_production
2018-01-14 00:36:07 +00:00
```
2018-06-05 19:28:25 +00:00
Create the database schemas and warm up the cache (as webserver user):
2018-01-14 00:36:07 +00:00
```bash
2018-02-01 21:26:19 +00:00
bin/console doctrine:schema:create
2018-06-05 19:28:25 +00:00
sudo -u www-data bin/console cache:warmup --env=prod
2018-01-14 00:36:07 +00:00
```
2018-02-10 18:11:30 +00:00
Create your first user with the following command. You will be asked to enter a password afterwards.
2018-01-14 00:36:07 +00:00
```bash
2018-02-10 18:11:30 +00:00
bin/console kimai:create-user username admin@example.com ROLE_SUPER_ADMIN
2018-01-14 00:36:07 +00:00
```
2018-06-05 19:28:25 +00:00
_Tip: You can skip the "create user" step, if you are going to import data from Kimai v1._
2018-01-14 00:36:07 +00:00
2018-02-01 21:26:19 +00:00
For available roles, please refer to the [user documentation ](var/docs/users.md ).
2018-01-09 12:09:33 +00:00
2018-01-27 10:21:52 +00:00
> **NOTE**
>
> If you want to use a fully-featured web server (like Nginx or Apache) to run
> Kimai, configure it to point at the `public/` directory of the project.
> For more details, see:
> http://symfony.com/doc/current/cookbook/configuration/web_server_configuration.html
That's it, you can start time-tracking :-)
2018-01-22 23:23:41 +00:00
### 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)
2018-01-27 10:21:52 +00:00
A possible full command for import:
2018-01-22 23:23:41 +00:00
```bash
2018-02-01 21:26:19 +00:00
bin/console kimai:import-v1 "mysql://user:password@127.0.0.1:3306/database?charset=utf8" "db_prefix" "password" "country"
2018-01-22 23:23:41 +00:00
```
2018-01-27 10:21:52 +00:00
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.
2018-01-22 23:23:41 +00:00
A sample command could look like that:
```bash
2018-02-01 21:26:19 +00:00
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"
2018-01-22 23:23:41 +00:00
```
2018-01-27 10:21:52 +00:00
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.
2018-01-22 23:23:41 +00:00
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.
2018-01-28 11:08:44 +00:00
## Extensions for Kimai 2
2016-10-20 20:10:41 +00:00
2018-02-01 21:26:19 +00:00
As Kimai 2 was built on top of Symfony, it can be extended like every other Symfony application.
2018-01-28 11:08:44 +00:00
We call these extensions bundles, but you might also know them as add-ons, extensions or plugins.
2016-10-20 20:10:41 +00:00
2018-02-01 21:26:19 +00:00
All available Kimai 2 bundles can be found at the [Kimai recipes ](https://github.com/kimai/recipes ) repository.
2016-10-22 22:12:32 +00:00
2018-02-01 21:26:19 +00:00
## Developer
2016-10-22 22:12:32 +00:00
2018-02-01 21:26:19 +00:00
If you want to develop for Kimai 2 please read the following documentation:
- an example on how to extend Kimai 2 can be found in this [GitHub repository ](https://github.com/kevinpapst/kimai2-invoice )
2018-06-07 22:16:12 +00:00
- the [developer documentation ](var/docs/developers.md ) is available both on GitHub and your local installation