Installation instructions can be found below and in the Wiki.

• ✅ Free and open-source
• ✅ Built by developers for developers
• ✅ Statistics for projects, languages, editors, hosts and operating systems
• ✅ Badges
• ✅ Weekly E-Mail reports
• ✅ REST API
• ✅ Partially compatible with WakaTime
• ✅ WakaTime integration
• ✅ Support for Prometheus exports
• ✅ Lightning fast
• ✅ Self-hosted

There are different options for how to use Wakapi, ranging from our hosted cloud service to self-hosting it. Regardless of which option choose, you will always have to do the client setup in addition.

If you want to try out a free, hosted cloud service, all you need to do is create an account and then set up your client-side tooling (see below).

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

Alternatively using eget:

$ eget muety/wakapi

# Create a persistent volume
$ docker volume create wakapi-data

$ SALT="$(cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w ${1:-32} | head -n 1)"

# Run the container
$ docker run -d \
  -p 3000:3000 \
  -e "WAKAPI_PASSWORD_SALT=$SALT" \
  -v wakapi-data:/data \
  --name wakapi \
  ghcr.io/muety/wakapi:latest

Note: By default, SQLite is used as a database. To run Wakapi in Docker with MySQL or Postgres, see Dockerfile and config.default.yml for further options.

If you want to run Wakapi on Kubernetes, there is wakapi-helm-chart for quick and easy deployment.

Alternatively, you can use Docker Compose for an even more straightforward deployment. See compose.yml for configuration details.

Wakapi supports Docker Secrets for the following variables: WAKAPI_PASSWORD_SALT, WAKAPI_DB_PASSWORD, WAKAPI_MAIL_SMTP_PASS. You can set these either by having them mounted as a secret file, or directly pass them as environment variables.

export WAKAPI_PASSWORD_SALT=changeme
export WAKAPI_DB_PASSWORD=changeme
export WAKAPI_MAIL_SMTP_PASS=changeme

docker compose up -d

If you prefer to persist data in a local directory while using SQLite as the database, make sure to set the correct user option in the Docker Compose configuration to avoid permission issues.

# Build and install
# Alternatively: go build -o wakapi
$ go install github.com/muety/wakapi@latest

# Get default config and customize
$ curl -o wakapi.yml https://raw.githubusercontent.com/muety/wakapi/master/config.default.yml
$ vi wakapi.yml

# Run it
$ ./wakapi -config wakapi.yml

Note: Check the comments in config.yml for best practices regarding security configuration and more.

💡 When running Wakapi standalone (without Docker), it is recommended to run it as a SystemD service.

Wakapi relies on the open-source WakaTime client tools. In order to collect statistics for Wakapi, you need to set them up.

1. Set up WakaTime for your specific IDE or editor. Please refer to the respective plugin guide
2. Edit your local ~/.wakatime.cfg file as follows.

[settings]

# Your Wakapi server URL or 'https://wakapi.dev/api' when using the cloud server
api_url = http://localhost:3000/api

# Your Wakapi API key (get it from the web interface after having created an account)
api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b

Optionally, you can set up a client-side proxy in addition.

You can specify configuration options either via a config file (default: config.yml, customizable through the -c argument) or via environment variables. Here is an overview of all options.

Wakapi uses GORM as an ORM. As a consequence, a set of different relational databases is supported.

• SQLite (default, easy setup)
• MySQL (recommended, because most extensively tested)
• MariaDB (open-source MySQL alternative)
• Postgres (open-source as well)
• CockroachDB (cloud-native, distributed, Postgres-compatible API)
• Microsoft SQL Server (Microsoft SQL Server)

Wakapi supports different types of user authentication.

• Cookie: This method is used in the browser. Users authenticate by sending along an encrypted, secure, HTTP-only cookie (wakapi_auth) that was set in the server's response upon login.
• API key:
  • Via header: This method is inspired by WakaTime's auth. mechanism and is the common way to authenticate against API endpoints. Users set the Authorization header to Basic <BASE64_TOKEN>, where the latter part corresponds to your base64-hashed API key.
  • Vis query param: Alternatively, users can also pass their plain API key as a query parameter ( e.g. ?api_key=86648d74-19c5-452b-ba01-fb3ec70d4c2f) in the URL with every request.
