How to Self-Host Wakapi Dev Tracker 2026

TL;DR

Wakapi (MIT, ~2K GitHub stars, Go) is a self-hosted WakaTime-compatible coding statistics server. Install the WakaTime plugin in your editor → point it at your Wakapi instance → get detailed breakdowns of time spent per project, language, editor, and OS. WakaTime charges $9/month for the full dashboard. Self-hosted Wakapi is free, stores your data locally, and provides the same statistics without sending your coding habits to a third-party.

Key Takeaways

• Wakapi: MIT, ~2K stars, Go — WakaTime-compatible server, self-hosted
• WakaTime plugin compatible: Use the existing WakaTime IDE plugins, just point them at your server
• Language stats: See exactly how much time you spend in Python vs TypeScript vs Go
• Project stats: Time per project, per day/week/month
• Editor stats: VS Code vs Vim vs JetBrains
• Leaderboards: Compare coding time with teammates on your Wakapi instance

Wakapi vs WakaTime

Feature	Wakapi (self-hosted)	WakaTime Free	WakaTime Pro
Cost	Free (hosting)	Free (2-week history)	$9/month
History retention	Unlimited	2 weeks	Unlimited
Project stats	Yes	Yes	Yes
Language breakdown	Yes	Yes	Yes
Team/leaderboards	Yes	No	Yes
Goals	No	No	Yes
API	Yes	Limited	Yes
Data ownership	Full	WakaTime	WakaTime
GitHub Stars	~2K	—	—

Part 1: Docker Setup

# docker-compose.yml
services:
  wakapi:
    image: ghcr.io/muety/wakapi:latest
    container_name: wakapi
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - wakapi_data:/data
      - ./wakapi.yml:/etc/wakapi/config.yml:ro
    environment:
      WAKAPI_DB_TYPE: sqlite3
      WAKAPI_DB_NAME: /data/wakapi.db
      WAKAPI_ALLOW_SIGNUP: "true"    # Disable after setup
      WAKAPI_PUBLIC_URL: "https://code.yourdomain.com"

volumes:
  wakapi_data:

Or use PostgreSQL for production:

environment:
  WAKAPI_DB_TYPE: postgres
  WAKAPI_DB_HOST: db
  WAKAPI_DB_PORT: "5432"
  WAKAPI_DB_NAME: wakapi
  WAKAPI_DB_USER: wakapi
  WAKAPI_DB_PASSWORD: "${POSTGRES_PASSWORD}"

Part 2: Configuration

# wakapi.yml
server:
  port: 3000
  public_url: "https://code.yourdomain.com"
  time_zone: "America/Los_Angeles"

db:
  type: sqlite3
  name: /data/wakapi.db

security:
  password_salt: "your-random-salt"    # openssl rand -hex 16

app:
  leaderboard_enabled: true
  leaderboard_scope: "7d"    # 7-day leaderboard
  aggregate_by_project: true
  max_inactive_months: 12    # Remove inactive users after 12 months
  
  # Custom language colors:
  # languages:
  #   TypeScript: "#3178c6"

docker compose up -d

Part 3: HTTPS with Caddy

code.yourdomain.com {
    reverse_proxy localhost:3000
}

Visit https://code.yourdomain.com → register your account.

Part 4: Connect Your IDE

Wakapi is WakaTime-compatible — use the existing WakaTime plugin in any editor.

VS Code

1. Install WakaTime extension
2. Open Command Palette (Cmd/Ctrl + Shift + P) → WakaTime: Settings
3. Update ~/.wakatime.cfg:

[settings]
api_url = https://code.yourdomain.com/api
api_key = YOUR_WAKAPI_API_KEY

Get your API key from: Wakapi → Settings → API Key

JetBrains (IntelliJ / PyCharm / WebStorm / GoLand)

1. Settings → Plugins → Search "WakaTime" → Install
2. WakaTime Settings → API Key: your Wakapi key
3. API URL: https://code.yourdomain.com/api

Vim/Neovim

" .vimrc
Plugin 'wakatime/vim-wakatime'

In ~/.wakatime.cfg:

[settings]
api_url = https://code.yourdomain.com/api
api_key = YOUR_API_KEY

Emacs

;; .emacs or init.el
(use-package wakatime-mode
  :config
  (setq wakatime-api-url "https://code.yourdomain.com/api")
  (global-wakatime-mode))

Part 5: Dashboard Overview

After a day of coding, the Wakapi dashboard shows:

Today: 6h 23m

Projects:
  my-startup-app      3h 45m  ██████████████████
  personal-scripts    1h 12m  █████
  dotfiles             46m    ██

Languages:
  TypeScript          2h 30m  ████████████
  Python              1h 45m  ████████
  Go                  1h 15m  ██████
  Markdown             53m    ████

Editors:
  VS Code             4h 20m  ████████████████████
  Neovim              2h  3m  ██████████

