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

Git, Git LFS, Make, Bash
Node.js 24+, pnpm 10.12.4+
Docker & Docker Compose
PostgreSQL client, jq, curl


# macOS
brew install git git-lfs node pnpm docker postgresql jq curl
 
# Debian/Ubuntu
sudo apt install git git-lfs make nodejs npm docker.io docker-compose postgresql-client jq curl
sudo npm install -g pnpm

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 check-ai - Run lint and typecheck (AI-friendly output)
make test-ai - Run all tests (AI-friendly output)
make test-e2e - Run E2E tests (Playwright)

Package-specific commands (from apps/web):

pnpm dev - Start Next.js dev server only
pnpm payload:migrate:create - Create new migration
pnpm payload:migrate - Run pending migrations
pnpm seed [preset] - Seed development data

Database commands (from project root):

make db-reset - Reset database
make db-shell - PostgreSQL shell
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