Kimai logo Kimai Docs Documentation

Install Kimai on a fresh Ubuntu 20.04 LTS

How to install Kimai on a brand new Ubuntu 20.04 with database, webserver and SSL certificate

Kimai 1.14 2.27.0 (latest version)

This is a collection of snippets to help you with setting up a fresh Ubuntu 18.04 server for using with Kimai. It is neither a full fledged documentation, explaining each step, nor is it a bash tutorial.

Please see it as a personal snippet collection… in which I assume:

  • that you are familiar with the Linux bash and have at least basic knowledge of vim
  • that you use a single domain on this server, change the nginx configuration accordingly if you have multiple VirtualHosts
  • that you know how to protect your server (UFW, Fail2Ban …) and can securely run it in the “wild”

You must additionally:

  • replace IP-of-myserver with the server IP
  • replace the username kevin with your own
  • replace the domain www.kimai.local with your own

Accounts and SSH connection

We start on our local machine, connect to the server and create our real user account:

ssh root@IP-of-myserver

useradd -m -s /bin/bash kevin
passwd kevin

Enable sudo access for this new user:

visudo /etc/sudoers.d/kevin

And paste this one line:

kevin   ALL=(ALL:ALL) ALL

Back to our local machine:

exit

Generate your SSH key and sent it to your server:

ssh-keygen -f ~/.ssh/kevin_myserver_rsa
ssh-copy-id -i /Users/kevin/.ssh/kevin_myserver_rsa.pub kevin@IP-of-myserver

Then edit your local SSH config:

vim ~/.ssh/config

And paste this:

Host myserver
    HostName IP-of-myserver
    IdentityFile ~/.ssh/kevin_myserver_rsa
    User kevin

And finally on to the server to start the software installation:

ssh myserver

Secure your SSHD configuration

Make sure your SSH server has at least some basic security settings in place:

sudo su
vim /etc/ssh/sshd_config

Change those:

PermitRootLogin no
PasswordAuthentication no

And restart the SSH Daemon:

/etc/init.d/ssh restart

Install PHP, webserver and database

Lets start with all required software:

apt-get update
apt-get upgrade
apt-get install git unzip curl vim
apt-get install php-fpm php-cli php-common php-json php-opcache php-readline php-xml php-zip php-intl php-gd php-mbstring php-mysql php-curl
apt-get install mariadb-server mariadb-client
apt-get install nginx

Install composer

Grab the latest hash from the composer download page and then execute:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '48e3236262b34d30969dca3c37281b3b4bbe3221bda826ac6a9a62d6444cdb0dcd0615698a5cbe587c3f0fe57a54d8f5') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

Only proceed if you see: Installer verified!

php composer-setup.php
php -r "unlink('composer-setup.php');"
chmod +x composer.phar
mv composer.phar /usr/bin/composer

Create database

Connect to your database as root user:

sudo su
mysql -u root

And execute the following statements:

CREATE DATABASE IF NOT EXISTS `kimai2`;
CREATE USER IF NOT EXISTS `kimai2`@127.0.0.1 IDENTIFIED BY "my-super-secret-password";
GRANT select,insert,update,delete,create,alter,drop,index,references ON `kimai2`.* TO kimai2@127.0.0.1;
exit;

Replace “my-super-secret-password” with a strong password and probably change the username as well.

Install Kimai

Clone Kimai and set proper file permissions:

Please compare with the latest version infos at: </documentation/installation.html>

cd /var/www/
git clone -b 2.27.0 --depth 1 https://github.com/kimai/kimai.git
cd kimai/
composer install --no-dev --optimize-autoloader -n
vim .env

Configure the above created database credentials:

DATABASE_URL=mysql://kimai2:my-super-secret-password@127.0.0.1:3306/kimai2

And execute the Kimai installation:

bin/console kimai:install -n
bin/console kimai:create-user admin admin@example.com ROLE_SUPER_ADMIN

Adjust file permission

You have to allow PHP (your webserver process) to write to var/ and it subdirectories.

Here is an example for Debian/Ubuntu, to be executed inside the Kimai directory:

chown -R :www-data .
chmod -R g+r .
chmod -R g+rw var/

You might not need these commands in a shared-hosting environment. And you probably need to prefix them with sudo and/or the group might be called different from www-data.

Use sudo to run the commands to change file permissions.

Configure webserver

Good, now that we have done all these steps we only need the webserver and VirtualHost configuration:

Check your PHP-FPM config for the fastcgi_pass (eg. version and socket)

This can be done with:

vim /etc/php/7.4/fpm/pool.d/www.conf
listen = /run/php/php7.4-fpm.sock

Edit/create the virtual host file:

vim /etc/nginx/sites-available/kimai2

And paste the following configuration:

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name www.kimai.local;
    root /var/www/kimai/public;
    index index.php;

    access_log off;
    log_not_found off;

    location ~ /\.ht {
        deny all;
    }

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi.conf;
        fastcgi_param PHP_ADMIN_VALUE "open_basedir=$document_root/..:/tmp/";
        internal;
    }

    location ~ \.php$ {
        return 404;
    }
}

Remove the Ubuntu default host and activate the site:

unlink /etc/nginx/sites-enabled/default
ln -s /etc/nginx/sites-available/kimai2 /etc/nginx/sites-enabled/kimai2
nginx -t && service nginx reload

Install Certbot for SSL

Almost there, only the free Lets Encrypt SSL certificate is missing:

apt-get install certbot python3-certbot-nginx
certbot --nginx

Follow the interactive dialogs and choose “2: Redirect - Make all requests redirect to secure HTTPS access.”. This will rewrite your nginx site configuration and should work out-of-the-box.

Kimai is now up and running at www.kimai.local - enjoy!

Top