Systems:
  macOS               6h 23m  ████████████████████████████

Part 6: API

# Get summary for today:
curl "https://code.yourdomain.com/api/summary?from=today&to=today" \
  -H "Authorization: Basic $(echo -n 'username:YOUR_API_KEY' | base64)"

# Get all-time stats:
curl "https://code.yourdomain.com/api/users/current/stats/all_time" \
  -H "Authorization: Basic $(echo -n 'username:YOUR_API_KEY' | base64)"

# Heartbeats (raw data):
curl "https://code.yourdomain.com/api/v1/users/current/heartbeats" \
  -H "Authorization: Basic $(echo -n 'username:YOUR_API_KEY' | base64)"

Part 7: Leaderboards

Compare coding time with friends or teammates:

1. All users on your Wakapi instance appear in the leaderboard
2. View → Leaderboard → see who coded most this week
3. Shows total time, top language, top project

Part 8: Badges (GitHub README)

Add your coding stats badge to GitHub:

![Wakapi Badge](https://code.yourdomain.com/api/badge/YOUR_USERNAME/interval:any/project:any)

Formats:
/badge/{username}/interval:today
/badge/{username}/interval:week  
/badge/{username}/interval:month
/badge/{username}/interval:year
/badge/{username}/interval:any      # All-time
/badge/{username}/project:my-app    # Specific project
/badge/{username}/language:Python   # Specific language

Maintenance

# Update Wakapi:
docker compose pull
docker compose up -d

# Backup:
tar -czf wakapi-backup-$(date +%Y%m%d).tar.gz \
  $(docker volume inspect wakapi_wakapi_data --format '{{.Mountpoint}}')

# Export your data:
# Settings → Export → Download JSON

# Logs:
docker compose logs -f wakapi

Why Self-Host Wakapi

The financial case is simple. WakaTime Pro costs $9/month — $108/year per developer. For a four-person engineering team, that's $432/year just to see coding statistics with more than two weeks of history. Wakapi self-hosted runs on a $4-6/month VPS and costs essentially nothing at that scale.

But the real case for Wakapi goes beyond money. Your coding statistics are surprisingly revealing data. Your activity patterns show when you work, which projects consume your time, how your productivity changes across days and seasons, and which languages you're actively learning versus maintaining. WakaTime's servers have years of that data for millions of developers. Self-hosting means that data stays on infrastructure you control, backed up how you choose, deleted on your timeline.

The WakaTime plugin compatibility is the key technical advantage. You don't need to install anything new or learn a new system — every existing WakaTime plugin works with Wakapi by changing a single config line (api_url). VS Code, JetBrains, Vim, Neovim, Emacs, Sublime Text — all work immediately. The transition from WakaTime to Wakapi takes about five minutes per developer machine.

Wakapi's leaderboard feature deserves mention for teams. Creating a shared Wakapi instance where your whole engineering team tracks stats builds an interesting form of visibility — not surveillance, but the kind of friendly competition that emerges from seeing who's been heads-down on a project all week. It's a lightweight way to understand where the team's effort actually goes, beyond what story points and stand-ups reveal.

When NOT to self-host Wakapi: If you want WakaTime's Goals feature (track whether you hit your daily coding targets), Wakapi doesn't have that yet. Also, if you code primarily on machines you don't control (corporate laptops with locked configs), you may not be able to modify ~/.wakatime.cfg to point at your server.

Prerequisites

Wakapi is one of the lightest self-hosted tools in the developer ecosystem. The Go binary is efficient, and even the Docker image is small.

Server specs: 256MB RAM and 1 vCPU is genuinely sufficient for a single developer instance. For a team of 10 developers all sending heartbeats, 1 vCPU and 512MB RAM handles the load comfortably. SQLite works fine for small teams; switch to PostgreSQL if you have more than 5-10 active users. A basic $4-6/month VPS is completely adequate. Check our VPS comparison for self-hosters for current pricing — this is one case where the cheapest tier is genuinely sufficient.

Operating system: Ubuntu 22.04 LTS. Docker runs cleanly, and the lightweight nature of Wakapi means you could share this VPS with other small self-hosted tools.

Domain and SSL: Wakapi needs HTTPS for the WakaTime plugins to connect without configuration changes. The plugins default to HTTPS connections. A domain with a Let's Encrypt certificate (managed by Caddy as shown in Part 3) is required. A self-signed certificate won't work without extra plugin configuration on every developer machine.

Signup management: After creating your initial accounts, set WAKAPI_ALLOW_SIGNUP: "false" to prevent unauthorized registration. Wakapi doesn't have a robust user management UI, so controlling access at the signup level is the easiest approach.

Skill level: Beginner-friendly. This is a single Docker container with a simple configuration file. If you're comfortable editing YAML and running Docker Compose, you can be up in 15 minutes.

Production Security Hardening

Wakapi stores your coding activity data — which files you edit, which projects you work on, your active hours. While this may seem low-risk, it's worth protecting properly. Follow the self-hosting security checklist and apply these measures:

Firewall (UFW): Only expose HTTPS through your reverse proxy. Never expose port 3000 directly.

sudo ufw default deny incoming
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Disable signup after setup: Once all team members have accounts, disable new registrations by setting WAKAPI_ALLOW_SIGNUP: "false" and restarting the container.

Secrets management: The password_salt in your Wakapi config is important — it's used for password hashing and should be generated with openssl rand -hex 16. Store it in your config file, which should never be committed to version control:

# .env (never commit this)
POSTGRES_PASSWORD=your-db-password
WAKAPI_PASSWORD_SALT=your-random-salt

echo ".env" >> .gitignore

API key rotation: If an API key is compromised (someone finds your ~/.wakatime.cfg), rotate it in Wakapi → Settings → API Key. The old key stops working immediately.

Disable SSH password authentication: Edit /etc/ssh/sshd_config: set PasswordAuthentication no and PermitRootLogin no. Use SSH keys only. Restart: sudo systemctl restart ssh.

Automatic security updates:

sudo apt install unattended-upgrades
sudo dpkg-reconfigure --priority=low unattended-upgrades

Regular backups: The SQLite database contains all your coding history — potentially years of data. Losing it means losing your history permanently. Set up automated backups of the wakapi_data volume. See automated server backups with restic for a set-and-forget solution that handles Docker volumes and uploads to object storage.

Getting the Most from Your Coding Data

Wakapi's raw statistics become genuinely useful when you develop a habit of reviewing them and letting the data inform how you work.

The weekly review is the most valuable practice. Every Monday morning, check last week's breakdown: how much time did you actually spend on which projects, and how does that match your intentions? Most developers discover significant gaps. You may think you spent most of the week on a critical feature, but the data shows you actually spent 40% of coding time in dotfiles and configuration. That's not necessarily bad, but it's useful to know. The discrepancy between perceived effort and actual effort is often eye-opening.

Language statistics reveal your actual tech stack evolution. If you set up Wakapi when you were primarily a Python developer and revisit six months later, you may find TypeScript has become your dominant language. This kind of data is genuinely useful for updating your resume, negotiating roles, or identifying when a technology has become a core competency versus something you just dabble in.

Editor statistics are interesting for multi-editor users. Many developers use VS Code for everyday work but occasionally drop into Neovim or a JetBrains IDE for specific tasks. Wakapi shows you the actual distribution. If Neovim is consistently showing 20% of your coding time, that's a signal you might want to invest more in Neovim configuration and plugins.

The GitHub badge (Part 8) is a subtle but effective portfolio signal. Adding your Wakapi badge to your GitHub profile README shows active coding in a verifiable way — it's not a number you can inflate since it comes from your actual editor activity. This is more honest signaling than GitHub contribution graphs, which can be gamed with commits.

For teams, the leaderboard creates a lightweight accountability mechanism. This works best when the culture treats it as data rather than competition — "I noticed I had a low coding week, want to check if there are blockers?" rather than ranking people. The aggregated team data can also surface whether workload is distributed reasonably or whether one developer is carrying the rest.

Troubleshooting Common Issues

WakaTime plugin shows "invalid API key" or stops sending heartbeats

First verify your ~/.wakatime.cfg points to the correct api_url and api_key. The API key in Wakapi is found at Settings → API Key — it's different from your login password. A common mistake is using the WakaTime.com API key on a Wakapi instance. Also verify SSL is working: curl https://code.yourdomain.com/api/health should return a 200 response.

No data appearing in dashboard after IDE setup

WakaTime plugins send heartbeats every 2 minutes while you're actively editing. Open a file in VS Code and edit it for a few minutes, then check the Wakapi dashboard. Also check the plugin's status — in VS Code, the WakaTime extension shows a status bar item at the bottom. If it shows an error or a question mark, check the extension's logs (Command Palette → WakaTime: Open Logs).

Old heartbeat data from WakaTime missing after migration

Wakapi only receives heartbeats going forward from when you change your api_url. Your historical WakaTime data doesn't automatically transfer. WakaTime Pro allows exporting your data as JSON, which you can import into Wakapi — though the import format isn't officially documented and may require manual scripting.

Container restarts after update

If Wakapi fails to start after pulling a new image, check logs immediately: docker compose logs wakapi. Database migration errors are common across minor versions. Wakapi runs migrations on startup — if the database schema is corrupted or the migration fails, the container crashes. Restoring from backup is the cleanest recovery path.

Leaderboard shows wrong time or missing users

Check that all users have the correct timezone set in their Wakapi profile. Wakapi aggregates by the user's local timezone — if your timezone is set wrong, your daily stats roll over at the wrong time. Also ensure all team members have accounts on the same Wakapi instance (leaderboards only show users registered locally).

See all open source developer tools at OSSAlt.com/categories/developer-tools.