Installation

Timecrack is a self-hosted, open source time tracking application built with Laravel. Install it on your own server so your team can track time through any modern web browser.

Server Requirements

  • PHP >= 8.2
  • Composer
  • MySQL 8.0+
  • Node.js (for compiling front-end assets)
  • Apache or Nginx web server
  • BCMath PHP Extension
  • Ctype PHP Extension
  • Fileinfo PHP Extension
  • JSON PHP Extension
  • Mbstring PHP Extension
  • OpenSSL PHP Extension
  • PDO PHP Extension
  • Tokenizer PHP Extension
  • XML PHP Extension

Tip: You can verify your PHP version and installed extensions by running php -v and php -m from the command line.

Installation Steps

Follow these steps to install Timecrack on your server:

  1. Clone the repository from GitHub: 
    git clone https://github.com/alextselegidis/timecrack.git
cd timecrack
  2. Install PHP dependencies: 
    composer install
  3. Copy the environment configuration file: 
    cp .env.example .env
  4. Configure your database connection in .env: 
    DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=timecrack
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password
  5. Generate the application key: 
    php artisan key:generate
  6. Run database migrations and seed the initial data: 
    php artisan migrate:fresh --seed
  7. Configure your web server to point the document root at the public directory (see below).
  8. Open your browser and navigate to your configured domain. Log in with the default credentials (admin@example.org / 12345678) and change the password immediately.

Web Server Configuration

Apache

Ensure mod_rewrite is enabled and AllowOverride All is set for the application directory. A sample virtual host configuration:

<VirtualHost *:80>
    ServerName time.example.com
    DocumentRoot /var/www/timecrack/public

    <Directory /var/www/timecrack/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx

Configure the root to point at the public directory and add a try_files directive:

server {
    listen 80;
    server_name time.example.com;
    root /var/www/timecrack/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Setting File Permissions

After cloning the files, set the correct permissions so the web server can read and write as needed:

# Set ownership to the web server user (e.g. www-data)
sudo chown -R www-data:www-data /var/www/timecrack

# Set directory permissions
sudo find /var/www/timecrack -type d -exec chmod 755 {} \;

# Set file permissions
sudo find /var/www/timecrack -type f -exec chmod 644 {} \;

# Ensure storage and cache are writable
sudo chmod -R 775 /var/www/timecrack/storage
sudo chmod -R 775 /var/www/timecrack/bootstrap/cache

HTTPS / SSL Configuration

It is strongly recommended to serve Timecrack over HTTPS. You can use Let's Encrypt for free SSL certificates:

# Install Certbot (Ubuntu/Debian)
sudo apt install certbot python3-certbot-apache   # for Apache
sudo apt install certbot python3-certbot-nginx     # for Nginx

# Obtain and install certificate
sudo certbot --apache -d time.example.com         # for Apache
sudo certbot --nginx -d time.example.com          # for Nginx

Important: Always use HTTPS in production to protect user credentials and time tracking data in transit.

Useful Links