Quick Start Guide

Get TimeTiles running locally in under 5 minutes. This guide is for developers and administrators setting up a local instance.

End users: If TimeTiles is already running and you want to import data, skip to the Getting Started Guide.

Prerequisites

You need the following installed:

Node.js 24+ and pnpm 10.12+
Docker & Docker Compose (for PostgreSQL) — or a local PostgreSQL 17+ with PostGIS
Git and Git LFS
Make
jq and curl for setup and diagnostic scripts
PostgreSQL client tools (psql and pg_isready), including when PostgreSQL runs in Docker

After cloning the repository, use its .mise.toml to install the pinned Node.js and pnpm versions with mise:


mise install

If you manage Node.js and pnpm another way, match the repository’s pinned versions. Install the remaining prerequisites separately; mise install does not install Docker, Git LFS, Make, or PostgreSQL.

Install and Run

Clone the repository


git clone https://github.com/jfilter/timetiles.git
cd timetiles

Run the init command


make init

This single command handles everything: installs dependencies, starts the database, runs migrations, seeds sample data, and starts the development server.

Open the app

Main app: localhost:3000
Admin dashboard: localhost:3000/dashboard
Data import: localhost:3000/ingest

Run make status at any time to check the health of your environment — database, server, and dependencies.

Try It Out

Go to localhost:3000/ingest and drop a CSV file with title, date, and location columns. TimeTiles will detect the schema, geocode addresses, and create an interactive map you can explore.

See the Getting Started Guide for a detailed walkthrough.

Development Commands

Command	What it does
`make dev`	Start the dev server (auto-starts database)
`make check`	Lint and typecheck all packages
`make test`	Run unit and integration tests
`make test-e2e`	Run Playwright E2E tests
`make migrate`	Run pending database migrations
`make seed`	Seed the database with sample data
`make fresh`	Full reset: stop, clean, start database, migrate, seed
`make db-reset`	Reset the database
`make db-shell`	Open a PostgreSQL shell
`make status`	Check environment health
`make help`	List all available commands

make fresh deletes the existing development database before recreating and seeding it. Back up any data you need first.

Fix reported formatting issues with pnpm exec oxfmt <file> on the named files. pnpm format formats all workspace packages without lint autofixes; prefer named files to avoid unrelated changes.

Database Mode

By default, make dev uses Docker for PostgreSQL. To use a local Homebrew PostgreSQL instead, create a .env file:


PG_MODE=local
DATABASE_URL=postgresql://timetiles_user:timetiles_password@localhost:5433/timetiles

make init, make dev, and the database reset/query commands respect this setting. make up, make down, and make logs control Docker Compose directly, regardless of the database mode. Use make ensure-infra to start the configured database and wait for it to become ready.

Troubleshooting

Port 3000 in use:


make kill-dev

Database connection issues:


make status
make ensure-infra

Something broken — start fresh:


make fresh

Next Steps

Getting Started — Import data and create your first dataset
Architecture — Understand the technical design
Development — Contributing, testing, and extending TimeTiles