Ist bei euch die Zeiterfassung auch gerade ein großes Thema? Das trifft sich gut!

Durchstarten mit der Zeiterfassung! Folgende Funktionen sind bereits enthalten:

• Erfassen von Zeiten: Kommt-Geht Erfassung oder einzelne Zeitbuchungen
• Stoppuhr-Modus
• Visualisierung der geleisteten Stunden auf Wochen und Monatsebene
• Berichte für eigene erfasste Stunden (CSV-Download)
• Berichte für Vorgesetzte (CSV-Download)

Unsere Entwicklung lebt von eurem Feedback. Wir freuen uns die Zeiterfassung mit euch zusammen voranzubringen.

• GitHub Issue
• E-Mail

Wenn du mehr Informationen und Bilder über dieses Projekt sehen möchtest dann schaue auf unserer Landingpage vorbei.

⚠️ Die Dokumentationen zu Betrieb und Entwicklung sind aktuell nur in englischer Sprache verfügbar.

• JDK 17
• Docker 20.10+
• PostgreSQL 9.6+
• E-Mail-Server
• OpenID Connect identity provider

The application is available as docker image on GitHub and Docker Hub

The application has a configuration file in the src/main/resources directory. This includes certain basic settings and default values. However, these alone are not sufficient to put the application into production. Specific configurations such as the database, e-mail server and security provider must be stored in a separate configuration file or handed via environment variables.

The options available with Spring Boot for using your own configuration file or environment variables can be found in the 'External Config' Reference

The application uses a PostgresSQL database management system to store the data. Create a database in your PostgresSQL database management system with e.g. the name zeiterfassung. and a user with access rights for this database and configure it

spring.datasource.url=jdbc:postgresql://$HOST:$PORT/$DATABASENAME
spring.datasource.username=$USER
spring.datasource.password=$PASSWORD

When you start the application for the first time, all database tables are created automatically.

To configure the e-mail server, the following configurations must be made.

zeiterfassung.mail.from[email protected]
zeiterfassung.mail.fromDisplayName=zeiterfassung
zeiterfassung.mail.replyTo[email protected]
zeiterfassung.mail.replyToDisplayName=replyto

spring.mail.host=$HOST
spring.mail.port=$PORT
spring.mail.username=$USERNAME
spring.mail.password=$PASSWORD

All other spring.mail.* configurations can be found in the Spring Documentation E-Mail be viewed.

As security provider OIDC-based security providers are possible to use (e.g. Keycloak, Microsoft Azure AD or other 'OpenID Connect providers'). To configure the security provider, the following configurations must be made.

spring.security.oauth2.client.registration.default.client-id=zeiterfassung
spring.security.oauth2.client.registration.default.client-secret=$OIDC_CLIENT_SECRET
spring.security.oauth2.client.registration.default.client-name=zeiterfassung
spring.security.oauth2.client.registration.default.provider=default
spring.security.oauth2.client.registration.default.scope=openid,profile,email,roles
spring.security.oauth2.client.registration.default.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.default.redirect-uri=$OIDC_REDIRECT_URI
spring.security.oauth2.client.provider.default.issuer-uri=$OIDC_ISSUER_URI
zeiterfassung.security.oidc.login-form-url=$OIDC_LOGIN_FORM_URL

Zeiterfassung is using user permissions from oidc claim groups for mapping possible permissions:

• ZEITERFASSUNG_USER: General access to the application aund time tracking features
• ZEITERFASSUNG_VIEW_REPORT_ALL: Access to reports of other users
• ZEITERFASSUNG_WORKING_TIME_EDIT_ALL: Allowed to edit working time of all users

If you're using Keycloak, this can be configured via a predefined OIDC client mapper with name groups. Create both permissions as Realm roles and assign user to those roles.

Sollten beim Starten der Anwendung Probleme auftreten, lässt sich in der Konfigurationsdatei eine ausführliche Debug-Ausgabe konfigurieren, indem das logging.level.* pro Paket konfiguriert wird,

logging.level.de.focusshift.zeiterfassung=TRACE
logging.level.org.springframework.security=TRACE

All other logging.* configurations can be found in the Spring Documentation Logging be viewed.

Since the application is based on Spring Boot, it can be installed very conveniently as a service. How exactly this works, can be found in the corresponding chapters of the Spring Boot documentation:

• Linux Service
• Windows Service

You can configure a launchpad that shows other applications the user can navigate to.

launchpad.name-default-locale=de

launchpad.apps[0].url=https://example.org
launchpad.apps[0].name.de=Anwendung 1
launchpad.apps[0].name.en=App 1
launchpad.apps[0].icon=

launchpad.apps[1].url=https://example-2.org
launchpad.apps[1].name.de=Anwendung 2
launchpad.apps[1].name.en=App 2
launchpad.apps[1].icon=

Launchpad has custom messages. So you have to tell Spring about the messages file:

spring.messages.basename=messages,launchpad-core

• (required) messages is the default application messages properties
• (required) launchpad-core provides launchpad specific messages

To run the docker container e.g. with following command:

docker run -p 8080:8080 ghcr.io/urlaubsverwaltung/zeiterfassung/zeiterfassung:$VERSION

Replace the $VERSION with a specific version from the docker images.

As part of a docker-compose setup all configurations can be set in service definition.

An example for an environment of Zeiterfassung with docker-compose can be found here.

• JDK 17
• Docker 20.10.+
• Docker Compose

Without GitHub account

https://github.com/urlaubsverwaltung/zeiterfassung.git

with GitHub account

git clone [email protected]:urlaubsverwaltung/zeiterfassung.git

Start the needed dependencies like the database and the keycloak server with

docker-compose up -d

The Zeiterfassung is a Spring Boot application and can be started with the dev-singletenant profile that will also generate demo data.

./mvnw clean spring-boot:run

and for Windows user with

./mvnw.cmd clean spring-boot:run

The application can then be controlled in the browser via http://localhost:8060/.

With the dev-singletenant profile a Postgres database is used and demo data is created, i.e. time entries, tenants and users. Therefore, you can now log into the web interface with different users.

As a user of a tenant can log in via http://localhost:8060/:

There are some app specific git hooks to automate stuff like:

• Install NodeJS dependencies after git pull when package-lock.json has changed
• Format files on commit

If you want to take advantage of this automation you can run:

git config core.hooksPath '.githooks' 

The git hooks can be found in the .githooks directory.

You can import a db dump created via pg_dump into docker-compose-based postgres:

• paste dump here into root directory and name it dumpfile.sql
• edit docker-compose.yml

services:
  postgres:
  ...
    volumes:
      - ./dumpfile.sql:/tmp/dumpfile.sql:ro

• start with a fresh docker-compose postgres
• open shell to postgres docker container docker-compose exec postgres bash
• exec command inside postgres docker container PGPASSWORD=$POSTGRES_PASSWORD psql -U $POSTGRES_USER -d $POSTGRES_DB -f /tmp/dumpfile.sql

Go to the GitHub action with the name release trigger.

• Click on "Run workflow"
• Add the "Milestone ID" (see in the uri of a milestone)
• Add "Release version"
• Add "Next version"
• Run the workflow

• Icons: https://lucide.dev/ (Github: https://github.com/lucide-icons/lucide)
• Sloth image: https://pixabay.com/de/illustrations/faultiere-säugetiere-pelzig-5599313/