Improve Documentation for Building a Docker Image from a Local Repo using docker-compose for Development

[WSHAPER]

Describe the problem

Currently, the documentation on setting up Kimai for development using Docker is specifically tailored to Docker alone, whereas the documentation about setting up using docker-compose, especially concerning building a kimai Docker image locally with changes from the local repository (COPY . into the Docker container) and setting it up using docker-compose, are either non-existent very vague.

Describe the solution you'd like

I suggest adding a guide to include instructions on:

• How to build the Kimai Docker image locally, incorporating changes made to the local repository. This should cover the use of COPY . in the Dockerfile to include local modifications.
• Setting up and configuring Kimai using docker-compose for a development environment. This includes instructions on how to modify the docker-compose.yml file to use the locally built image instead of pulling from a Docker registry.
• Examples of common configurations for development, such as setting up volumes for live code reloading or adjusting environment variables for debugging.

I am happy to contribute to the documentation update myself; I only need some initial guidance or pointers on where to start and any specific considerations or preferences regarding documentation structure and content.

Describe alternatives you've considered

As alternatives, I've looked into general Docker and docker-compose documentation to piece together how it might work specifically for Kimai, but this approach is time-consuming and may not cover best practices or specific configurations beneficial for Kimai development. Community forums and GitHub issues provide some insights, but these are scattered and not as accessible as official documentation.

Screenshots

No response

[Not-Code]

Hi @WSHAPER, first thanks for getting in touch.
On the topic of docker-compose there's a section in the documentation that provides some examples on how to get things started.
It's already under the maintainers' radar and it will likely be revisited in the future.

Still we have some sort of disagreement on what should be documented. If you ask me, the problem of the current documentation (about docker) is that it's sort of confusing. And in my opinion less information, but of higher quality, is better for the average user.

Also engineering time is a finite resource and should not be used to document things, but should create code that documents itself 😄 .
If you look at the current Kimai HEAD all your question are answered: CI is described here and the Dockerfile is here. These resources are enough for anyone with sufficient technical knowledge.

And if someone doesn't get what's going on there, it's probably best that they just use the images provided by the project. It's not the project's responsibility to explain how dockers or github worlflows work.

I know I might sound harsh, and I'm sorry, but I'm used to say what I really think instead of beating around the bush. And anyway this is just an opinion and, for what it is, it could simply be wrong 😄 .

[WSHAPER]

Hi @Not-Code,

Thank you for your feedback and time. While I understand and appreciate the emphasis on self-documenting code and the valuable pointers provided towards the Kimai HEAD, CI descriptions, and Dockerfile resources, I'd like to highlight a specific area where targeted documentation could immensely lower the entry barrier for new contributors and developers aiming to customize or extend Kimai, particularly in the context of Docker and docker-compose setups.

I would like to propose the following split structure for Dockerfiles that aims to clarify the setup for different environments and purposes (which supports the goal of self-documentation):

• Dockerfile.source for fetching source code.
• Dockerfile.php-extensions for building PHP extensions.
• Dockerfile.fpm-base for the FPM environment setup.
• Dockerfile.apache-base for the Apache environment setup.
• Dockerfile.dev for development-specific configurations.
• Dockerfile.prod for production-specific configurations.

This approach could streamline the process for contributors, making it easier to understand and engage with the project.

Specific Use Case

The following example leverages docker-compose and a Dockerfile to enable hot-loading of local changes, significantly enhancing the developer experience by providing a seamless integration and testing workflow, without the need to pull a docker image.
Adapted from source: Beginner-friendly introduction to DevOps with Docker on Windows

# Dockerfile example for a live development environment with Node.js
FROM node:8.6
RUN mkdir /build-dir && WORKDIR /build-dir
COPY ./src/package.json /build-dir
RUN npm install -g nodemon && npm install
RUN mkdir -p /usr/src/app && WORKDIR /usr/src/app
RUN ln -s /build-dir/node_modules node_modules
COPY ./src/ /usr/src/app/
EXPOSE 3000
CMD ["npm", "run", "debug"]

# docker-compose.yml example for MySQL and Node services
version: '3.4'
services:
  mysql:
    environment:
      MYSQL_DATABASE: nodeappdb
      MYSQL_PASSWORD: nodeapppw
      MYSQL_ROOT_PASSWORD: hellosupersafepasswordforroot
      MYSQL_USER: nodeappuser
    image: mysql:5.7
    command: "--lower_case_table_names=1 --max-allowed-packet=33554432"
    volumes: - ./db:/var/lib/mysql
  node:
    ports: - "3000:3000"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/healthcheck || exit 1"]
    environment: - NODE_ENV=development
    build: context: . dockerfile: Dockerfile
    depends_on: - mysql
    volumes: - ./src/:/usr/src/app/ - ./node_modules:/usr/src/app/node_modules - ./command.sh:/command.sh
networks: default:

# command.sh for Node.js service in docker-compose
#!/bin/bash
cp -r /build-dir/node_modules/ /usr/src/app/
exec npm run debug

Thank you for considering my suggestions. I look forward to your feedback!