---
title: "Deploy Wakapi | (Just Updated) WakaTime-Compatible Coding Time Tracker, REST API and API Key Generated"
description: "Wakapi WakaTime-compatible coding time tracker with REST API, key preset"
category: "Other"
url: https://railway.com/deploy/wakapi-or-just-updated-wakatime-compatib
---

# 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

**[Deploy Wakapi | (Just Updated) WakaTime-Compatible Coding Time Tracker, REST API and API Key Generated on Railway](https://railway.com/template/wakapi-or-just-updated-wakatime-compatib)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/wakapi-or-just-updated-wakatime-compatib/manifest.json

- **Creator:** SuperSlowSloth
- **Category:** Other

## Template content

### wakapi

- **Image:** ghcr.io/bon5co/wakapi-railway:2.18.2@sha256:6bc7d80904ef7aa5f6b38f83024b68a912b4f42de9c68b925accc908c7660eab
- **Health check:** /api/health
- **Public domain:** Yes

## Documentation

# 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 the `wakapi` service)
- Private URL: `http://wakapi.railway.internal:8080`
- Credentials: the variable `WAKAPI_API_KEY` on the `wakapi` service is the administrator's REST API key; `WAKAPI_ADMIN_PASSWORD` is the web login of the user `admin`; `WAKAPI_PASSWORD_SALT` hashes passwords and is not a login
- Auth: send `Authorization: Bearer BASE64_OF_WAKAPI_API_KEY` on 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/health` returns 200

```bash
#!/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):

```text
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_URL` to it.

### Deployment Dependencies

- [Wakapi repository](https://github.com/muety/wakapi)
- [Wakapi documentation](https://wakapi.dev/)
- [Wrapper image source](https://github.com/bon5co/wakapi-railway)


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — Self-hosted virtual tabletop for role-playing games (license required)
- [Double Commander in your browser](https://railway.com/deploy/double-commander-in-your-browser) — The Double Commander file manager in the cloud, from any device

Open this page in a browser: https://railway.com/deploy/wakapi-or-just-updated-wakatime-compatib
