Modern Resource-Order-Activity Working Time, Absence Management, and Period Closing System

Features • Screenshots • Architecture • Quick Start • Docker • Mail Config • Operations • REST API • License

Chronivaro is a lightweight, high-performance working time and absence management platform built on the Strolch framework. It delivers precise multi-block daily time tracking with automatic break derivation, comprehensive vacation journal accounting, monthly period closing workflows with calculation snapshots, role-based supervisor approval queues, and tenant-wide administration.

The system is packaged as a standalone application distribution with an embedded Eclipse Jetty 12 runtime and a lib/ directory containing all dependencies, serving both modern Web Component frontend assets and REST API endpoints without requiring an external servlet container.

Chronivaro offers a responsive single-page web interface tailored for employees, supervisors, HR managers, and administrators.

🔍 Click to preview key interface highlights

Live Team Presence ("Who is Working?")	Multi-Block Daily Time Recording

Absence Requests & Vacation Balances	Supervisor Approvals Inbox

Monthly Period Closing & Calculation Snapshot	Master Data & Employee Administration

📚 Explore the complete visual walkthrough: See the Full UI Screenshots Gallery for all 21 application screens, including reporting views, work schedule definitions, holiday calendars, and audit logs.

• ⏱️ Time Tracking & Live Timer: Real-time start/stop timer, manual work entry creation/editing, multi-interval daily tracking, automatic break calculation from time gaps, and overnight shift handling.
• 🌴 Absence & Vacation Management: Multi-type absence requests (Vacation, Sickness, Military/Civil Defense, Special Leave) with flexible units (Full-Day, Half-Day, Hours), quota accounting, and balance progression.
• ✅ Supervisor Approval Queues: Dedicated approval inbox for team supervisors and HR managers with optimistic concurrency validation, team/type filters, and mandatory rejection feedback.
• 📅 Monthly Period Closing Workflow: Employee period submission, calculation snapshot generation (actual vs. target hours, overtime/undertime), supervisor approval, and HR/Admin period locking.
• 📊 Reporting & RFC 4180 CSV Export: Personal summaries, monthly balance histories, vacation account journals, team performance overviews, and filtered absence reports with UTF-8 BOM encoding for Excel.
• 👥 Tenant Administration & Self-Service: Comprehensive master data management for employees, employment schedules, teams, locations, holiday calendars (including extensible CSV holiday import for formats like "fcal.ch DE"), absence types, global tenant parameters, and user self-service password management.
• 🔒 Security & Audit Logging: Role-based access control (Employee, Supervisor, HR, Administrator), immutable append-only audit trail logging all state transitions, approvals, and configuration changes.
• 🚀 Standalone Embedded Jetty Execution: Executable standalone JAR (chronivaro.jar) with manifest classpath loading from lib/ (and packaged distribution archive chronivaro.tar.gz) delivering frontend assets and REST API endpoints out-of-the-box.

Chronivaro is structured as a modular Maven project separating core domain logic, REST APIs, frontend web components, and standalone packaging:

graph LR
    Client[Web Browser / API Clients] -->|HTTP / JSON| Jetty[Embedded Jetty 12 Server]
    Jetty -->|Static Routing| WebUI[chronivaro-web / Frontend SPA]
    Jetty -->|JAX-RS Jersey| REST[chronivaro-rest / REST API]
    REST -->|Services & Commands| Core[chronivaro-core / Strolch Domain Model]
    Core -->|In-Memory TX| Strolch[Strolch Runtime & Data Persistence]

• Java Runtime: JDK 25 (or JDK 24+)
• Build Tool: Maven 3.6+
• Browser: Modern web browser (Firefox, Chrome, Edge, Safari)

To build all modules and package the distribution archive:

mvn clean install

To run unit and integration tests:

mvn test

The resulting executable JAR, dependency lib/ folder, and distribution tarball are located at:

chronivaro-app/target/chronivaro.jar
chronivaro-app/target/lib/
chronivaro-app/target/chronivaro.tar.gz

Start Chronivaro as a standalone application using Java:

java -jar chronivaro-app/target/chronivaro.jar --port 8080 --runtime ./runtime --env dev

