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
mariadb
Just deployed
/var/lib/mysql
Just deployed
/opt/kimai/var/data
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 thekimaiservice) - Private URL:
http://kimai.railway.internal:8080 - Credentials: the variables
ADMINPASS(web login for the useradmin) andKIMAI_API_TOKEN(API access token) on thekimaiservice;DATABASE_URLis 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/loginreturns 200
#!/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):
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
Template Content
mariadb
mariadb:11.8