Skip to content
This repository has been archived by the owner on Jan 8, 2024. It is now read-only.

Commit

Permalink
Migrated documentation to Kimai website
Browse files Browse the repository at this point in the history
  • Loading branch information
@kevinpapst
kevinpapst committed Nov 17, 2023
1 parent 799a534 commit 1eadcb1
Show file tree
Hide file tree
Showing 8 changed files with 21 additions and 349 deletions.
6 changes: 2 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
95 changes: 3 additions & 92 deletions docs/build.md
View file
Original file line number Diff line number Diff line change
@@ -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 [email protected]: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 <https://github.com/docker/buildx>

And then you can build an alternate architecture:

```bash
docker buildx build --platform linux/arm64/v8,linux/amd64 -t kimai/kimai2:multi .
```
14 changes: 2 additions & 12 deletions docs/examples.md
View file
Original file line number Diff line number Diff line change
@@ -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)
6 changes: 5 additions & 1 deletion docs/helm.md
View file
Original file line number Diff line number Diff line change
@@ -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 <https://github.com/robjuz/helm-charts/tree/master/charts/kimai2>.
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)
82 changes: 2 additions & 80 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -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 [email protected] ROLE_SUPER_ADMIN
```

Now, you can access the Kimai instance at <http://localhost:8001>.

__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)
55 changes: 2 additions & 53 deletions docs/runtime-args.md
View file
Original file line number Diff line number Diff line change
@@ -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, <https://php.net/memory-limit>

```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
[email protected]
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)
43 changes: 2 additions & 41 deletions docs/troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -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)
Loading

0 comments on commit 1eadcb1

Please sign in to comment.