Knowledgebase

Introduction

This tutorial explains how to install and configure Wakapi on Ubuntu 20.04. It also describes how to secure your Wakapi installation with an Nginx reverse proxy, a Let's Encrypt SSL certificate using Certbot, and how to daemonize it using PM2. This secures your server and allows it to run in the background.

Wakapi is a free and open-source alternative to WakaTime that can be self-hosted on any server. WakaTime is a time tracking tool for developers that automatically tracks your time when you start coding. WakaTime's plugins for each code editor are open source, but the dashboard is not. This is where Wakapi comes in. It allows you to control your data and display it from your server. Wakapi uses WakaTime's IDE plugins to send data to your Wakapi server.

Prerequisites

Before you begin, you should:

• Deploy an Ubuntu 20.04 server.
• Update the server.
• Create a non-root user with sudo privileges.
• Log in to your server as a non-root user.
• Install NVM and Node.js.
• Configure a Rcs firewall or ufw, and open port 433 to either your IP or all IPs.

You will also need a domain name that points to your server. If you do not have a domain or do not wish to register one, you cannot use Certbot to create an SSL certificate, as Let's Encrypt does not support IP addresses. It is unsafe and not recommended to create and self-sign your SSL certificate. So, you may need to use an alternative service that supports signing certificates for IP addresses such as ZeroSSL.

Installation

1. Install unzip and nginx using apt. The install script requires this to unzip the necessary files, while nginx will set up a reverse proxy.

    $ sudo apt install unzip nginx

2. Install pm2 using npm. This will use this to daemonize Wakapi.

    $ npm install -g pm2

3. Create a new folder and enter it.

    $ mkdir wakapi
    $ cd wakapi

4. Install Wakapi using the install script.

    $ curl -L https://wakapi.dev/get | bash

5. Ensure that your version of snapd is up to date.

    $ sudo snap install core; sudo snap refresh core

6. Ensure that any apt versions of Certbot are uninstalled.

    $ sudo apt remove certbot

7. Install Certbot using snap.

    $ sudo snap install --classic certbot

8. Run Certbot. Certbot will prompt you for things like your domain name, email address, agreement to the ToS, and if you want to redirect HTTP to HTTPS (recommended). Enter those values when prompted.

    $ sudo certbot certonly --standalone

9. Note down the path of your certificate and private key when provided. It will be different, depending on the domain name used.

    Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
    Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem

If you use a different SSL provider, ensure the certificate and private key files are stored somewhere on your system. Note down the paths to them instead.

You have now successfully installed Wakapi and have obtained a signed SSL certificate.

Server Configuration

Wakapi Configuration File

Before starting Wakapi, a few options in the configuration file need to be changed.

Open the config.yml file in your text editor.

$ nano config.yml

You should now see the Wakapi configuration file. Edit the following values, and leave everything else as the default.

server:
  public_url: https://example.com # Replace with your domain name/IP address and port you use to access Wakapi

...

security:
  insecure_cookies: false # Disable insecure (HTTP) cookies

Close and save the file by pressing Control + X, then Y, followed by Enter.

Testing Your Configuration

You can now start Wakapi to test it before adding it as a daemon.

$ ./wakapi

You should see something similar to the text below, which indicates that Wakapi is ready to use.

--> Listening for HTTP on 127.0.0.1:3000... ✅

You won't be able to connect to your Wakapi server from the internet yet, as you need to configure the reverse proxy. This will be configured later.

Daemonize Wakapi

Daemonizing Wakapi allows it to run in the background, automatically restart, and automatically start when your server reboots.

1. Hit Control + C to stop Wakapi.

2. Start Wakapi under PM2.

    $ pm2 start ./wakapi

3. View the logs to ensure it has started correctly and is running.

    $ pm2 logs
    --> Listening for HTTP on 127.0.0.1:3000... ✅

4. Hit Control + C again to exit PM2 logs.

5. Save the current list of processes.

    $ pm2 save

6. Get the startup script for PM2.

    $ pm2 startup

