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


# 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

If you use mise, the repo includes a local .mise.toml with the pinned Node.js and pnpm versions:


mise install

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 format`	Format code
`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

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

All make commands respect this setting automatically.

Troubleshooting

Port 3000 in use:


make kill-dev

Database connection issues:


make down && make up

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