• Trusted header: This mechanism allows to delegate authentication to a reverse proxy (e.g. for SSO), that Wakapi will then trust blindly. See #534 for details.
  • Must be enabled via trusted_header_auth and configuring trust_reverse_proxy_ip in the config
  • Warning: This type of authentication is quite prone to misconfiguration. Make sure that your reverse proxy properly strips relevant headers from client requests.

See our Swagger API Documentation.

$ go install github.com/swaggo/swag/cmd/swag@latest
$ swag init -o static/docs

You can export your Wakapi statistics to Prometheus to view them in a Grafana dashboard or so. Here is how.

# 1. Start Wakapi with the feature enabled
$ export WAKAPI_EXPOSE_METRICS=true
$ ./wakapi

# 2. Get your API key and hash it
$ echo "<YOUR_API_KEY>" | base64

# 3. Add a Prometheus scrape config to your prometheus.yml (see below)

# prometheus.yml
# (assuming your Wakapi instance listens at localhost, port 3000)

scrape_configs:
  - job_name: 'wakapi'
    scrape_interval: 1m
    metrics_path: '/api/metrics'
    bearer_token: '<YOUR_BASE64_HASHED_TOKEN>'
    static_configs:
      - targets: [ 'localhost:3000' ]

There is also a nice Grafana dashboard, provided by the author of wakatime_exporter.

Wakapi plays well together with WakaTime. For one thing, you can forward heartbeats from Wakapi to WakaTime to effectively use both services simultaneously. In addition, there is the option to import historic data from WakaTime for consistency between both services. Both features can be enabled in the Integrations section of your Wakapi instance's settings page.

Wakapi also integrates with GitHub Readme Stats to generate fancy cards for you. Here is an example. To use this, don't forget to enable public data under Settings -> Permissions.