The application will be accessible at http://localhost:8080.

1. Build the project from the root:

   mvn clean package -DskipTests

2. Start the container stack using Docker Compose:

   docker compose -f docker-compose-dev.yml up --build

3. Open http://localhost:8080 in your browser.

Build and tag the local Docker image:

./build-docker-image.sh

Build, tag, and push to the remote registry (repo.strolch.li):

./build-and-push-docker.sh

To package a clean, ready-to-use runtime environment tarball for deployment:

# Using the shell script
./build-runtime-tarball.sh -o runtime.tar.gz

# Or using the Java class directly
java -cp "chronivaro-app/target/*" ch.eitchnet.chronivaro.app.RuntimeArchiveGenerator -s runtime -o runtime.tar.gz

The packaging process automatically:

• Copies all necessary configuration and model files from runtime/.
• Excludes temporary/session files (runtime/temp/) and dbStore directories (runtime/data/dbStore/).
• Sanitizes PrivilegeUsers.xml to remove personal user accounts while preserving system accounts (State=SYSTEM) and the admin user.

Chronivaro includes an automated release script (release.sh) to update Maven POM versions to the release version, sign and annotate git tags, build artifacts (standalone application distribution tarball, sanitized runtime tarball, SHA-256 checksums), sign all release assets with GPG (.asc detached signatures), generate release notes, publish GitHub Releases, announce releases on Mastodon, and automatically increment the POM version to the next minor snapshot (e.g. 0.2.0-SNAPSHOT):

# Dry-run / Simulation mode (inspect release notes, assets, and version updates preview):
./release.sh --simulate

# Full release for version 0.1.0 with Maven build:
./release.sh -v 0.1.0 -b

# Release with custom next development version:
./release.sh -v 0.1.0 -n 0.2.0-SNAPSHOT -b

# Release and announce on Mastodon:
./release.sh -v 0.1.0 -b -m --mastodon-instance mastodon.social --mastodon-token $MASTODON_TOKEN

Configuration can be provided via flags, environment variables (GITHUB_TOKEN, MASTODON_INSTANCE, MASTODON_ACCESS_TOKEN, MASTODON_VISIBILITY), or loaded automatically from the release environment file ${HOME}/.config/chronivaro/release.env.

1. Prepare directory structure on host:

   mkdir chronivaro && cd chronivaro
   mkdir -p logs runtime/{config,data,temp}

2. Copy configuration files from runtime/ into runtime/ (config/, data/, temp/).
3. Set secure values for secretKey and secretSalt in runtime/config/PrivilegeConfig.xml.
4. Configure mail delivery in runtime/config/StrolchConfiguration.xml (see Email Delivery & MailHandler Configuration below).
5. Optional: Configure file logging in runtime/config/logback.xml to persist logs to /chronivaro-logs (mounted to ./logs).
6. Copy docker-compose.yml to the directory.
7. Launch the container:

   docker compose up -d
   docker compose logs -f

When upgrading Chronivaro to a newer version, new features may introduce updated templates (runtime/data/Templates.xml), new service or search privileges (runtime/config/PrivilegeRoles.xml), or new configuration parameters (runtime/data/Model.xml).

Every GitHub release includes:

• runtime-upgrade-<prev_tag>-to-<new_tag>.patch: A unified diff patch file that can be applied directly to an existing deployment's runtime/ directory.
• RELEASE_NOTES.md: Markdown release notes with detailed explanations of changed runtime files and diff snippets.

1. Backup Existing Runtime Directory:

   # Always take a backup before upgrading
   tar -czf "runtime-backup-$(date +%Y%m%d%H%M%S).tar.gz" runtime/

2. Download Release Assets & Patch: Download the new application distribution archive (chronivaro-<version>.tar.gz), the patch file (runtime-upgrade-<from>-to-<to>.patch), and checksums (SHA256SUMS.txt). Verify integrity:

   sha256sum --check SHA256SUMS.txt

3. Dry-Run / Test Patch Application: From your installation root directory (containing runtime/):

   # Test with patch utility:
   patch --dry-run -p1 < runtime-upgrade-v0.2.0-to-v0.3.0.patch
   
   # Or test with git (if your runtime directory is version-controlled):
   git apply --check runtime-upgrade-v0.2.0-to-v0.3.0.patch

