Deployment guide

Wakapi on a VPS: self-hosted coding-time statistics

Deploy on a VPS Cloud →

Tutorial

Self-hosting

Wakapi on a VPS: self-hosted coding-time statistics

WakaTime plugins measure coding time very well, but they send every open file, project and branch to a third-party service. Wakapi is an open-source server compatible with those same plugins: you change one configuration line and your statistics stay on your VPS. This guide installs it with Docker Compose, closes sign-ups, publishes it over HTTPS behind nginx and connects your editor.

6 min read4 steps
Contents· What Wakapi does1/11
  1. 01What Wakapi does
  2. 02What Wakapi gives you
  3. 03Hosted WakaTime or Wakapi on your VPS
  4. 04Prerequisites
  5. 05Install Wakapi with Docker Compose
  6. 06Do not leave sign-ups open
  7. 07Publish Wakapi over HTTPS with nginx
  8. 08Connect your editor
  9. 09Read your statistics and the API
  10. 10Back up and update
  11. 11Install Wakapi in one click on ServOrbit

What Wakapi does

Wakapi receives the heartbeats that WakaTime plugins send while you code: the file, project, language, editor, machine and branch, roughly every two minutes. It aggregates them into statistics you can browse in a web dashboard and through an API compatible with WakaTime's.

The project is released under the MIT licence. It is a single Go application and stores its data in SQLite by default (MySQL and PostgreSQL are also supported). On a VPS it uses about 100 MB of memory at rest.

What Wakapi gives you

  • Time per project, language, editor, machine and branch — over the day, the week or any period you choose.
  • Your current plugins — VS Code, JetBrains, Vim, Neovim, Sublime Text: only the server address changes.
  • A WakaTime-compatible API — status bars and tools that read the WakaTime API point to your instance.
  • Invite-only accounts — public sign-ups closed, single-use invite links valid for 24 hours.
  • Import of your history — from WakaTime or another Wakapi instance, in the settings.
  • Data that stays with you — nothing leaves the VPS unless you turn on the WakaTime relay.

Hosted WakaTime or Wakapi on your VPS

Scroll the table

WakaTime (hosted service)Wakapi on your VPS
Where heartbeats goWakaTime's serversYour VPS
Editor pluginsWakaTime pluginsThe same plugins
History keptDepends on the planAs long as you keep it
Team accountsWakaTime accountsAccounts on your instance, by invitation
Server licenceProprietary serviceMIT

Prerequisites

An Ubuntu 24.04 VPS with 1 GB of RAM and 1 vCPU is plenty. You need Docker with the Compose plugin, nginx and certbot on the host, and a name (wakapi.example.com in this guide) pointing to the VPS's IP. WakaTime plugins send their data over HTTPS: set up the certificate from the start.

Install Wakapi with Docker Compose

  1. Prepare the folder and the .env file

    WAKAPI_PASSWORD_SALT is the salt added to passwords before hashing: generate it once and never change it, or no account will be able to log in again. Sign-ups stay open just long enough to create your account, then they are closed in step 4.

    mkdir -p /opt/wakapi && cd /opt/wakapi
    cat > .env <<EOF
    DOMAIN=wakapi.example.com
    WAKAPI_PASSWORD_SALT=$(openssl rand -hex 32)
    WAKAPI_ALLOW_SIGNUP=true
    EOF
    chmod 600 .env
  2. Write the docker-compose.yml file

    The official image runs as an unprivileged user and keeps its SQLite database in the wakapi-data volume. The port is published on the loopback interface only: nginx alone faces the Internet. WAKAPI_LEADERBOARD_ENABLED turns off the public leaderboard, and WAKAPI_INSECURE_COOKIES set to false restricts session cookies to HTTPS.

    services:
      wakapi:
        image: ghcr.io/muety/wakapi:2.18.2
        restart: unless-stopped
        environment:
          WAKAPI_PASSWORD_SALT: "${WAKAPI_PASSWORD_SALT}"
          WAKAPI_PUBLIC_URL: "https://${DOMAIN}"
          WAKAPI_ALLOW_SIGNUP: "${WAKAPI_ALLOW_SIGNUP:-false}"
          WAKAPI_INVITE_CODES: "true"
          WAKAPI_LEADERBOARD_ENABLED: "false"
          WAKAPI_INSECURE_COOKIES: "false"
        ports:
          - "127.0.0.1:3000:3000"
        volumes:
          - wakapi-data:/data
    
    volumes:
      wakapi-data: {}
  3. Start and create your account

    Start the stack and check the health endpoint, which should answer app=1 and db=1:

    docker compose up -d
    curl -s http://127.0.0.1:3000/api/health

    Once nginx and the certificate are in place (next section), open https://wakapi.example.com/signup and create your account: the first account created becomes administrator.

  4. Close sign-ups

    As soon as your account exists, close sign-ups and recreate the container:

    sed -i 's/^WAKAPI_ALLOW_SIGNUP=true/WAKAPI_ALLOW_SIGNUP=false/' .env
    docker compose up -d

    The sign-up form now answers "registration is disabled". To add a colleague, generate an invite link from your account settings ("Invite Friends"): it is valid for 24 hours and works only once.

