---
title: "Deploy Kimai | (Just Updated) Time Tracking App with REST API, Admin and API Token Generated"
description: "Kimai time tracking app with REST API, admin and API token preset"
category: "Other"
url: https://railway.com/deploy/kimai-or-just-updated-time-tracking-app-
---

# Deploy Kimai | (Just Updated) Time Tracking App with REST API, Admin and API Token Generated

Kimai time tracking app with REST API, admin and API token preset

**[Deploy Kimai | (Just Updated) Time Tracking App with REST API, Admin and API Token Generated on Railway](https://railway.com/template/kimai-or-just-updated-time-tracking-app-)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/kimai-or-just-updated-time-tracking-app-/manifest.json

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

## Template content

### mariadb

- **Image:** mariadb:11.8@sha256:6422478cb8e159f080fb1d8ccf65101e26fe51385787fde7d16c3b165a331f15
- **Start command:** `/bin/sh -c 'set -e; M=$(cat /sys/fs/cgroup/memory.max 2>/dev/null || echo max); if [ "$M" != max ]; then B=$((M / 2 / 1048576)); [ "$B" -lt 128 ] && B=128; else B=512; fi; export MARIADB_DATABASE=kimai MARIADB_USER=kimai; echo "[railway] uid=$(id -u) innodbBufferPoolMB=$B owner=$(stat -c %u:%g /var/lib/mysql)"; exec docker-entrypoint.sh mariadbd --datadir=/var/lib/mysql/data --innodb-buffer-pool-size=${B}M --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci'`

### kimai

- **Image:** ghcr.io/bon5co/kimai-railway:2.72.0@sha256:ebe85f28cf6625baf247022d866662eb66a5294f92ce4ed4cec28af40d7226ee
- **Health check:** /en/login
- **Public domain:** Yes

## Documentation

# Deploy and Host Kimai on Railway

**Built for an LLM agent to deploy and use.** The deploy form has no fields to fill: the database password, the administrator's password and an API access token are generated, the administrator account `admin` is created at first boot, the API token is seeded for it, and the database and uploaded files sit on volumes. Kimai is the open-source, self-hosted time-tracking application for freelancers and teams, with timesheets, projects, customers, invoices, reports and a REST API.

## About Hosting Kimai

This template runs two services: **kimai**, the upstream Kimai 2.72.0 image (pinned by digest) through a thin wrapper, and **mariadb**, a pinned MariaDB 11.8 with a volume at `/var/lib/mysql`. The kimai service has its own volume at `/opt/kimai/var/data` for the persisted application secret, uploads and invoice files. Both volumes survive redeploys, so customers, projects, timesheets and users persist. The service listens on Railway's injected `PORT`, and the healthcheck is `GET /en/login`.

**What the wrapper fixes.** Kimai's REST API accepts only access tokens that a signed-in person creates in the web interface, so a fresh deploy has no API credential until someone clicks through the settings. The wrapper seeds one access token for the administrator from the generated `KIMAI_API_TOKEN` once the database is installed, so an agent can call `/api/*` from the first request. It also binds Apache to Railway's injected `PORT`, refuses to start without an administrator password, and re-enables the Apache module Railway otherwise drops.

**Using it.** Sign in at the public URL as `admin` with the value of `ADMINPASS`, or call the API with `KIMAI_API_TOKEN` as a Bearer token. The administrator's address is the placeholder `admin@example.com`; change it in the profile settings. Kimai has no public registration route; further users are created by the administrator. Outgoing email is not configured; add the upstream `MAILER_URL` and `MAILER_FROM` variables described in the Kimai documentation to enable password resets and notifications.

### Agent contract

- Public URL: `https://RAILWAY_PUBLIC_DOMAIN` (the generated domain of the `kimai` service)
- Private URL: `http://kimai.railway.internal:8080`
- Credentials: the variables `ADMINPASS` (web login for the user `admin`) and `KIMAI_API_TOKEN` (API access token) on the `kimai` service; `DATABASE_URL` is the database connection and is not a login
- Auth: send `Authorization: Bearer KIMAI_API_TOKEN (the value of the variable)` on every `/api/*` call. A request with no token or a wrong token answers 401. Public sign-up does not exist.
- Health: `GET /en/login` returns 200

```bash
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, KIMAI_API_TOKEN, ADMINPASS (variables of the kimai service; the user name is admin); also curl, sed. Creates one throwaway customer and deletes it.
R="https://$RAILWAY_PUBLIC_DOMAIN"; J="Content-Type: application/json"; A="Authorization: Bearer $KIMAI_API_TOKEN"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/en/login")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/en/login"
# read with the token
curl -s -o /dev/null -w "read version: %{http_code}\n" -H "$A" "$R/api/version"
# write with the token: create a customer, read it back, delete it
ID=$(curl -s -X POST -H "$J" -H "$A" -d '{"name":"agent-contract-check","country":"US","currency":"USD","timezone":"UTC"}' "$R/api/customers" | sed -n 's/^{[^}]*"id":\([0-9]*\),.*/\1/p')
if [ -n "$ID" ]; then echo "write customer: created"; else echo "write customer: FAILED"; fi
curl -s -o /dev/null -w "read customer: %{http_code}\n" -H "$A" "$R/api/customers/$ID"
curl -s -o /dev/null -w "delete customer: %{http_code}\n" -X DELETE -H "$A" "$R/api/customers/$ID"
# refusals: no token, wrong token, public sign-up
curl -s -o /dev/null -w "write without key: %{http_code}\n" -X POST -H "$J" -d '{"name":"x","country":"US","currency":"USD","timezone":"UTC"}' "$R/api/customers"
curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -X POST -H "$J" -H "Authorization: Bearer not-a-token" -d '{"name":"x","country":"US","currency":"USD","timezone":"UTC"}' "$R/api/customers"
curl -s -o /dev/null -w "public signup: %{http_code}\n" -X POST -H "$J" -d '{"username":"intruder","email":"intruder@example.com"}' "$R/en/register/"
```

Expected output against a fresh deploy (measured on a Railway deploy of this template):

```text
health: 200
read version: 200
write customer: created
read customer: 200
delete customer: 204
write without key: 401
write wrong key: 401
public signup: 404
```

The refusals are the contract: `write without key: 401`, `write wrong key: 401` and `public signup: 404` (the registration route does not exist). The first five lines show the token can read and write the API.

## Why Deploy Kimai 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 Kimai 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 token can write, and unauthenticated writes and sign-ups are refused.
- **Administrator and API token from variables** - both are created at boot from generated credentials, with no click-through step.
- **No public sign-up** - nobody else can register on the public URL.
- **Data survives redeploys** - the MariaDB database and Kimai's uploads live on volumes.
- **Pinned** - the upstream image and MariaDB are pinned by digest and the wrapper by tag and digest.

## Common Use Cases

- **Self-hosted time tracking** - timesheets, activities and projects in a database you control.
- **Freelancer invoicing** - track billable hours per customer and generate invoices and exports.
- **Team time reports** - budgets, teams and reporting for agencies and small companies.
- **Time-tracking backend for an AI agent** - give an automation a REST API to start, stop and query timesheets.

## Dependencies for Kimai Hosting

- The kimai and mariadb services with their volumes, created by the template. A custom domain is optional.

### Deployment Dependencies

- [Kimai repository](https://github.com/kimai/kimai)
- [Kimai documentation](https://www.kimai.org/documentation/)
- [Wrapper image source](https://github.com/bon5co/kimai-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/kimai-or-just-updated-time-tracking-app-