4. Apply the Patch:

   # Using patch:
   patch -p1 < runtime-upgrade-v0.2.0-to-v0.3.0.patch
   
   # Or using git:
   git apply runtime-upgrade-v0.2.0-to-v0.3.0.patch

5. Review Custom Configurations: If your deployment has customized users (PrivilegeUsers.xml) or custom tenant data (Model.xml), review any modified sections to ensure your settings are preserved.

6. Update Application Binaries & Restart:

   • Standalone Deployments: Extract the new chronivaro.jar and lib/ directory, then restart the service:

     tar -xzf chronivaro-<version>.tar.gz
     sudo systemctl restart chronivaro

   • Docker Deployments: Update the image tag in docker-compose.yml and restart the container:

     docker compose pull
     docker compose up -d

You can also use the bundled CLI tool to generate markdown upgrade instructions or unified diffs between any two git tags/revisions:

# Print markdown upgrade instructions to stdout
./generate-upgrade-instructions.sh -f v0.2.0 -t HEAD

# Save upgrade instructions to a file
./generate-upgrade-instructions.sh -f v0.2.0 -t v0.3.0 -o UPGRADE.md

Chronivaro uses Strolch's li.strolch.privilege.handler.MailUserChallengeHandler in runtime/config/PrivilegeConfig.xml to deliver user registration challenges and password reset tokens.

Challenge delivery is handled by the MailHandler component configured in runtime/config/StrolchConfiguration.xml:

• Development (SimulatedMailHandler): By default in local/dev environments, SimulatedMailHandler intercepts outgoing emails and logs challenge links to the standard log output, allowing local testing without an SMTP server.
• Production (SmtpMailHandler): For production deployments, switch the implementation to SmtpMailHandler and configure your SMTP server connection parameters. No modifications to PrivilegeConfig.xml are needed.

<Component>
    <name>MailHandler</name>
    <api>li.strolch.handler.mail.MailHandler</api>
    <!-- For production SMTP: -->
    <!-- <impl>li.strolch.handler.mail.SmtpMailHandler</impl> -->
    <!-- For local development / simulation: -->
    <impl>li.strolch.handler.mail.SimulatedMailHandler</impl>
    <Properties>
        <fromAddr>Chronivaro &lt;[email protected]&gt;</fromAddr>
        <username>[email protected]</username>
        <password>XXX</password>
        <auth>true</auth>
        <startTls>true</startTls>
        <host>smtp.gmail.com</host>
        <port>587</port>
        <sign>false</sign>
        <!-- Optional PGP signing key in runtime/config/ -->
        <signingKey>[email protected]</signingKey>
        <signingKeyPassword>myKeyPassword</signingKeyPassword>
        <encrypt>false</encrypt>
        <!-- Optional comma-separated list of recipient PGP public keys in runtime/config/ -->
        <recipientPublicKeys>[email protected]</recipientPublicKeys>
    </Properties>
</Component>

See docs/OPERATIONS.md for detailed descriptions of all MailHandler configuration properties.

For testing, demonstration, or initial development environments, Chronivaro includes a GenerateSampleDataJob that creates a rich dataset (holiday calendars, locations, teams, employees with working schedules, defaults, time entries, absences, on-call periods, and period approvals).

The job is configured as a StrolchJob resource in runtime/data/Model.xml:

<Resource Id="GenerateSampleDataJob" Name="GenerateSampleDataJob" Type="StrolchJob">
    <ParameterBag Id="parameters" Name="Parameters" Type="Parameters">
        <Parameter Id="className" Name="Class Name" Type="String" Value="ch.eitchnet.chronivaro.core.jobs.GenerateSampleDataJob"/>
        <Parameter Id="mode" Name="Job Mode" Type="String" Interpretation="Enumeration" Uom="JobMode" Value="Manual"/>
    </ParameterBag>
</Resource>

When set to JobMode.Manual, it can be triggered on demand via the Strolch Jobs API or during first startup. StrolchJob definitions are automatically excluded from production runtime distribution tarballs generated by build-runtime-tarball.sh.

