Sync with master branch #141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

Ente merged 39 commits into master from develop

Jan 7, 2026

CHANGELOG.md

-Original file line number
+Diff line change
@@ -1,5 +1,70 @@
     # CHANGELOG
+    ## v8.7
+    * Added automatic update check within the Settings page allowing to see the changelogs and a link to the new Release.
+    * Updated `README.md`
+    * Admins can now select the default worktime type to be selected in the form within the app.json `config` section via the `default_worktime_type` key.
+    * Added function to automatically add keys to app.json after update
+    * Admins can now customize the look and feel of the PDF exports. Please check `README.md` `Exports` section for more information.
+    ## v8.6
+    * Telemetry statistics page for environments using the Telemetry Server. Please check `README.md`
+    ## v8.5.1
+    * Fixed undefined variable warning message <!-- [#133](https://github.com/Ente/timetrack/issues/133) -->
+    * Changed `app.json.sample` default values
+    * Updated README.md <!-- [#134](https://github.com/Ente/timetrack/issues/134) -->
+    * Added `update.sh` script
+    * Internal plugin views can now be hidden
+    * Fix utility plugin 500 error when trying to export data for user that doesn't exist
+    ## v8.5
+    * Fixed an issue with IDs not generated correctly for project items.
+    * Added functionality to delete and edit project items.
+    * Adding users to a project has been made easier.
+    * Internal changes
+    * Added additional plugin permission level
+    * Added 2 new themes
+    ## v8.4.3
+    * Now displaying the instance uuid within the settings page.
+    * Added ability to reset the instance uuid via the settings page.
+    ## v8.4.2
+    * Added user based permissions for plugin views.
+    * Updated plugins to use new permission system.
+    ## v8.4.1
+    **This update requires DB migration** - see `README.md` section `Database`
+    * Added telemetry support (disabled by default, can be enabled within `app.json`)
+    * Added telemetry server to receive telemetry data (see `api/v1/class/telemetry/server/README.md` for more information)
+    ## v8.4
+    * Added `nfcclock` plugin to allow clocking in and out with NFC tags (requires `nfclogin` plugin)
+    * Updated `nfclogin` plugin to version `1.2` (added Toil API route for `nfcclock` called `nfclclock`)
+    * Removed unused `extract_plugin` function from `PluginDevTool` class
+    * Custom language files can now be used with the `i18n` class by placing them within the `data/i18n/custom/` directory. This also works for plugins.
+    ## v8.3.3
+    **This update might require DB migration** - see `README.md` section `Database`
+    * Added migration script for adding the `pid` column to the `projects_items` table for already existing installations. The script will not be executed for new installations.
+    ## v8.3.2
+    * Added script to initialize the database for demo purposes when using Docker (See `README.md`)
+    * Fixed missing `active` column within the `users` table when initializing the database for the first time
     ## v8.3.1
     * Removed deprecated `app` attribute from `general` section within `app.json`
@@ Expand Down @@

README.md

-Original file line number
+Diff line change
@@ Expand Up @@
     - Plugin Support
     - Exporting to PDF/CSV
+    A demo is available here: [https://tt-demo.openducks.org](https://tt-demo.openducks.org)
+    **The demo is available with limited features only, e.g. the plugin system disabled.**
+    **The demo currently does not work as intended...**
+    > You would like to support the project? Consider helping out with the documentation at [https://timetrackd.openducks.org](https://timetrackd.openducks.org) or by contributing to the code.
     ## Installation
     ### Quick Install with Docker
     You can quickly get started with TimeTrack using Docker. Follow these steps:
     * Ensure you have Docker and Docker Compose installed on your system.
-    * Clone the TimeTrack repository: `git clone https://github.com/Ente/timetrack.git` & `cd timetrack`
+    * Clone the TimeTrack repository: `git clone https://github.com/Ente/timetrack.git` & `cd timetrack` - **The develop branch should not be used unless you know what you are doing. Download the latest release [https://github.com/ente/timetrack/releases/latest](here)**
     * Build the Docker image: `docker build -t openducks/timetrack .`
     * Create a `app.json` configuration file based on the provided sample below: `cp api/v1/inc/app.json.sample api/v1/inc/app.json` and edit it to fit your needs.
       * Adjust the database settings if needed (at least `db_password`)
@@ Expand All @@
     Certain features, like the NFC login may require additional setup for parsing the USB device.
+    If you want to use the demo, you can run the provided `demo_setup.sh` script within the project root. This will automatically setup the database with demo data (worktimes and users) and rebuilds the entire container.
+    You may want to set the `demo` setting within the `app.json` to `true` to display the demo credentials on the login page.
     ### Requirements
     - PHP 8.2 (`curl|gd|gmp|intl|mbstring|mysqli|openssl|xsl|gettext|dom|ldap`) - tested with PHP 8.2.26
@@ Expand All @@
     Simply install the software by following these steps:
     - Install php and requirements: `sudo apt update && sudo apt install php8.2 php8.2-curl php8.2-gd php8.2-gmp php8.2-intl php8.2-mbstring php8.2-mysqli php8.2-pgsql php8.2-xsl php8.2-gettext php8.2-dom php8.2-ldap composer git mariadb-server apache2 -y` and enable the apache rewrite mod `a2enmod rewrite && service apache2 restart`. If you do not want to use apache2 you can skip this step.
-    - Git clone timetrack to e.g. `/var/www`: `cd /var/www && git clone https://github.com/Ente/timetrack.git && cd timetrack`
+    - Git clone timetrack to e.g. `/var/www`: `cd /var/www && git clone https://github.com/Ente/timetrack.git && cd timetrack` - **The develop branch should not be used unless you know what you are doing. Download the latest release [https://github.com/ente/timetrack/releases/latest](here)**
     - Install requirements for composer `composer install`
     - Create a new database, e.g. with the name `ab` and create a dedicated user, login (`mysql -u root -p`) then e.g. `timetool`: `CREATE DATABASE ab;` and `CREATE USER 'timetool'@'localhost' IDENTIFIED BY 'yourpassword';` and `GRANT ALL PRIVILEGES ON ab.* TO 'timetool'@'localhost';` don't forget to `FLUSH PRIVILEGES;`!
     - Configure `app.json` (see below - required changes: `base_url`, `db_user`, `db_password`, `smtp` section and any other if your installation is different) then `mv api/v1/inc/app.json.sample app.json && cd /var/www/timetrack`
     - Run DB migrations: `vendor/bin/phinx migrate`
-    - Start webserver e.g. `service apache2 stop && php -S 0.0.0.0:80` or using apache2 (then you have to configure the `sites-available` conf yourself)
-    - You can then access TimeTrack in your browser at `http://localhost`, default login is `admin` with password `admin`. Create yourself a new admin account, login and delete the default account afterwards.
+    - Follow "Use with ..." guides
+    #### Use with apache2.4
+    - Create a new virtual host: `sudo nano /etc/apache2/sites-available/timetrack.conf`
+    - Content:
+    ```conf
+    <VirtualHost *:80>
+        ServerName timetrack.yourdomain.de
+        DocumentRoot /var/www/timetrack
+        <Directory /var/www/timetrack>
+            AllowOverride All
+            Require all granted
+        </Directory>
+        ErrorLog ${APACHE_LOG_DIR}/error.log
+        CustomLog ${APACHE_LOG_DIR}/access.log combined
+    </VirtualHost>
+    ```
+    - Enable site and module: `sudo a2ensite timetrack && a2enmod rewrite`
+    #### Use with PHP development server
+    - Start server: `cd /var/www/timetrack && php -S 0.0.0.0:80`
+    #### Finalize
+    You can now access TimeTrack in your browser at `http://localhost`, default login is `admin` with password `admin`. Create yourself a new admin account, login and delete the default account afterwards.
     To save log files, please create the subfolder `data/logs` and make it writeable to the web server (e.g. `chown www-data:www-data data/logs && chmod 775 data/logs`).
-    Please also make sure that the `/data` directory is writable by the webserver, aswell as the plugins directory (default: `api/v1/class/plugins/plugins`).
+    Please also make sure that the `/data` directory is writable by the webserver, aswell as the plugins directory (default: `api/v1/class/plugins/plugins`). The `/api/v1/toil/permissions.json` also needs to be writeable by the webserver.
+    **You can run the `update.sh` script to update your instance: `sudo sh update.sh`**
     ### Configure app.json
@@ Expand All @@
     - `timezone`: Set the timezone of your application, e.g. `Europe/Berlin` or `America/New_York` (default: `UTC`)
     - `force_theme`: Force a theme for all users, this disables the feature allowing users to set their own theme.
     - `theme_file`: If `force_theme` is true, the specified theme is used (default: `/assets/css/v8.css`)
+    - `demo`: If set to `true`, demo credentials are shown on the login page. Useful for demo installations.
+    - `telemetry`: Enable/disable telemetry (Default: `enabled` - **PLEASE DISABLE IF NEEDED**)
+    - `telemetry_server_url`: Full server url to telemetry upload
+    - `telemetryServer`: Enables/disables the Server Telemetry Statistics page
     #### **SMTP section**
@@ Expand Down Expand Up @@
     All existing export modules can be accessed with the `ExportManager` Plugin.
     You can specify your own CSS file within the `app.json` `exports -> pdf -> css` setting (full path) - the default is `api/v1/class/exports/modules/PDFExportModule/css/index.css`
+    ### Custom contents
+    You can use custom contents within your PDF exports by placing HTML/PHP files into `api/v1/class/exports/modules/PDFExportModule/php/`.
+    Two files can be placed there:
+    - `user_content_ending.php`: This file is included at the end of the PDF export, e.g. for signatures or custom footers
+    - `user_content_starting.php`: This file is included at the beginning of the PDF export, e.g. for custom headers.
+    You can put normal PHP and HTML code into these files.
     ## QR codes
     You can use the plugin `QRClock` to generate QR codes for yourself to either clock in or out. The QR code generated can be saved for later use, e.g. print it out.
@@ Expand Down Expand Up @@
     The theme the user selected is saved as a cookie, meaning it is only selected on the current device. On mobile or on another device, the user has to set the desired theme again.
+    ## Run as Telemetry server
+    Basically, there are only a few steps to do
+. Navigate to the telemetry server directory: `cd api/v1/class/telemetry/server`
+. Start server: `nohup php -S 0.0.0.0:8888 server.php > telemetry.log 2>&1 &`
+. Set `telemetryServer` inside app.json `general` section to `true`.
+. Check received telemetry data on the "Server Telemetry" page.
+    ## Change Telemetry server URL for managed environments
+    If you want  all of your TimeTrack instances to point to your telemetry server instance, you need to change the app.json `general` `telemetry_server_url` attribute to your URL.
+    Also make sure the `telemetry` attribute is set to `"enabled"`.
+    To check if all worked simply visit the Settings page using an admin account. Check the checkbox within the Telemetry section at the bottom of the page and click the Submit button.
+    On your server timetrack instance you need to visit the "Server Telemetry" page to check if you received the new/updated telemetry data.
     ## Updates
     TimeTrack has to be updated in two ways: database and application.
+    A full update on linux based machines can also be performed by executing the `update.sh` file inside the root directory. In any other cases follow the steps below:
+    If you were seeking assistance and were asked to try out the changes in a branch, please execute this command inside the timetrack root directory: `git fetch && git checkout BRANCH` - replace BRANCH with the actual branch name, e.g. TT-24 or develop.
     ### Application
@@ Expand Down @@

VERSION

Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		8.3.1
		8.7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Sync with master branch #141

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!