Developer Tools AWS

Wakapi Coding Analytics on AWS User Guide

| Product: Wakapi on AWS

Overview

This guide covers the deployment and configuration of Wakapi on AWS using cloudimg AWS Marketplace AMIs. Wakapi is a self hosted, WakaTime compatible coding-activity and statistics server. It receives heartbeats from the standard WakaTime editor plugins for Visual Studio Code, JetBrains IDEs, Vim, Sublime Text and dozens more, then renders clear dashboards of how much time you spend per project, per programming language, per editor and per machine, with daily and ranged summaries and an all time overview. Because it speaks the WakaTime API, your existing editor setup points at your own server by changing a single line of configuration, and your coding history stays entirely on infrastructure you control.

The cloudimg image ships the free and open source, MIT licensed Wakapi (muety/wakapi), installed as the official single Go binary and reverse proxied behind nginx, with the SQLite activity database on a dedicated data volume, so your instance starts in seconds. Wakapi binds only to loopback and is reached solely through nginx. There is no default login: a per instance administrator account with a random password and a per instance password salt are generated on each machine's first boot, before the server is reachable, and are never baked into the image. Public self sign up is disabled so the server is single tenant rather than an open registration service. Backed by 24/7 cloudimg support.

Wakapi is a trademark of its respective owner. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by the Wakapi project. It ships the free and open source MIT licensed self hosted software, unmodified.

What is included:

  • Wakapi 2.17.5 (the MIT licensed self hosted, WakaTime compatible coding statistics server), installed as the official single Go binary at /usr/local/bin/wakapi
  • An nginx reverse proxy publishing the web UI on port 80, ready for your TLS certificate; Wakapi itself binds only to loopback 127.0.0.1:3000
  • The SQLite activity database on a dedicated gp3 data volume mounted at /var/lib/wakapi, on its own independently resizable disk
  • wakapi.service, nginx.service and wakapi-firstboot.service as systemd units, enabled and active on boot
  • A per instance admin account with a random password and a per instance password salt generated on first boot, never baked into the image
  • No default login, no shipped secret, public self sign up disabled and an empty database on first boot
  • A fully patched Ubuntu 24.04 LTS base with unattended security upgrades
  • 24/7 cloudimg support with a guaranteed 24 hour response SLA

Wakapi sign-in

Connecting to your instance

Connect over SSH on port 22 as the default login user for the operating system variant you launched:

OS variant SSH login user
Ubuntu 24.04 ubuntu 
ssh ubuntu@<vm-ip>

Prerequisites

  • An AWS account subscribed to the Wakapi listing on AWS Marketplace
  • A key pair in the target region for SSH access
  • A security group allowing inbound TCP 22 (SSH) and 80 (web UI) from your IP ranges

Step 1: Launch from the AWS Marketplace console

Subscribe to the Wakapi listing, choose Launch through EC2, pick the m5.large recommended instance type (or larger), select your key pair and a security group that allows ports 22 and 80, and launch. The dedicated data volume for the activity database is attached automatically.

Step 2: Launch from the AWS CLI

aws ec2 run-instances \
  --image-id ami-xxxxxxxxxxxxxxxxx \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=wakapi}]'

Step 3: Connect to your instance

ssh ubuntu@<vm-ip>

Step 4: Confirm the services are running

Wakapi runs as a single Go binary under wakapi.service, fronted by nginx.service. Both should be active:

systemctl is-active wakapi.service nginx.service

Step 5: Read the per instance credentials

The first boot generates a unique admin password, password salt and WakaTime API key for this instance and writes them to a root only file:

sudo cat /root/wakapi-info.txt

You will see the admin username (admin), its random password, the account's WakaTime API key and the resolved WAKAPI_URL for this instance. Keep this file safe; nothing here is shared between instances and nothing was baked into the image.

Step 6: Verify the security model

Confirm the login page is served over HTTP on port 80, that Wakapi listens only on loopback, and that public sign up is refused:

