Hamstrack

Source-available under the Elastic License 2.0 — not an OSI-approved open-source licence. You may self-host, modify and use Hamstrack commercially, free of charge; you may not offer it to third parties as a hosted or managed service, circumvent its license-key functionality, or remove its licensing notices.

Hamstrack is a source-available task tracker for software teams: workspaces, projects, kanban boards, backlog, workflows, comments, attachments and real-time updates — in a single deployable JAR.

One codebase ships in two deployment models:

	Cloud	DC (self-hosted)
Where	hamstrack.com	Your own server
Setup	Sign up and go	Docker Compose, one container + PostgreSQL (or the JAR, if you already run JVMs)
File storage	S3	Local filesystem (or any S3-compatible store)
Configuration	Managed	Fully under your control via environment variables
Run it yourself	deploy/cloud/ — S3 via MinIO, no AWS account, no public DNS (guide)	deploy/dc/ — the path below

Either model is yours to run, for yourself or your organisation. The licence (ELv2) forbids one thing: offering Hamstrack to third parties as a managed service. The two profiles differ only in defaults, and every behaviour they disagree about is a plain environment variable you can set under either — the one thing no variable moves is the deployment label on log lines. The Cloud-model guide carries the current table of those defaults, which is where the list lives so that it cannot go stale in two places. Most people self-hosting want DC, which is the path below.

What is in the repository. The operator documentation is docs/ — start with the Self-hosting guide — and the stacks you install from are under deploy/. CLAUDE.md, PLAN.md, DESIGN.md and .claude/ are not part of installing or running Hamstrack: they are how it is built — the engineering conventions, the roadmap, the visual system, and the agents and review gates every change goes through. They are tracked on purpose, so if you came for how the product is made rather than what it does, start there instead.

Status: Hamstrack is in active development — breaking changes are called out in the release notes. Hamstrack Cloud does not reset user data. Your workspaces, projects and issues stay until they are deleted. The database is backed up daily and restoring from a backup has been tested; that is an operational practice, not a guaranteed service level. Every account starts with a demo workspace and a sample project to explore.

Features

• Workspaces — the tenancy boundary; invite members by email with role-based access (OWNER / ADMIN / MEMBER)
• Projects — per-workspace, with keys (DEMO-42), archiving and project-level roles (Project admin / Team lead / Contributor / Commenter / Viewer)
• Roles & permissions — every gate is a permission, not a rung: 29 permission keys, eight built-in roles, and workspace-defined custom roles built by duplicating one; a workspace switch decides whether people who were never added to a project can work in it
• Issues — issue types, statuses, priorities and custom fields, plus assignees, due dates, sub-task links, change history and optimistic locking
• Kanban board — drag-and-drop between status columns, workflow-transition rules enforced on drop
• Backlog — flat table of all unfinished work
• Comments & attachments — with @mentions, soft delete and per-issue file uploads
• Admin console — a system administrator manages a global catalog of statuses, priorities, issue types and custom fields, bundles them into reusable workflows and sets, and assigns those to projects from a bulk-editable matrix (/admin)
• Notifications — in-app bell plus live updates over Server-Sent Events; email for verification, invites and password recovery
• Auth — email registration with verification, JWT access tokens, rotating refresh-token cookie, password recovery

Self-hosting (DC)

Hamstrack self-hosts as a single Docker image (ghcr.io/zherikhov/hamstrack) plus PostgreSQL — SPRING_PROFILES_ACTIVE=dc, everything else via environment variables. The stack is in this repository at deploy/dc/; the schema migrates itself on startup (Flyway). The image is published for linux/amd64 only — there is no arm64 build, so the commands below need an x86-64 host (Requirements).

git clone https://github.com/Zherikhov/hamstrack.git
cd hamstrack/deploy/dc
cp .env.example .env
# Fill DB_PASSWORD, JWT_SECRET, SEED_ADMIN_EMAIL, SEED_ADMIN_PASSWORD.
# If you skip one, the next command refuses and names it.
docker compose up -d --wait --wait-timeout 300

