WorkingTime

WorkingTime is a server-rendered timekeeping application written in Go. It records clock-in/-out events, derives work and break intervals, and provides departmental management, calendars, reporting, barcode workflows, and administrative exports.

The application targets Go 1.27 and supports SQLite by default, tinySQL, and Microsoft SQL Server. SQLite and tinySQL suit compact deployments; use a managed database, backups, and an operational review for multi-instance or business-critical operation.

Getting Started

To run the project, follow these steps:

• Install Go 1.27 or newer.

• Clone the repository.

• Change to the project directory.

• Create a local administrator and start the application:

  export BOOTSTRAP_ADMIN_EMAIL=admin@example.test
  export BOOTSTRAP_ADMIN_PASSWORD='use-a-unique-password-of-at-least-12-characters'
  go run .

• Open http://127.0.0.1:8083 and sign in with that account. The initial administrator is created once in the active tenant database.

• Alternatively, ./test.sh starts a local SQLite instance (time_tracking.test.db).

• When requests use a hostname, SQLite data is isolated in tenant/<host>/time_tracking.db. Restrict supported hosts with ALLOWED_HOSTS in production.

Database backends

SQLite is the default and creates one database file per HTTP host. It is the simplest option for a small, single-service deployment.

tinySQL is an embedded, tenant-aware option. Set DB_BACKEND=tinysql and choose a writable TINYSQL_PATH; requests for different accepted hosts are stored as logical tenants in the same tinySQL data file. WorkingTime uses tinySQL's database/sql driver, reader/writer pools, a five-second busy timeout, and explicit random integer IDs because tinySQL intentionally has no AUTOINCREMENT feature.

export DB_BACKEND=tinysql
export TINYSQL_PATH=/var/lib/workingtime/time_tracking.tinysql
go run .

The tinySQL schema is purpose-built and initialized automatically for a fresh data file. It is not an automatic migration format for an existing SQLite or MSSQL installation; export and validate data before planning such a migration. Back up the tinySQL data file while the application is stopped or through tinySQL's supported backup procedure.

Microsoft SQL Server is selected with DB_BACKEND=mssql and its MSSQL_* variables. It is the only networked backend currently included.

Usage

Before clocking in and out, you need to create a department, then a user and an activity. Follow these steps to start using the timekeeping system:

• Access the web interface at http://127.0.0.1:8083.
• Navigate to the /addDepartment page to create a new department.
• Navigate to the /addUser page to create a new user and associate them with a department.
• Navigate to the /addActivity page to create a new activity.
• Use the form on the index page to clock in and out by selecting a user and an activity from the dropdown menus.
• Users can view their own history at /myHistory after signing in.
• Admins can export CSVs from the Admin menu (Entries, Work Hours).
• Tenant overrides: place templates/*.html or static/* under tenant/<host>/ to override defaults.

Features

The timekeeping system includes the following features:

• Create and manage departments, users, and activities.
• Clock in and out with a user and an activity.
• View work hours per user per day.
• View the current status of all employees.
• Admin downloads: export Entries and Work Hours as CSV (/admin/download/...).
• User self‑service: personal history at /myHistory after login.
• Optional per‑user auto checkout at 23:59:59 (toggle in Edit User).

Security and operations

The default configuration is deliberately closed: all time-entry flows require a session and the barcode kiosk must be explicitly enabled with PUBLIC_KIOSK_ENABLED=true. Administrative management, organisation-wide data, and exports require an admin role. Regular DB users can only manually record their own entries.

Production deployments must set all of the following:

• APP_ENV=production
• SESSION_SECRET — at least 32 random bytes; for example openssl rand -base64 48
• ALLOWED_HOSTS — comma-separated public hostnames
• BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD only for the first startup, then remove the password from the environment file

Cookies are HttpOnly and SameSite=Lax; set COOKIE_SECURE=true behind HTTPS (enabled automatically in production). Mutating requests require a session-bound CSRF token, HTTP request bodies are capped at 1 MiB by default, and the server uses explicit read/write/idle timeouts and graceful shutdown.

credentials.csv is no longer distributed or read by default. If legacy CSV authentication is necessary, point CREDENTIALS_FILE at a protected file containing bcrypt password hashes; plain-text CSV passwords are rejected in production. See credentials.example.csv.

The supplied systemd environment example contains the required variables. The Dockerfile runs as a non-root user; mount a writable volume at /app/tenant (or set TENANT_DIR) and provide the production environment variables. For tinySQL in the container, set TINYSQL_PATH=/app/tenant/time_tracking.tinysql so the data file is on that writable volume.

Run the same checks as CI locally:

go mod verify
go vet ./...
go test ./...

Future Features

• check-in and -out with RFID tags (like in this example/or here)
• Automatic generation of reports and analyses on work hours, productivity, and attendance
• Real-time notifications to managers when an employee works longer than planned
• automatically tracking and managing overtime, with options for compensatory days off or additional pay
• allow project-based time tracking, enabling employees to log hours to specific projects and tasks
• gamification elements to increase employee engagement, such as rewards for punctual clock-ins
• self-service portal where employees can manage their work hours, leave requests, and overtime applications themselves
• monitor compliance with labor laws and internal company policies
• verifies that all employees who were in the building during an emergency evacuation have reached the designated assembly point

Notes and remaining scope

The system implements basic role-based access control, but it is not a replacement for an enterprise identity provider, audit log, data-retention policy, backup strategy, or legal assessment of working-time regulations. The MSSQL auto-checkout policy is intentionally disabled pending a dialect-specific implementation; configure that policy through a reviewed scheduled job if MSSQL is used.

License

This project is provided under the MIT License.