1. Initial Login: Navigate to http://localhost:8080 and log in with default credentials:
   • Username: admin
   • Password: admin
2. Mandatory Password Change: Immediately change the default admin password via the user profile dropdown in the top header.
3. First Employee Onboarding:
   • Verify/configure Locations, Teams, and Work Schedule Templates under Administration.
   • Create the employee profile in Administration -> Employees, assigning Team, Location, and Schedule Template. Saving the employee automatically provisions the linked user account.
   • Initiate registration by selecting Actions -> Register on the employee row.
   • The employee completes the registration form with their challenge code to set their password, logs in, and can start tracking time immediately.

Chronivaro provides unauthenticated standard endpoints for container orchestration, load balancers, and health checks:

Chronivaro uses SLF4J with Logback for structured logging. Every HTTP request carries an X-Correlation-Id header mapped to the logging MDC context:

2026-08-19 13:30:00.123 [qtp1234567-24] [corrId=e4a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c] INFO  ch.eitchnet.chronivaro.rest.resource.ChronivaroResource - Processed presence query

Clients can supply custom correlation IDs via the X-Correlation-Id request header; otherwise, the server automatically generates and returns a UUID correlation ID in the response headers.

Logging configuration can be customized dynamically by placing logback.xml in runtime/config/. When the Strolch agent starts, LoggingLoader.reloadLogging(this.configPathF) reloads Logback configuration from runtime/config/logback.xml.

By default, the standard Docker container provides /chronivaro-logs as a mount point for persistent log files. To persist logs:

1. Ensure runtime/config/logback.xml contains a RollingFileAppender pointing to /chronivaro-logs/chronivaro.log (or ${LOG_DIR:-/chronivaro-logs}/chronivaro.log).
2. Mount the log directory in Docker Compose:

   volumes:
     - ./runtime:/chronivaro-runtime
     - ./logs:/chronivaro-logs

Chronivaro supports Personal Access Tokens (PAT) for third-party integrations (e.g. desktop widgets, CLI scripts, mobile timers):

• Generation & Management: Users can generate and revoke tokens in the Web UI under Profile -> Personal Access Tokens (#tokens).
• Validity & Expiration: Tokens can be created with custom validity periods (specified in days, months, or years; defaulting to 1 year) or configured with no expiration.
• Preset Scopes:
  • DESKTOP_TIMER: Permissions to start/stop timers, fetch status/summaries, and read personal entries.
  • READ_ONLY_TIMES: Read-only access to /me/* entries, summaries, and presence.
  • FULL_PERSONAL: Full scope of the user's personal /me/* permissions.
• Authentication: Pass the token via the Authorization header:

  Authorization: Bearer <tokenId>:<tokenSecret>

  (Or Authorization: <tokenId>:<tokenSecret> or HTTP Basic Auth with username <tokenId> and password <tokenSecret>)

Users can test their PAT against the REST API with standard curl commands (assuming the server is hosted at http://localhost:8080):

curl -X GET "http://localhost:8080/rest/chronivaro/v1/me/timer/status" \
  -H "Authorization: Bearer <tokenId>:<tokenSecret>" \
  -H "Accept: application/json"

curl -X POST "http://localhost:8080/rest/chronivaro/v1/me/timer/start" \
  -H "Authorization: Bearer <tokenId>:<tokenSecret>" \
  -H "Content-Type: application/json" \
  -d '{
    "workingLocation": "OFFICE",
    "comment": "Working on feature implementation",
    "isOnCall": false
  }'

curl -X POST "http://localhost:8080/rest/chronivaro/v1/me/timer/stop" \
  -H "Authorization: Bearer <tokenId>:<tokenSecret>" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Lunch break"
  }'

• 🖼️ Screenshots Gallery: Comprehensive visual tour of all application views and administration screens.
• ⚙️ Operations & Deployment Guide: Production deployment, container setup, systemd integration, and disaster recovery.
• 📡 OpenAPI Specification: Comprehensive REST API contract with request/response schemas and examples.
• 📋 Implementation Backlog: Granular task breakdown and implementation history.
• 📊 Implementation Status: Architectural decisions, delivered milestones, and verification summary.

Chronivaro is free software licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).