Do not leave sign-ups open

An instance published on a domain with WAKAPI_ALLOW_SIGNUP=true lets anyone open an account and store data on it. Keep false, invite colleagues by link, and leave the port on 127.0.0.1.

Publish Wakapi over HTTPS with nginx

Create /etc/nginx/sites-available/wakapi with this server block, then enable it with a symbolic link in sites-enabled:

server {
    listen 80;
    server_name wakapi.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Check the configuration, reload nginx and request the certificate; certbot adds the HTTPS block and the redirect from HTTP itself.

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d wakapi.example.com

Connect your editor

Install your editor's WakaTime plugin from its usual marketplace. In Wakapi, open the settings and copy your API key, then write the ~/.wakatime.cfg file on your machine:

[settings]
api_url = https://wakapi.example.com/api
api_key = <API_KEY>

The WakaTime client derives the project name from the root folder of the Git repository and the machine name from the host name: your repositories appear as they are in the dashboard, and you tell the laptop from the desktop without effort. A .wakatime-project file at the root of a repository forces another project name, useful when several clones share the same folder name. To leave out a sensitive folder, the exclude key of ~/.wakatime.cfg accepts regular expressions on paths.

Code for a few minutes and reload Wakapi's dashboard: your first figures appear. The same file serves every plugin on the machine. To send your data to both WakaTime and Wakapi, the WakaTime client accepts an [api_urls] section that adds destinations.

Read your statistics and the API

The dashboard shows time per project, language, editor, operating system, machine and branch, over the chosen interval. The same figures are available through the WakaTime-compatible API, with Basic authentication using the base64-encoded API key:

curl -s https://wakapi.example.com/api/compat/wakatime/v1/users/current/statusbar/today \
  -H "Authorization: Basic $(printf %s '<API_KEY>' | base64)"

This is the endpoint read by plugins that show today's time in the status bar. The settings also offer README badges, public sharing of selected statistics (off by default) and the import of your WakaTime history.

Back up and update

All the data lives in the wakapi-data volume. Stop the container while you copy the SQLite database, so that the copy is consistent:

cd /opt/wakapi
docker compose stop wakapi
docker run --rm -v wakapi_wakapi-data:/data -v "$PWD":/backup alpine:3.22 \
  tar czf /backup/wakapi-$(date +%F).tar.gz -C /data .
docker compose start wakapi

To update, first read the release notes on GitHub, back up, then change the image tag:

cd /opt/wakapi
sed -i 's|wakapi:2.18.2|wakapi:<NEW_VERSION>|' docker-compose.yml
docker compose pull && docker compose up -d

Install Wakapi in one click on ServOrbit

On a ServOrbit VPS, Wakapi installs from the Marketplace. The script deploys the official image, generates the administrator password and the hashing salt, creates the admin account, closes public sign-ups and turns off the public leaderboard, then configures the nginx reverse proxy over HTTPS — on a subdomain of one of your domains or on the VPS's free subdomain. You log in with the user admin and the password shown in your client area, then connect your editor as above.

Share this articleservorbit.com/ma-en/blog/self-host-wakapi-vps-coding-stats