7. Copy and paste the command PM2 outputs back into the terminal and press Enter to successfully configure the startup script.

Securing Wakapi with an Nginx Reverse Proxy

You can now use your SSL certificate and Nginx to secure Wakapi. Be sure to replace example.com with your domain name or IP address.

1. Create a new configuration file in Nginx's sites-available directory.

    $ sudo touch /etc/nginx/sites-available/example.com

2. Open the file in your text editor.

    $ sudo nano /etc/nginx/sites-available/example.com

3. Paste the following into the file, and replace example.com with your domain name or IP address.

    upstream wakapi {
      server localhost:3000;
    }
   
    server {
      listen 443 ssl http2;
      server_name example.com;
   
      gzip on;
   
      ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
      ssl_session_cache builtin:1000 shared:SSL:10m; 
      ssl_session_cache shared:MySSL:10m;
      ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
      ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
      ssl_prefer_server_ciphers on;
   
      location / {
        proxy_pass         http://wakapi;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
      }
    }

4. Exit your text editor and save changes by pressing Control + X, then Y, followed by Enter.

5. Create a link to the new configuration file in Nginx's sites-enabled directory.

    $ sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com.conf

6. Test the configuration file. If the test is successful, you will see the syntax is ok, and the test is successful messages.

    $ sudo nginx -t
    nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
    nginx: configuration file /etc/nginx/nginx.conf test is successful

7. Restart Nginx to apply the changes.

    $ sudo systemctl restart nginx

8. Open your server's IP or domain name in a browser with HTTPS and no specified port.

    https://example.com

You should now see the Wakapi homepage with a lock in the URL bar, representing an HTTPS connection.

Client Configuration

To send data to the Wakapi server, you need to create an account, then configure one or more of the many WakaTime IDE plugins to send data to Wakapi.

Account Creation

1. Navigate to your Wakapi homepage.
2. Click Sign In at the top right of the page.
3. Click the gray Sign up button next to the green Log in button.
4. Enter your preferred username, email address, and password.

You should now see a welcome screen with details on how to set up your WakaTime plugin.

WakaTime IDE Plugins

Installation

Visit the WakaTime plugins page and pick your desired IDE or text editor.

Ensure to follow the instructions to install the plugin. When prompted for your API key, copy the API key from the Wakapi dashboard and enter it. If it does not prompt you to enter an API key, or you are required to edit the ~/.wakatime.cfg file regardless, proceed to the next section.

Configuration

There should be a new ~/.wakatime.cfg file in your home directory. Open this file in your text editor.

$ nano ~/.wakatime.cfg

Add the api_url value to the file under [settings]. If not already added, provide your API key by adding the api_key to [settings].

[settings]
api_url = https://example.com/api
api_key = your-wakapi-api-key

Save and close the file by using Control + X, then Y, followed by Enter.

Close and reopen your text editor or IDE to ensure the configuration is applied. Now start coding or editing a file, and refresh your Wakapi dashboard. You should now see some statistics on your dashboard.

Congratulations, you have now successfully installed and configured Wakapi and your WakaTime plugin.

Additional Information

Updating Wakapi

Updating to a newer version of Wakapi is as simple as re-running the install script in the /wakapi folder. Note that it will overwrite your existing configuration file. Rename the configuration file or temporarily move it to a different location to avoid this.

$ curl -L https://wakapi.dev/get | bash

You can find the Wakapi version number at the bottom of any Wakapi page. You can find the latest release here.

Preventing Additional Sign Ups

Once you have created your account, you can safely disable additional people from signing up by editing your config.yml.

$ nano config.yml

Under security, change the value of allow_signup to false.

security:
  allow_signup: false

Exit and save your changes by using Control + X, then Y, followed by Enter.

Restart the Wakapi server to apply your changes.

$ pm2 restart wakapi

Documentation

• Wakapi Documentation and Repository
• Wakapi Website
• PM2 Documentation
• Nginx Documentation
• WakaTime Website