Deploying Wakapi

Introduction

Wakapi is a self-hosted, open-source alternative to WakaTime for tracking your coding time and activity. Compatible with existing WakaTime plugins and IDE extensions, Wakapi provides detailed insights into your programming habits while keeping all your data private on your own server.

Key highlights of Wakapi:

• WakaTime Compatible: Works with all existing WakaTime editor plugins
• Detailed Statistics: Track time by language, project, editor, and more
• Dashboard: Visual charts and graphs of your coding activity
• Goals: Set and track weekly coding goals
• Leaderboards: Compare coding time with other users on your instance
• API: REST API for integrations and custom dashboards
• Privacy Focused: Your coding data stays on your server
• Lightweight: Minimal resource requirements with SQLite or PostgreSQL
• Multiple Users: Support for teams and organizations

This guide walks through deploying Wakapi on Klutch.sh using Docker, configuring the time tracker, and connecting your IDE.

Why Deploy Wakapi on Klutch.sh

Deploying Wakapi on Klutch.sh provides several advantages for coding time tracking:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Wakapi without complex orchestration. Push to GitHub, and your time tracker deploys automatically.

Persistent Storage: Attach persistent volumes for your coding statistics database. Your activity history survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API communication with your IDE plugins.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Always Available: Your coding statistics are accessible 24/7 for tracking and analysis.

Prerequisites

Before deploying Wakapi on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• An IDE with WakaTime plugin support (VS Code, JetBrains, Vim, etc.)

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Wakapi deployment.

Repository Structure

wakapi-deploy/
├── Dockerfile
├── config.yml
└── .dockerignore

Creating the Dockerfile

FROM ghcr.io/muety/wakapi:latest

# Copy custom configuration
COPY config.yml /app/config.yml

# Set environment variables
ENV WAKAPI_DB_TYPE=${WAKAPI_DB_TYPE:-sqlite3}
ENV WAKAPI_DB_NAME=${WAKAPI_DB_NAME:-/data/wakapi.db}
ENV WAKAPI_PASSWORD_SALT=${WAKAPI_PASSWORD_SALT}
ENV WAKAPI_LISTEN_IPV4=${WAKAPI_LISTEN_IPV4:-0.0.0.0}
ENV WAKAPI_PORT=${WAKAPI_PORT:-3000}

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 3000

# Volume for persistent data
VOLUME ["/data"]

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1

Creating the Configuration File

Create a config.yml file:

env: production

server:
  listen_ipv4: 0.0.0.0
  port: 3000
  base_path: /
  public_url: ${WAKAPI_PUBLIC_URL}

db:
  host:
  port:
  name: /data/wakapi.db
  dialect: sqlite3
  max_conn: 2

security:
  password_salt: ${WAKAPI_PASSWORD_SALT}
  insecure_cookies: false
  cookie_max_age: 172800
  allow_signup: true
  expose_metrics: true

mail:
  enabled: false

sentry:
  dsn:

Environment Variables Reference

Variable	Required	Default	Description
WAKAPI_DB_TYPE	No	sqlite3	Database type (sqlite3, postgres, mysql)
WAKAPI_DB_NAME	No	/data/wakapi.db	Database name or path
WAKAPI_PASSWORD_SALT	Yes	-	Salt for password hashing
WAKAPI_PUBLIC_URL	Yes	-	Public URL of your Wakapi instance
WAKAPI_PORT	No	3000	Server port

Deploying Wakapi on Klutch.sh

Generate a Password Salt

Generate a secure password salt:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “wakapi” or “coding-tracker”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Wakapi Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
WAKAPI_PASSWORD_SALT	Your generated salt
WAKAPI_PUBLIC_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
/data	5 GB	SQLite database with coding statistics

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Access Wakapi

Once deployment completes, access your Wakapi instance at https://your-app-name.klutch.sh. Create an account to get started.

Connecting Your IDE

Getting Your API Key

1. Log in to your Wakapi instance
2. Navigate to Settings
3. Find your API key in the API section
4. Copy the key for plugin configuration

Configuring WakaTime Plugin

VS Code

1. Install the WakaTime extension
2. When prompted, enter your API key
3. Configure the API URL in settings:

{
  "wakatime.apiUrl": "https://your-wakapi.klutch.sh/api"
}

Or create/edit ~/.wakatime.cfg:

[settings]
api_url = https://your-wakapi.klutch.sh/api
api_key = your-api-key

JetBrains IDEs

1. Install the WakaTime plugin from the marketplace
2. Go to Settings > WakaTime
3. Enter your API key
4. Set the API URL to your Wakapi instance

Vim/Neovim

Add to your .wakatime.cfg:

[settings]
api_url = https://your-wakapi.klutch.sh/api
api_key = your-api-key

Verifying Connection

1. Open a project in your IDE
2. Make some edits to trigger heartbeats
3. Check your Wakapi dashboard for incoming data
4. Data should appear within a few minutes

Understanding Your Statistics

Dashboard Overview

The main dashboard shows:

• Total coding time (today, week, month)
• Time by language
• Time by project
• Time by editor/IDE
• Daily activity chart

Projects

View detailed statistics per project:

• Total time spent
• Languages used
• Active days
• Recent activity

Goals

Set weekly coding goals:

1. Navigate to Goals
2. Set target hours per week
3. Track progress on the dashboard

Leaderboards

Compare with other users:

• View rankings by coding time
• Filter by time period
• Compete with teammates

Advanced Configuration

PostgreSQL Database

For larger deployments, use PostgreSQL:

db:
  dialect: postgres
  host: your-postgres-host
  port: 5432
  name: wakapi
  user: wakapi
  password: ${DB_PASSWORD}

Email Notifications

Enable email for reports:

mail:
  enabled: true
  smtp:
    host: smtp.example.com
    port: 587
    username: ${SMTP_USER}
    password: ${SMTP_PASS}
    tls: true
  sender: wakapi@example.com

Troubleshooting

Heartbeats Not Recording

• Verify API URL in plugin configuration
• Check API key is correct
• Ensure HTTPS is working
• Review IDE plugin logs

Statistics Not Updating

• Wait a few minutes for processing
• Check the Wakapi logs for errors
• Verify database is accessible

Login Issues

• Check password salt hasn’t changed
• Clear browser cookies
• Verify account exists

Additional Resources

• Wakapi Official Website
• Wakapi GitHub Repository
• WakaTime Plugins (compatible with Wakapi)
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Wakapi on Klutch.sh gives you a privacy-focused coding time tracker compatible with the WakaTime ecosystem. The combination of Wakapi’s detailed statistics and Klutch.sh’s deployment simplicity means you can quickly start tracking your programming activity while keeping your data under your control.