That command exits non-zero if the stack does not come up, so its exit code is the check: a plain docker compose up -d returns 0 even while a container is crash-looping. On success it returns once both services are healthy (~35s on a warm image) — the timeout is a ceiling on waiting, not a wait. On failure it names the service — container dc-app-1 is unhealthy — and docker compose logs app carries the reason, because the application refuses a bad value by name at startup.

If that failure names the app while docker compose logs app shows it still starting — or already started — the stack is fine and the healthcheck gave up too early. Raise APP_START_PERIOD_SECONDS in .env (default 180, which allows the app 230s to answer before it is called unhealthy) and run the command again. Raising --wait-timeout cannot fix that one: it bounds how long the command waits, and by then the container has already been marked unhealthy. The app has been measured starting in 96s on a modest Linux server, so a slower or CPU-throttled host is the case this variable exists for — Troubleshooting has the two symptoms side by side.

Then open http://localhost:8080 and sign in with SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD. No SMTP server and no domain are needed for this. Your instance serves its own API reference at /docs, rendered from the OpenAPI spec at /openapi.yaml.

To pin a release line rather than track the current one, set APP_IMAGE_TAG in deploy/dc/.env; the template names the current line and says why latest is the wrong answer.

Running it without Docker is possible and is not a peer of the path above. A release also publishes hamstrack-<version>.jar and its SHA-256, taken out of the image of the same tag so the two run identical bytes — for an operator who already runs JVM services and is knowingly taking on what the container does (supervision, the heap bound, the JVM locale pins, the management port, the memory ceiling). The list of exactly what that is: Without Docker. It is not the lighter option, and if any item on that list is new to you the container is the better answer.

→ Full walkthrough: Self-hosting guide — complete configuration reference, TLS / reverse proxy, email (SMTP), attachment storage, upgrades and backups.

Documentation & REST API

In-app documentation lives at /docs on every instance (hamstrack.com/docs) — an interactive Swagger UI reference rendered from the OpenAPI spec served at /openapi.yaml (import it into Postman or a code generator directly).

Markdown references per deployment model:

• API reference — Cloud (https://hamstrack.com/api)
• API reference — DC / self-hosted (https://your-host/api)
• Observability guide — logs, metrics, dashboards & alerts (Cloud + DC), backend internals, and the dev setup.

Development

Requirements: Java 21, Docker (PostgreSQL + MailHog for local email), Node is installed automatically by the Maven build.

The development stack (PostgreSQL on port 15432 + MailHog) is a different file from the self-hosted one above — docker-compose.dev.yml, which has to be named explicitly:

docker compose -f docker-compose.dev.yml up -d postgres mailhog

# run the backend + built frontend (http://localhost:8080)
DB_URL=jdbc:postgresql://localhost:15432/hamstrack \
DB_USERNAME=hamstrack DB_PASSWORD=hamstrack \
JWT_SECRET=dev-only-jwt-secret-0123456789abcdef-32b \
./mvnw spring-boot:run

# tests (needs the postgres container)
./mvnw test

# full build → single executable JAR with the frontend inside
./mvnw clean package

Local email (verification links, invites) lands in the MailHog UI at http://localhost:8025. The React frontend lives in src/main/frontend/ and is built into the JAR by frontend-maven-plugin; append -Dfrontend.skip=true to Maven commands to skip it during backend-only iterations.

Stack

Spring Boot / Java 21 · PostgreSQL + Flyway · Spring Security (JWT) · React 19 + TypeScript + Vite · Tailwind CSS v4 · TanStack Query · single-JAR deployment, Docker image published to ghcr.io/zherikhov/hamstrack.

Contributing

Issues and pull requests are welcome. CI runs the full test suite on every PR; deploys to Cloud happen automatically from green builds on main.

License

Hamstrack is source-available under the Elastic License 2.0 (ELv2). ELv2 is not an OSI-approved open-source licence and Hamstrack is not open source: it carries a field-of-use restriction, spelled out below.

You may freely use, copy, modify, and self-host Hamstrack — including for commercial purposes. You may not provide it to third parties as a hosted or managed service, circumvent its license-key functionality, or remove its licensing/copyright notices. See LICENSE for the full terms.