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 go | WakaTime's servers | Your VPS |
| Editor plugins | WakaTime plugins | The same plugins |
| History kept | Depends on the plan | As long as you keep it |
| Team accounts | WakaTime accounts | Accounts on your instance, by invitation |
| Server licence | Proprietary service | MIT |
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
Prepare the folder and the .env file
WAKAPI_PASSWORD_SALTis 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 .envWrite the docker-compose.yml file
The official image runs as an unprivileged user and keeps its SQLite database in the
wakapi-datavolume. The port is published on the loopback interface only: nginx alone faces the Internet.WAKAPI_LEADERBOARD_ENABLEDturns off the public leaderboard, andWAKAPI_INSECURE_COOKIESset tofalserestricts 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: {}Start and create your account
Start the stack and check the health endpoint, which should answer
app=1anddb=1:docker compose up -d curl -s http://127.0.0.1:3000/api/healthOnce nginx and the certificate are in place (next section), open
https://wakapi.example.com/signupand create your account: the first account created becomes administrator.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 -dThe 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.comConnect 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 wakapiTo 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 -dInstall 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.
servorbit.com/ma-en/blog/self-host-wakapi-vps-coding-stats