# login page served through nginx on port 80
curl -s -o /dev/null -w 'login page: HTTP %{http_code}\n' http://localhost/login
# wakapi binds to loopback only (never the public interface)
sudo ss -ltnp | grep -q '127.0.0.1:3000' && echo 'wakapi bound to loopback 127.0.0.1:3000 only'
# a public sign-up attempt is refused (single-tenant appliance)
curl -s -o /dev/null -w 'signup attempt: HTTP %{http_code} (403 = disabled, as expected)\n' \
  --data-urlencode 'username=notallowed' --data-urlencode 'password=abcd1234efgh' \
  --data-urlencode 'password_repeat=abcd1234efgh' --data-urlencode 'location=UTC' \
  http://localhost/signup

Step 7: Sign in and load the dashboard

Log in with the per instance admin credentials and confirm the statistics dashboard responds:

CJ=$(mktemp)
curl -s -o /dev/null -c "$CJ" \
  --data-urlencode 'username=admin' --data-urlencode 'password=<WAKAPI_ADMIN_PASSWORD>' \
  http://localhost/login
curl -s -o /dev/null -w 'dashboard: HTTP %{http_code}\n' -b "$CJ" http://localhost/summary
rm -f "$CJ"

In a browser, open http://<vm-ip>/ and sign in with the username admin and the password from /root/wakapi-info.txt. The dashboard breaks your activity down per project, per language and per editor.

Coding-activity dashboard

Step 8: Point your editor at your Wakapi server

Wakapi speaks the WakaTime API, so any editor with the WakaTime plugin can send heartbeats to it. Install the WakaTime plugin for your editor, then set its config file to your server. This edits a file on your workstation, not on the instance:

# ~/.wakatime.cfg on YOUR workstation (edit your-domain to your instance URL)
# [settings]
# api_url = http://your-domain/api
# api_key = <the WAKAPI_API_KEY from /root/wakapi-info.txt>
echo 'Set api_url and api_key in ~/.wakatime.cfg using the wakatime-cli plugin settings'

As you code, heartbeats flow to your server and the dashboards fill in. You can also find and reset the account's API key from Settings.

API key and editor integration

Step 9: Explore per project statistics

Every project you work on gets its own drill down, with its languages, editors, branches, files and hourly breakdown, so you can see exactly where your time goes on a single codebase.

Per-project statistics

Step 10: Confirm the pinned release

/usr/local/bin/wakapi -version

Step 11: Import history (optional)

Wakapi can import your existing coding history from a WakaTime account or another Wakapi instance from the Settings page, so you do not lose your past activity when you self host.

Step 12: Server components

The appliance is intentionally minimal:

  • Wakapi runs as wakapi.service, a single Go binary bound to 127.0.0.1:3000, reading /etc/wakapi/config.yml plus the per instance overrides in /etc/wakapi/wakapi.env
  • nginx (nginx.service) is the only public listener, reverse proxying port 80 to Wakapi and ready for your TLS certificate
  • The SQLite activity database lives at /var/lib/wakapi/wakapi.db on a dedicated gp3 data volume; it is a file and is never network reachable
  • wakapi-firstboot.service generates the per instance salt and admin account on first boot and then disables itself

Step 13: Managing the service

Standard systemctl commands manage the stack (these edit runtime state, so run them when you intend to):

sudo systemctl restart wakapi.service
sudo systemctl restart nginx.service

Step 14: Use your own domain and HTTPS (production)

For production, front the instance with your own domain and a certificate. Point a DNS record at the instance, then terminate TLS either at an AWS load balancer or on the instance with certbot:

# on the instance, after pointing your-domain at it
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain

Wakapi derives its public URL from WAKAPI_PUBLIC_URL in /etc/wakapi/wakapi.env; update it to https://your-domain/ after enabling TLS.

Step 15: Security recommendations

  • Change the admin password after first login from Settings
  • Restrict the security group for port 80 to known ranges, or place the instance behind a load balancer that terminates TLS
  • Keep public sign up disabled (the default) so the server stays single tenant; add users deliberately if you need them
  • Take regular snapshots of the /var/lib/wakapi data volume to back up your activity database

Step 16: Support and Licensing

Wakapi is distributed under the MIT license. This is a repackaged open source product; cloudimg's charges are for support services, not for the software itself.

cloudimg provides 24/7 technical support with a guaranteed 24 hour response SLA. Email support@cloudimg.co.uk or use live chat for help with deployment, TLS termination, editor plugin configuration, backups, user management and scaling.

Deploy on AWS

Find Wakapi on AWS Marketplace and launch it with cloudimg's preconfigured AMI.