Quick Start Guide

Get TimeTiles up and running in minutes. This guide is for developers and administrators who want to set up TimeTiles locally for development or self-hosting.

👤 End users: If you’re looking to import and explore data, see the Getting Started Guide instead.

Prerequisites

Bash
Git
Git LFS
Make
Node.js 24+
pnpm 10.12.4+
Docker and Docker Compose

Quick Start


# Clone the repository
git clone https://github.com/jfilter/timetiles.git
cd timetiles
 
# Single command: setup + database + seed + start dev server
make init

Open http://localhost:3000 to see the application running!

💡 Tip: make init does everything - setup, database initialization, seeding, and starts the dev server. Run make status anytime to check your environment health.

✅ Next Steps: See the Getting Started Guide to learn how to import and explore data.

Development Commands

Monorepo commands (from project root):

make dev - Start all services with database
make test - Run all tests
make check-ai - Run lint and typecheck (AI-friendly)

Package-specific commands (from apps/web):

pnpm dev - Start Next.js dev server only
pnpm payload:generate - Generate TypeScript types
pnpm seed [preset] - Seed development data
pnpm test - Run Vitest tests

Database commands (from project root):

make migrate - Run database migrations
make migrate-create - Create new migration
make seed ARGS="development" - Seed with preset

Docker Commands

make up - Start PostgreSQL
make down - Stop services
make logs - View logs

Troubleshooting

Port 3000 in use


lsof -ti:3000 | xargs kill -9

Database connection issues


make down && make up

Reset everything


make clean && make up