From f45fbbce6057202968e8594ce86b7032ec2babdf Mon Sep 17 00:00:00 2001 From: Kevin Papst Date: Fri, 2 Nov 2018 16:11:40 +0100 Subject: [PATCH] improved docs and cross-linked docker (#383) --- README.md | 6 ++++-- var/docs/README.md | 22 ++++++++++----------- var/docs/installation.md | 42 ++++++++++++++++++++++++++++++++-------- 3 files changed, 48 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index feb496f0..6d5569ce 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,8 @@ Our roadmap is open for changes and input from the community, please [sent us](i > **NOTE** > -> There are [further infos about installation](var/docs/installation.md) if you have to use FTP, want to develop with Kimai, or are setting Kimai up on a personal computer (vs a server). +> There are [further infos about installation](var/docs/installation.md) if you have to use FTP, want to develop with Kimai +or are setting up Kimai on your personal computer. There is also a [docker image](var/docs/docker.md) available. If you want to install Kimai 2 in your production environment, then SSH into your server and change to your webserver root. You need to install Git and [Composer](https://getcomposer.org/doc/00-intro.md) if you haven't already. @@ -122,7 +123,8 @@ Installation complete: enjoy time-tracking :-) > **NOTE** > -> Don't forget tweaks that may be necessary to these instructions if you are using FTP, developing, or updating on a personal computer instead of a server. See [further infos about installation](var/docs/installation.md). +> Don't forget tweaks that may be necessary to these instructions if you are using FTP, developing or updating on your +personal computer instead of a server. See [further infos about installation](var/docs/installation.md). **STOP** diff --git a/var/docs/README.md b/var/docs/README.md index 178b64a6..88d965cc 100644 --- a/var/docs/README.md +++ b/var/docs/README.md @@ -11,20 +11,18 @@ try to add it as soon as possible. For the most parts Kimai usage should be self-explanatory, so we will only cover topics here which were [requested](https://github.com/kevinpapst/kimai2/issues) by the community. -- [Timesheets](timesheet.md) - information about timesheets -- [Invoices](invoices.md) - export your data to different formats with customizable templates -- [User and Security](users.md) - docu for user and security topics, like authentication, registration and roles - [Configurations](configurations.md) - intro into the global application configs - - [Emails](emails.md) - transport configuration and handling of emails - - [Dashboard & widgets](dashboard.md) - how to configure widgets and dashboard sections - [Calendar](calendar.md) - the Timesheet calendar view -- [Developer docu](developers.md) - how to extend Kimai's feature set + - [Dashboard & widgets](dashboard.md) - how to configure widgets and dashboard sections + - [Emails](emails.md) - transport configuration and handling of emails +- [Developer](developers.md) - docs about extending Kimai's feature set + - [API](developers_api.md) - how to use the JSON API - [Theme settings](theme.md) - theme related settings - [FAQ](faq.md) - some answers to frequently asked questions -- [API](developers_api.md) - how to use the JSON API -- [Translations](translations.md) - all about languages and translations - -## Installation - - [Installation](installation.md) - instructions about several installation methods -- [Importing data](migration_v1.md) - how to import your timesheets from Kimai v1 + - [Docker](docker.md) - using the built-in Dockerfile for development + - [Importing data](migration_v1.md) - how to import your timesheets from Kimai v1 +- [Invoices](invoices.md) - export your data to different formats with customizable templates +- [Timesheets](timesheet.md) - information about timesheets +- [Translations](translations.md) - all about languages and translations +- [User and Security](users.md) - docu for user and security topics, like authentication, registration and roles diff --git a/var/docs/installation.md b/var/docs/installation.md index 33bc58fb..07197dc9 100644 --- a/var/docs/installation.md +++ b/var/docs/installation.md @@ -5,17 +5,43 @@ installation instruction in our [README](https://github.com/kevinpapst/kimai2/#i You need GIT and [Composer](https://getcomposer.org/doc/00-intro.md) on the machine where you want to install Kimai. -## Installing on a personal computer (instead of a server) -### 1. No need to use www-data user +## Docker + +There is a dedicated about [our Docker setup](docker.md), which is primarily meant for use in development. + +## Installing on a personal computer + +### Which user to use - no need to use www-data user?! + The installation instructions are intended primarily for server applications. -If you are installing Kimai 2 on a desktop or laptop computer - even for use in a local network, but where the computer primarily serves as a single user computer - you will avoid permission errors by subsituting ```www-data``` in the relevant commands with your username. -In particular, ```sudo -u www-data``` is a command which grants the ```www-data``` user temporary administrator/super-user privileges). However, depending on the configuration of your particular computer, you may be able to avoid sudo altogether (your user may already have adequate permissions). -You can try first leaving ```sudo -u www-data``` altogether in the relevant commands. If you have permission errors, you can substitute it for ```sudo -u username``` in the relevant commands (where username is the username that runs the server - if you don't know, it is likely your own username that you login with). -### 2. Chown & Chmod commands -Further, chown & chmod commands should be for the username that runs the server instead of ```www-data``` (again, if you don't know, it is likely your own username). +If you are installing Kimai 2 on your personal computer - even for use in a local network, but where the computer primarily +serves as a single user computer - you will avoid permission errors by subsituting `www-data` in the relevant commands with your username. -Also note that, depending on where you are installing Kimai 2 and how your computer is configured, you may also receive "operation not permitted" errors when setting file permissions (chown and chmod commands). In that case, prefix them with ```sudo ```. +In particular, `sudo -u www-data` is a command which grants the `www-data` user temporary administrator/super-user privileges). +However, depending on the configuration of your particular computer, you may be able to avoid sudo altogether (your user +may already have adequate permissions). + +You can try first leaving `sudo -u www-data` altogether in the relevant commands. +If you have permission errors, you can substitute it for `sudo -u $USER` in the relevant commands (where username is the +username that runs the server - if you don't know, it is likely your own username that you login with). + +### chown & chmod commands + +Further, `chown` and `chmod` commands should be for the username that runs the server instead of `www-data` (again, if you +don't know, it is likely your own username). + +Also note that, depending on where you are installing Kimai 2 and how your computer is configured, you may also receive +"operation not permitted" errors when setting file permissions (chown and chmod commands). +In that case, prefix them with `sudo`. + +### Still doesn't work? + +These infos were added to give you some possible guidance if you run into troubles. The Linux (and Mac) filesystem +with its permission structure, especially when using server software, can be tricky and challenging. + +But this has NOTHING to do with Kimai and we might not be able to help you in such situations ... it is your system and +responsibility, be aware that wrong permissions might break Kimai and can also lead to security problems. ## Hosting & 1-click installations