![](https://github-readme-stats.vercel.app/api/wakatime?username={yourusername}&api_domain=wakapi.dev&bg_color=2D3748&title_color=2F855A&icon_color=2F855A&text_color=ffffff&custom_title=Wakapi%20Week%20Stats&layout=compact)

There is a WakaTime plugin for GitHub Metrics that is also compatible with Wakapi. To use this, don't forget to enable public data under Settings -> Permissions.

Preview:

- uses: lowlighter/metrics@latest
  with:
    # ... other options
    plugin_wakatime: yes
    plugin_wakatime_token: ${{ secrets.WAKATIME_TOKEN }}      # Required
    plugin_wakatime_days: 7                                   # Display last week stats
    plugin_wakatime_sections: time, projects, projects-graphs # Display time and projects sections, along with projects graphs
    plugin_wakatime_limit: 4                                  # Show 4 entries per graph
    plugin_wakatime_url: http://wakapi.dev                    # Wakatime url endpoint
    plugin_wakatime_user: .user.login                         # User

The browser-wakatime plugin enables you to track your web surfing in WakaTime (and Wakapi, of course). Visited websites will appear as "files" in the summary. Follow these instructions to get started:

1. Install the browser extension from the official store (Firefox, Chrome)
2. Open the extension settings dialog
3. Configure it like so (see screenshot below):
   • API Key: Your personal API key (get it at wakapi.dev)
   • Logging Type: Only the domain
   • API URL: https://wakapi.dev/api/compat/wakatime/v1 (alternatively, replace wakapi.dev with your self-hosted instance hostname)
4. Save
5. Start browsing!

Note: the plugin will only sync heartbeats once in a while, so it might take some time for them to appear on Wakapi. To "force" it to sync, simply bring up the plugin main dialog.

If you're using the GNOME desktop, there is a quick way to display your today's coding statistics in the status bar.

Simply install the Executor extension and add the following command as a status bar indicator:

~/.wakatime/wakatime-cli-linux-amd64 --today

You can export your coding activity from Wakapi to CSV in the form of raw heartbeats. While there is no way to accomplish this directly through the web UI, we provide an easy-to-use Python script instead.

$ pip install requests tqdm
$ python scripts/download_heartbeats.py --api_key API_KEY [--url URL] [--from FROM] [--to TO] [--output OUTPUT]

python scripts/download_heartbeats.py --api_key 04648d14-15c9-432b-b901-dbeec70d4eaf \
  --url https://wakapi.dev/api \
  --from 2023-01-01 \
  --to 2023-01-31 \
  --output wakapi_export.csv

It is recommended to use wakapi behind a reverse proxy, like Caddy or nginx, to enable TLS encryption (HTTPS).

However, if you want to expose your wakapi instance to the public anyway, you need to set server.listen_ipv4 to 0.0.0.0 in config.yml.

Unit tests are supposed to test business logic on a fine-grained level. They are implemented as part of the application, using Go's testing package alongside stretchr/testify.

$ CGO_ENABLED=0 go test `go list ./... | grep -v 'github.com/muety/wakapi/scripts'` -json -coverprofile=coverage/coverage.out ./... -run ./...

API tests are implemented as black box tests, which interact with a fully-fledged, standalone Wakapi through HTTP requests. They are supposed to check Wakapi's web stack and endpoints, including response codes, headers and data on a syntactical level, rather than checking the actual content that is returned.

Our API (or end-to-end, in some way) tests are implemented as a Postman collection and can be run either from inside Postman, or using newman as a command-line runner.

To get a predictable environment, tests are run against a fresh and clean Wakapi instance with a SQLite database that is populated with nothing but some seed data (see data.sql). It is usually recommended for software tests to be safe, stateless and without side effects. In contrary to that paradigm, our API tests strictly require a fixed execution order (which Postman assures) and their assertions may rely on specific previous tests having succeeded.

# 1. sqlite (cli)
$ sudo apt install sqlite  # Fedora: sudo dnf install sqlite

# 2. newman
$ npm install -g newman

$ ./testing/run_api_tests.sh

To keep things minimal, all JS and CSS assets are included as static files and checked in to Git. TailwindCSS and Iconify require an additional build step. To only require this at the time of development, the compiled assets are checked in to Git as well.

$ yarn
$ yarn build  # or: yarn watch

New icons can be added by editing the icons array in scripts/bundle_icons.js.

As explained in #284, precompressed (using Brotli) versions of some of the assets are delivered to save additional bandwidth. This was inspired by Caddy's precompressed directive. gzipped.FileServer checks for every static file's .br or .gz equivalents and, if present, delivers those instead of the actual file, alongside Content-Encoding: br. Currently, compressed assets are simply checked in to Git. Later we might want to have this be part of a new build step.

To pre-compress files, run this:

# Install brotli first
$ sudo apt install brotli  # or: sudo dnf install brotli

# Watch, build and compress
$ yarn watch:compress

# Alternatively: build and compress only
$ yarn build:all:compress

# Alternatively: compress only
$ yarn compress

Since Wakapi heavily relies on the concepts provided by WakaTime, their FAQs largely apply to Wakapi as well. You might find answers there.

|---o---o--------------o---o---|
|   |10s|      3m      |10s|   |

• 💻 [Code] Image generator from Wakapi stats – LacazeThomas/wakapi-stats (Go)
• 💻 [Code] Discord integration for Wakapi - LLoneDev6/Wakapi-Discord (JavaScript)
• 💻 [Code] Alternative heartbeats export script - wakapiexporter.nim ( Nim)
• 💻 [Code] Wakapi Helm chart for K8s deployments - andreymaznyak/wakapi-helm-chart (YAML)
• 🗒 [Article] Wakamonth: hours reporting tool

Coding in open source is my passion and I would love to do it on a full-time basis and make a living from it one day. So if you like this project, please consider supporting it 🙂. You can donate either through buying me a coffee or becoming a GitHub sponsor. Every little donation is highly appreciated and boosts my motivation to keep improving Wakapi!

I highly appreciate the efforts of @alanhamlett and the WakaTime team and am thankful for their software being open source.

Moreover, thanks to server.camp for sponsoring server infrastructure for Wakapi.dev.

MIT @ Ferdinand Mütsch