Deploy Wakapi | (Just Updated) WakaTime-Compatible Coding Time Tracker, REST API and API Key Generated
Wakapi WakaTime-compatible coding time tracker with REST API, key preset
Just deployed
/data
Deploy and Host Wakapi on Railway
Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the administrator password, the password salt and a REST API key are generated, the administrator is created at first boot, public sign-up is closed, and the SQLite database sits on a volume. Wakapi is the open-source, self-hosted, WakaTime-compatible backend for coding time tracking: editors send heartbeats to its REST API and it reports time per project, language and editor.
About Hosting Wakapi
This template runs one service, wakapi, the upstream Wakapi 2.18.2 image (pinned by digest) through a thin wrapper, with a volume at /data that holds the SQLite database (users, API keys, heartbeats), so everything survives redeploys. The server listens on Railway's injected PORT, and the healthcheck is GET /api/health.
What the wrapper fixes. A fresh upstream Wakapi has no users and open registration: the first visitor to the public URL registers and becomes the administrator, and the REST API accepts only a per-user API key that is created at registration and shown after sign-in. The upstream image is distroless, so it cannot script any of that. The wrapper creates the administrator before the server listens on the public port, seeds the administrator's API key from the generated variable WAKAPI_API_KEY, and sets WAKAPI_ALLOW_SIGNUP=false so /signup answers 403.
Using it. Point a WakaTime plugin at https://DOMAIN/api with the key from WAKAPI_API_KEY (or call the REST API directly). Sign in to the web interface as admin with WAKAPI_ADMIN_PASSWORD. Keep WAKAPI_PASSWORD_SALT stable: changing it locks every password out. To rotate the API key, change WAKAPI_API_KEY and redeploy. To add real users, set WAKAPI_ALLOW_SIGNUP=true on the wakapi service by hand.
Agent contract
- Public URL:
https://RAILWAY_PUBLIC_DOMAIN(the generated domain of thewakapiservice) - Private URL:
http://wakapi.railway.internal:8080 - Credentials: the variable
WAKAPI_API_KEYon thewakapiservice is the administrator's REST API key;WAKAPI_ADMIN_PASSWORDis the web login of the useradmin;WAKAPI_PASSWORD_SALThashes passwords and is not a login - Auth: send
Authorization: Bearer BASE64_OF_WAKAPI_API_KEYon every API call (Wakapi decodes the token as base64, as WakaTime clients send it). A write with no key answers 401, a write with a wrong key answers 401, and public sign-up answers 403. - Health:
GET /api/healthreturns 200
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, WAKAPI_API_KEY (variables of the wakapi service); also curl, base64, date, grep. Sends one throwaway heartbeat.
R="https://$RAILWAY_PUBLIC_DOMAIN"; J="Content-Type: application/json"; A="Authorization: Bearer $(printf %s "$WAKAPI_API_KEY" | base64 | tr -d '\n')"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/api/health")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/api/health"
# read with the key
curl -s -o /dev/null -w "read summary: %{http_code}\n" -H "$A" "$R/api/summary?interval=today"
# write with the key: post one heartbeat, read it back as a project in today's summary
curl -s -o /dev/null -w "write heartbeat: %{http_code}\n" -X POST -H "$J" -H "$A" -d "[{\"entity\":\"/tmp/contract.go\",\"type\":\"file\",\"category\":\"coding\",\"time\":$(date +%s),\"project\":\"agent-contract-check\",\"language\":\"Go\"}]" "$R/api/heartbeats"
if curl -s -H "$A" "$R/api/summary?interval=today" | grep -q "agent-contract-check"; then echo "read back: found"; else echo "read back: MISSING"; fi
# refusals: no key, wrong key, public sign-up
INTRUDER=intruder-12345
curl -s -o /dev/null -w "write without key: %{http_code}\n" -X POST -H "$J" -d '[{"entity":"/tmp/x.go","type":"file","time":1}]' "$R/api/heartbeats"
curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -X POST -H "$J" -H "Authorization: Bearer bm90LXRoZS1rZXk=" -d '[{"entity":"/tmp/x.go","type":"file","time":1}]' "$R/api/heartbeats"
curl -s -o /dev/null -w "public signup: %{http_code}\n" -X POST -d username=intruder -d "password=$INTRUDER" -d "password_repeat=$INTRUDER" "$R/signup"
Expected output against a fresh deploy (measured on a Railway deploy of this template):
health: 200
read summary: 200
write heartbeat: 201
read back: found
write without key: 401
write wrong key: 401
public signup: 403
The refusals are the contract: write without key: 401, write wrong key: 401 and public signup: 403 (no second user can register). The first four lines show the API key works for reads and writes.
Why Deploy Wakapi on Railway?
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying Wakapi on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
- Agent-ready - no deployer fields, a contract block, and one script that proves the instance is healthy, the API key can read and write, and unauthenticated writes and sign-ups are refused.
- Setup done for you - the administrator and the API key are created from generated variables before the server listens, so nobody can claim the instance.
- Sign-up closed - nobody else can register on the public URL.
- Data survives redeploys - users, keys and heartbeats live in SQLite on a volume.
- Pinned - the upstream image is pinned by digest and the wrapper by tag and digest.
Common Use Cases
- Self-hosted WakaTime alternative - keep your coding time data on your own server and use the same editor plugins.
- Team coding statistics and leaderboards - per project, language and editor reports without a third party.
- Time tracking for an AI agent's coding sessions - post heartbeats and read summaries over the REST API.
- Coding time badges and README stats - share totals from your own host.
Dependencies for Wakapi Hosting
- The wakapi service with its volume, created by the template. A custom domain is optional; if you add one, set
WAKAPI_PUBLIC_URLto it.
Deployment Dependencies
Template Content
