Install Kimai on Ubuntu 18.04
How to install Kimai on a brand new Ubuntu 18.04 with database, webserver and SSL certificate
This documentation is outdated and does not work with the latest Kimai version. Please upgrade and use Ubuntu 20.04 LTS instead.
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 fully fledged documentation, explaining each step, nor is it a bash tutorial.
Self-hosting knowledge prerequisites
Self-hosting Kimai requires technical knowledge, including:
- Setting up and configuring servers and containers
- Managing application resources and scaling
- Securing servers and applications
- Configuring Kimai
Kimai recommends self-hosting for expert users. Mistakes can lead to data loss, security issues, and downtime. If you aren’t experienced at managing servers, Kimai recommends the hosted cloud.
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/myserver_rsa
ssh-copy-id -i ~/.ssh/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/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 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 mysql-server mysql-client
apt-get install nginx
apt-get install git unzip curl
BTW: I’d use MariaDB, but Ubuntu 18.04 ships an outdated MariaDB which does not support JSON columns, thus not compatible with Kimai.
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.25.0 --depth 1 https://github.com/kimai/kimai.git
cd kimai/
chown -R :www-data .
chmod -R g+r .
chmod -R g+rw var/
composer install --no-dev --optimize-autoloader
vim .env
Configure the database connection and adjust the settings to your needs (compare with the original .env file):
DATABASE_URL=mysql://kimai2:my-super-secret-password@127.0.0.1:3306/kimai2?charset=utf8mb4&serverVersion=5.7.40
And execute the Kimai installation:
bin/console kimai:install -n
bin/console kimai:user:create 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.2/fpm/pool.d/www.conf
listen = /run/php/php7.2-fpm.sock <= search for this "listen" entry
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.2-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;
}
}
Lets activate the site and remove the Ubuntu default host:
ln -s /etc/nginx/sites-available/kimai2 /etc/nginx/sites-enabled/kimai2
unlink /etc/nginx/sites-enabled/default
nginx -t && service nginx reload
Install Certbot for SSL
Almost there, only the free Lets Encrypt SSL certificate is missing:
apt-get install software-properties-common
add-apt-repository universe
add-apt-repository ppa:certbot/certbot
apt-get update
apt-get install certbot python-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!