From 1eadcb1eab8bc9d930a3d864fca672de0146cb14 Mon Sep 17 00:00:00 2001 From: Kevin Papst Date: Fri, 17 Nov 2023 17:25:57 +0100 Subject: [PATCH] Migrated documentation to Kimai website --- README.md | 6 +-- docs/build.md | 95 ++--------------------------------------- docs/examples.md | 14 +----- docs/helm.md | 6 ++- docs/index.md | 82 +---------------------------------- docs/runtime-args.md | 55 +----------------------- docs/troubleshooting.md | 43 +------------------ docs/updating.md | 69 ++---------------------------- 8 files changed, 21 insertions(+), 349 deletions(-) diff --git a/README.md b/README.md index fda55eb..eb00f16 100644 --- a/README.md +++ b/README.md @@ -65,10 +65,8 @@ Keep in mind that this Docker setup is transient and the data will disappear whe ## Using docker-compose -This will run the latest prod version using FPM with an nginx reverse proxy - -See the [docker-compose.yml](docker-compose.yml) in the root of this repo. +See [https://www.kimai.org/documentation/docker-compose.html](https://www.kimai.org/documentation/docker-compose.html) ## Documentation -[https://tobybatch.github.io/kimai2/](https://tobybatch.github.io/kimai2/) +[https://www.kimai.org/documentation/docker.html](https://www.kimai.org/documentation/docker.html) diff --git a/docs/build.md b/docs/build.md index b75880f..cbccd97 100644 --- a/docs/build.md +++ b/docs/build.md @@ -1,96 +1,7 @@ -# Building the Kimai Docker +# Building the Kimai Docker images -The same docker file is used to build all the tagged images and is configured by combination of build arguments and targets. +The documentation was moved to the official docs page. -## Clone the repo +See [https://www.kimai.org/documentation/building-docker.html](https://www.kimai.org/documentation/building-docker.html) -Before you do anything else you will need to clone this repo and open a terminal in that folder: -```bash -git clone git@github.com:tobybatch/kimai2.git -cd kimai2 -``` - -## Targets - -The docker file has many staging targets but two functional builds are `prod` and `dev` which correspond to the prod and development environments as outlined in the Kimai documentation. The default is `prod` - -```bash - docker build --target=prod . - docker build --target=dev . -``` - -## Build Arguments - -### BASE - -* `BASE=apache` -* `BASE=fpm` - -Selects which PHP wrapper to use. The Apache Debian version bundles an Apache server, and the mod-php wrapper based on a debian buster image. The fpm-alpine version provides the fast CGI version of PHP based on an alpine image. - -The Apache/Debian image is bigger (~940mb) but does not require a second container to provide http services. Use this image for development, tests or evaluation. - -The FPM image is smaller (~640mb) but requires a web server to provide the http services. Use this image in production and see the [docker-compose](docker-compose.md) page for setting up a http server. - -### KIMAI - -This allows over releases of Kimai to be built. You can specify anything that would be passed to a git clone command. - -* A tag or release, e.g. `KIMAI=2.0.31` -* A branch name, e.g. `KIMAI=main` - -### TZ - -The PHP timezone for the php build. Defaults to Europe/Berlin. - -* `TZ=Europe/London` - -## Examples - -Build a dev image of Kimai 2.0.31 that uses the apache bundled web server: - -```bash - docker build --target=dev --build-arg KIMAI=2.0.31 --build-arg BASE=apache . -``` - -Build a prod, FPM image of Kimai 2.0.31, localised for the UK - -```bash - docker build --target=prod --build-arg KIMAI=2.0.31 --build-arg BASE=fpm --build-arg TZ=Europe/London . -``` - -## Extending the image - -If the base image(s) that are here do not contain an extension you need then you can base you own image from the ones built here. - -To keep the final image size down we recommend building the php extension in an intermediate image and then copying that extension into the new image. - -e.g. to add xml/xls support to the apache/debian production image - -```dockerfile -FROM php:7.4.15-apache-buster AS php-base -RUN apt-get update -RUN apt-get install -y libxslt-dev libxml2-dev libssl-dev -RUN docker-php-ext-install -j$(nproc) xsl xml xmlrpc xmlwriter simplexml - -FROM kimai/kimai2:apache-1.12-prod -COPY --from=php-base /usr/local/etc/php/conf.d/docker-php-ext-xsl.ini /usr/local/etc/php/conf.d/docker-php-ext-xsl.ini -COPY --from=php-base /usr/local/lib/php/extensions/no-debug-non-zts-20190902/xsl.so /usr/local/lib/php/extensions/no-debug-non-zts-20190902/xsl.so -``` - -Attention: the above example is outdated and does not work with Kimai 2.x. - -## Building for other architectures, Pi, Mac etc - -Currently, the CI chain doesn't do this for us, but it is possible to build your own image, e.g. for ARM CPUs. - -**Note** Kimai doesn't seem to support 32-bit builds, so older Pi's are not supported. - -The process to build it relies on `Buildx`, install that from here - -And then you can build an alternate architecture: - -```bash - docker buildx build --platform linux/arm64/v8,linux/amd64 -t kimai/kimai2:multi . -``` diff --git a/docs/examples.md b/docs/examples.md index 527cd00..60ec4a3 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,15 +1,5 @@ # Examples -Listed here are example set ups for running the image(s). If you'd like to contribute a new one them please raise a PR for this page. +The documentation was moved to the official docs page. -* [Apache dev](https://github.com/tobybatch/kimai2/tree/main/compose/docker-compose.apache.dev.yml) -* [Apache prod](https://github.com/tobybatch/kimai2/tree/main/compose/docker-compose.apache.prod.yml) -* [FPM dev](https://github.com/tobybatch/kimai2/tree/main/compose/docker-compose.fpm.dev.yml) -* [FPM prod](https://github.com/tobybatch/kimai2/tree/main/compose/docker-compose.fpm.prod.yml) - -None of these images persist the DB between restarts, you will need to add a volume to do that: - - volumes: - - mysql:/var/lib/mysql - -See the [docker-compose.yml](../docker-compose.yml) in the root of the repo. +See [https://www.kimai.org/documentation/docker-compose.html](https://www.kimai.org/documentation/docker-compose.html) diff --git a/docs/helm.md b/docs/helm.md index 9e03a8e..b0480f9 100644 --- a/docs/helm.md +++ b/docs/helm.md @@ -1,3 +1,7 @@ # Helm and Kubernetes -We used to keep a helm chart in this repo, but it is now managed in an external repo. Please go to . +We used to keep a helm chart in this repo, but it is now managed in an external repo. + +The documentation was moved to the official docs page. + +See [https://www.kimai.org/documentation/kubernetes.html](https://www.kimai.org/documentation/kubernetes.html) diff --git a/docs/index.md b/docs/index.md index aaefc95..7134af1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,83 +1,5 @@ # Kimai Dockers -We provide a set of docker images for the [Kimai](https://github.com/kimai/kimai) project. +The documentation was moved to the official docs page. -The built images are available from [Kimai](https://hub.docker.com/r/kimai/kimai2) at Docker Hub. - -## Quick start - -Run the latest production build: - -1. Start a DB - - ```bash - docker run --rm --name kimai-mysql-testing \ - -e MYSQL_DATABASE=kimai \ - -e MYSQL_USER=kimai \ - -e MYSQL_PASSWORD=kimai \ - -e MYSQL_ROOT_PASSWORD=kimai \ - -p 3399:3306 -d mysql - ``` - -2. Start Kimai - - ```bash - docker run --rm --name kimai-test \ - -ti \ - -p 8001:8001 \ - -e DATABASE_URL=mysql://kimai:kimai@${HOSTNAME}:3399/kimai?charset=utf8&serverVersion=5.7 \ - kimai/kimai2:apache - ``` - -3. Add a user using the terminal - - ```bash - docker exec -ti kimai-test \ - /opt/kimai/bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN - ``` - -Now, you can access the Kimai instance at . - -__Note:__ -If you're using Docker for Windows or Docker for Mac, and you're getting "Connection refused" or other errors, you might need to change `${HOSTNAME}` to `host.docker.internal`. -This is because the Kimai Docker container can only communicate within its network boundaries. Alternatively, you can start the container with the flag `--network="host"`. -See [here](https://stackoverflow.com/questions/24319662/from-inside-of-a-docker-container-how-do-i-connect-to-the-localhost-of-the-mach) for more information. - -Keep in mind that this Docker setup is transient and the data will disappear when you remove the containers. - -```bash - docker stop kimai-mysql-testing kimai-test - docker rm kimai-mysql-testing kimai-test -``` - -## Using docker-compose - -This will run the latest prod version using FPM with an nginx reverse proxy - -See the [[docker-compose.yml](https://github.com/tobybatch/kimai2/blob/main/docker-compose.yml)] in the root of this repo. - -## Documentation - -[https://tobybatch.github.io/kimai2/](https://tobybatch.github.io/kimai2/) - -## Documentation - -* [Updating the image](updating.md) -* [All runtime arguments](runtime-args.md#runtime-arguments) -* [Building it yourself](build.md#building-the-kimai-docker) - * [Build arguments](build.md#build-arguments) - * [Extending the image](build.md#extending-the-image) -* [Helm and Kubernetes](helm.md) -* [Troubleshooting](troubleshooting.md#troubleshooting) - * [NGINX and proxying](troubleshooting.md#nginx-and-proxying) - * [Fixing permissions](troubleshooting.md#permissions) - * [500 Server errors](troubleshooting.md#500-server-errors) - * [Older versions](troubleshooting.md#older-version) -* [Examples](examples.md) - * [docker-compose](examples.md#docker-compose) - * [apache dev instance](examples.md#apache-dev) - * [fpm prod instance](examples.md#fpm-prod) - -## Helping out - -If you find a bug or have a feature request then create a tickets [here](https://github.com/tobybatch/kimai2/issues). We'd like to upgrade the dockerhub account to a rate free account and if you'd like to help with that then please donate via [paypal](https://www.paypal.com/paypalme/tobybatchuk). +See [https://www.kimai.org/documentation/docker.html](https://www.kimai.org/documentation/docker.html) diff --git a/docs/runtime-args.md b/docs/runtime-args.md index da92ab4..8d703b7 100644 --- a/docs/runtime-args.md +++ b/docs/runtime-args.md @@ -1,56 +1,5 @@ # Runtime Arguments -The following settings can set at runtime: +The documentation was moved to the official docs page. -## PHP Settings - -### Memory limit - -The maximum amount of memory a script may consume, - -```bash -memory_limit=512M -``` - -## Kimai core settings - -See the Kimai and Symfony docs for more info on these. - -```bash -DATABASE_URL=mysql://user:pass@hodt/dbname?charset=utf8&serverVersion=5.7 -APP_SECRET=change_this_to_something_unique -TRUSTED_PROXIES=nginx,localhost,127.0.0.1 -TRUSTED_HOSTS=nginx,localhost,127.0.0.1 -MAILER_FROM=kimai@example.com -MAILER_URL=null://localhost -``` - -Start up values: - -If set, then these values will be used to create a new admin user (if not yet existing). - -```bash -ADMINPASS= -ADMINMAIL= -``` - -## Changing UID and GID - -It is possible to set the user that FPM or Apache run as. If the user does not exist a new user called www-kimai is created and the server is then run under that user. Note these must be numbers, not names. - -```bash -USER_ID=1000 -GROUP_ID=1000 -``` - -## Alternate DB config - -It is possible to pass the DB config in individual values. If the ENV variable ```DB_TYPE``` is set then the following values will be expected: - -The ```DB_TYPE``` must be `mysql`: - -* ```DB_USER``` defaults to ```kimai``` -* ```DB_PASS``` defaults to ```kimai``` -* ```DB_HOST``` defaults to ```sqldb``` -* ```DB_PORT``` defaults to ```3306``` -* ```DB_BASE``` defaults to ```kimai``` +See [https://www.kimai.org/documentation/docker.html](https://www.kimai.org/documentation/docker.html#runtime-arguments) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8b60952..4a0f3d2 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,44 +1,5 @@ # Troubleshooting -## NGINX and proxying +The documentation was moved to the official docs page. -While outside the direct responsibility of this project we get a lot of issues reported that relate to proxying with NGINX into the FPM container. - -Note that you will need to set the name of your NGINX container to be in the list of TRUSTED_HOSTS when you start the Kimai container. - -## ARM support - -We don't build ARM images at the moment. We use git hub actions to auto build releases and I can get them to build as multi arch images. The images build and run fine, but you'll need to build them yourself. See [Building it yourself](https://tobybatch.github.io/kimai2/build.html#building-the-kimai-docker) on how to do that. - -If you fancy trying to fix the multi arch build, I have an on going attempt to do that in the branch `add-buildx-support` using `buildx` - -## Permissions - -If you are mounting the code base into the container (`-v $PWD/kimai:/opt/kimai`) then you will need to fix the permissions on the var folder. - -```bash -docker exec --user root CONTAINER_NAME chown -R www-data:www-data /opt/kimai/var -``` - -or - -```bash -docker-compose --user root exec CONTAINER_NAME chown -R www-data:www-data /opt/kimai/var -``` - -## 500 Server errors - -Around nine out of ten of the bugs raised are related to the TRUSTED_HOSTS value. If you get a 500 then check that the `TRUSTED_HOSTS` environment variable is set to either your hostname or the hostname of your proxy server (nginx etc). In the docker-compose environment that is the container name of the nginx container. - -## Older version - -While we do backport bug fixes we only thoroughly test them against the latest release of Kimai. We keep the older tags available for those who do not wish to upgrade, but if you encounter a bug then first retest after pulling the latest tag -before raising an issue. - -## Allowed memory size exhausted - -If you encounter an error like `Allowed memory size of 134217728 bytes exhausted` during cache reload, you can instruct PHP to use more memory for that one call with passing the memory limit as runtime parameter: - -```bash -php -d memory_limit=1G ../../bin/console kimai:reload --env=prod -``` +See [https://www.kimai.org/documentation/docker-troubleshooting.html](https://www.kimai.org/documentation/docker-troubleshooting.html) diff --git a/docs/updating.md b/docs/updating.md index e338207..f628855 100644 --- a/docs/updating.md +++ b/docs/updating.md @@ -1,69 +1,6 @@ -# Upgrading +# Upgrading Kimai docker -BACK UP EVERYTHING. The database, the mounted volumes, everything. Please. Pretty please. +The documentation was moved to the official docs page. -While this process (almost) always works there can be errors, and we really don't want you to lose any data. +See [https://www.kimai.org/documentation/docker-updates.html](https://www.kimai.org/documentation/docker-updates.html) -## The apache image - -Just change the tag name and restart the image. - -## The fpm image - -The FPM image will need to be upgraded with a manual step. Because the FPM image will have a HTTP proxy (normally nginx) container serving the static assets the `public` directory is mounted into that nginx container. This is done via volumes: - -```yaml -version: '3.5' -services: - kimai: - image: kimai/kimai2 - ... - volumes: - - public:/opt/kimai/public - ... - nginx: - ... - volumes: - - public:/opt/kimai/public:ro - ... -``` - -When the kimai image is updated, and the container is restarted any new assets in the public directory are never included. These will be things like CSS files, images and especially version specific javascript code! To fix this you need to copy the newer files from a fresh image over the top. - -```bash -# You might need to use `docker volume ls | grep kimai` and see how your Kimai public volume really is named on your system! -me@myhost $ docker run --rm -ti -v kimai_public:/public --entrypoint /bin/bash kimai/kimai2 -# ^^^^^^^^^^^^ -> Kimai public volume -bash-5.0$ cp -r /opt/kimai/public / -bash-5.0$ exit -me@myhost $ -``` - -Now you'll need to tell the running kimai to update its assets: - -```bash -me@myhost $ docker-compose exec kimai /opt/kimai/bin/console assets:install -``` - -That should do it. - -### Automated upgrade - -If you have backed up everything you can use the automated update image that will do the work for you. - -Add this to the services section of your docker-compose: - -```yaml -autoupdate: - image: kimai/kimai2 - volumes: - - public:/public - - ./bin/copy-public.sh:/copy-public.sh - entrypoint: /copy-public.sh -``` - -You'll still need to tell the running kimai to update its assets: - -```bash -me@myhost $ docker-compose exec kimai /opt/kimai/bin/console assets:install -```