Getting started

What Tick is, what it does, and how to get a copy running in two minutes.

What is Tick?

Tick is a self-hosted, MIT-licensed time tracker for freelancers and small teams. It pairs a persistent one-keystroke timer with a fast entries list, an open-ended client → project → task model, safe deletion everywhere (soft delete, cascade previews, 30-day trash, undo), server-resolved billable rates, and a built-in theme editor — all in a single small app you run with Docker or plain Node.

It runs as one Nuxt app in front of one PostgreSQL database. There is no required external service: auth is session-based (scrypt-hashed passwords), and everything — timer, entries, catalog, reports, PDF rendering, theming — is served from the same process. An SMTP server is the one optional extra, and only to email invites and password-reset links.

Features

Sticky timer bar on every page: start typing, hit Enter, attach a client/project/task later. Run up to ten timers at once — the bar holds the one you pin, the rest live in the running list.
Time page: entries grouped by day or by project, free-text filtering with #tag and @name shortcuts, bulk select with Mark billable, Move to… and Delete.
Manual entries with forgiving free-text parsing — yesterday, last tue, 2pm, 1.5h and 90m all work. See the full format table.
Open-ended structure: every entry is "simple" until you attach something. Entries store a single reference (client, project or task); the rest of the chain is derived at read time, so re-filing a task re-files its history automatically.
Rates resolve server-side, first non-null wins: entry override → project → client → org member → user default.
Safe deletion: cascade-delete dialogs preview exactly what happens, everything soft-deletes into a 30-day trash, and every destructive action gets an undo toast with a visible countdown.
Dashboard with today/week stat cards, a 16-week activity grid, a billable donut and per-day bars — drawn in with GSAP.
Reports over any range, regroupable by client / project / task / tag, with CSV and server-rendered PDF export. See Reports & calendar.
Calendar week and day views where entries are drag-created, dragged between days and resized on a 5-minute grid.
Import from Toggl Track, Clockify or any CSV, with a dry-run preview before a single row is written.
Theme editor: 12 presets, 17 primary colors, 9 neutral palettes, radius, five fonts, dark/light, optional sidebar starfield. Applies live and persists per user.
Multi-user orgs with owner/admin/member roles, per-member rates, and invite links that are emailed when SMTP is configured and copyable when it is not.
Self-hoster controls: registration modes (open / invite-only / closed), password reset with or without SMTP, auth rate limiting, security headers and CSP — see Security.
Installable PWA with a mobile layout, so the phone version is a real app rather than a shrunken desktop.

Quickstart (Docker Compose)

The repository ships a docker-compose.yml that runs the app plus a bundled Postgres 17 with a persistent volume. Migrations apply automatically on startup.

git clone https://github.com/ticktimer/Tick.git tick && cd tick
cp .env.example .env
# edit .env: set NUXT_SESSION_PASSWORD (openssl rand -base64 36)
docker compose up -d

Open http://localhost:3000 and register your first account. Registering creates a personal organization with you as its owner.

Other install paths (plain docker run against your own Postgres, or native Node + PM2) are covered in Installation.

Registration is open by default — anyone who can reach the host can create a workspace. Before exposing an instance, set NUXT_PUBLIC_REGISTRATION=invite (or closed) and put TLS in front of it. The security checklist is short and worth reading once.

Demo data

For development or a demo instance, the seed script fills the database with a realistic org — three clients, five projects, tasks, tags and about three weeks of time entries:

npm run db:seed

Then log in with:

Field	Value
Email	`mara@example.com`
Password	`tick-demo`

The seeded user (Mara Juhl, org "Hollow Studio", $85/h default rate) has data on the dashboard, the Time page and every manage page, so you can explore the whole app immediately.

Where to go next

Installation — Docker, docker run, native + PM2, reverse proxy, SMTP, registration modes.
Timer & entries — the day-to-day tracking workflow.
Projects, clients & tasks — how the data model and rates work.
Security — what the app protects, and what you have to do before going public.
Data model and API routes — for integrating or contributing.

Installation

Run Tick with Docker Compose, plain docker run, or natively with Node and PM2.