Quick Start Guide

Get up and running with Pillow in minutes! This guide will walk you through setting up a complete development environment and running your first property search.

Prerequisites

Before you begin, make sure you have the following installed:

• Docker with Docker Compose (docker compose)
• Go 1.24+ (for Mill API and Connectors development)
• Node.js 22+ (for Pillow App and Docs development)
• Git (for version control)

Turborepo Monorepo

This is a Turborepo monorepo. Always use npm scripts from the repository root for development tasks:

• npm run install:all - Install all dependencies
• npm run check - Run quality checks (lint + build + test)
• npm run dev - Start all components in dev mode

Installation Methods

Choose the installation method that works best for you:

Turborepo Setup (Recommended)

The fastest way to get started is using the Turborepo monorepo setup:

Steps:

1. Clone the repository

   git clone https://github.com/pillow/pillow.git
   cd pillow

2. Install all dependencies

   npm run install:all

   This installs Go modules, npm packages, and development tools for all workspaces.

3. Start infrastructure services

   # Start PostgreSQL, Redis, and Redpanda
   docker compose -f docker-compose.dev.yml up -d

4. Start development servers

   # Start all components in development mode
   npm run dev

   This starts:

   • Mill API (Go) on port 4000
   • Pillow App (Next.js) on port 3000
   • Documentation site (Astro) on port 4321

5. Verify services are running

   # Check infrastructure
   docker compose -f docker-compose.dev.yml ps
   
   # Check API health
   curl http://localhost:4000/health
   
   # Check frontend
   curl http://localhost:3000

Manual Setup

For development or customization, you can set up services manually.

1. Install Dependencies

# From repository root - installs all dependencies
npm run install:all

2. Mill API Setup

# Navigate to Mill directory
cd mill

# Start infrastructure (PostgreSQL + Redis)
make docker-compose-up

# Start the API server (with hot reload)
make dev
# Or: go run cmd/mill/main.go

The Mill API will be available at:

• API: http://localhost:4000
• OpenAPI docs: http://localhost:4000/swagger/index.html
• Health check: http://localhost:4000/health

3. Pillow App Setup

# Navigate to Pillow App directory
cd pillow-app

# Install dependencies (if not using npm run install:all)
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Start the development server
npm run dev

The frontend will be available at http://localhost:3000

First Steps

1. Verify Installation

Check that all services are running:

# Check infrastructure services
docker compose -f docker-compose.dev.yml ps

# Check API health
curl http://localhost:4000/health

# Check frontend
curl http://localhost:3000

2. Access the Applications

• Pillow App (Frontend): http://localhost:3000
• Mill API: http://localhost:4000
• OpenAPI Documentation: http://localhost:4000/swagger/index.html
• API Health Check: http://localhost:4000/health
• Documentation Site: http://localhost:4321 (when running npm run dev)

3. Create Your First API Token

# Create a service token for connectors or API access
curl -X POST http://localhost:4000/admin/tokens/service \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "test-service",
    "source": "test-source",
    "roles": ["connector"]
  }'

Save the token from the response for use in API requests.

4. Your First Property Search

Try searching for properties using the API:

# Search for properties (no auth required for public endpoints)
curl "http://localhost:4000/api/v1/properties?limit=5"

# Search with filters
curl "http://localhost:4000/api/v1/properties?city=San%20Francisco&limit=5"

# With authentication (if required)
curl -H "Authorization: Bearer your-token" \
  "http://localhost:4000/api/v1/properties?city=San%20Francisco&limit=5"

Or use the web interface at http://localhost:3000 to search visually.

Loading Sample Data

Mill auto-creates sample data on startup when configured (the default for local development). You can also run a connector to collect live data:

# Run the homes.co.nz connector in dry-run mode (scrape but don't submit)
cd connectors
go run . -connector homes-co-nz -mill-api http://localhost:4000 -dry-run

# Run for real (submit scraped data to Mill)
go run . -connector homes-co-nz -mill-api http://localhost:4000

# Or submit a single property via the API
curl -X POST http://localhost:4000/connectors/properties/single \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-Connector-Source: test-source" \
  -d '{
    "title": "Test Property",
    "property_type": "residential",
    "address": { "street": "123 Test St", "city": "Auckland", "country": "New Zealand" },
    "rooms": { "bedrooms_total": 3, "bathrooms_total": 2 }
  }'

See the Connectors documentation for more information on data collection.

Development Workflow

Hot Reloading

All services support hot reloading during development:

• Mill API: Uses air for hot reloading Go code (run make dev from mill/ directory)
• Pillow App: Next.js development server with fast refresh (automatic with npm run dev)
• Connectors: Use go run with file watching or air for hot reloading

Testing

Run tests for all components:

Run All Tests (Turborepo)

# From repository root - runs tests for all workspaces
npm run test

Individual Component Tests

# Mill API tests
cd mill && go test ./...
# Or: make test-unit

# Pillow App tests
cd pillow-app && npm test

# Connector tests
cd connectors && go test ./...

# Integration tests (Mill)
cd mill && make test-integration

Debugging

Mill API Debugging

cd mill

# Enable debug mode
export GIN_MODE=debug
export LOG_LEVEL=debug

# Run with verbose logging
make dev
# Or: go run cmd/mill/main.go

Pillow App Debugging

cd pillow-app

# Run in debug mode (Next.js has built-in debugging)
npm run dev

# Enable React DevTools (browser extension recommended)
# Or use Next.js built-in debugging features

Configuration

Environment Variables

Key environment variables for each service:

Mill API (config/config.yaml)

The Mill reads its config from mill/config/config-local.yaml by default. Key settings:

mill/config/config-local.yaml

database:
  postgres:
    host: "localhost"
    port: 5432
    user: "pillow"
    password: "pillow"
    database: "pillow"
    ssl_mode: "disable"

redis:
  host: "localhost"
  port: 6379

All values can be overridden via environment variables prefixed with MILL_ (e.g. MILL_DATABASE_POSTGRES_HOST).

Pillow App (.env.local)

pillow-app/.env.local

NEXT_PUBLIC_MILL_API=http://localhost:4000
MILL_API=http://localhost:4000
MILL_API_TIMEOUT=10000

Connectors

Connectors receive the Mill API URL and credentials via CLI flags:

go run . -connector homes-co-nz -mill-api http://localhost:4000

Tokens are acquired automatically from the Mill admin endpoint. See Connectors for details.

Common Issues & Solutions

Port Conflicts

If you have port conflicts, change default ports:

• Mill API: 4000 → 4001 (in mill/config/.env)
• Pillow App: 3000 → 3001 (in pillow-app/.env.local)
• Redis: 6379 → 6380 (in docker-compose.yml)

Database Connection Issues

PostgreSQL runs locally via Docker. If you experience connection issues:

# Ensure the container is running
docker compose -f docker-compose.dev.yml ps

# Restart the database
docker compose -f docker-compose.dev.yml restart postgres

# Check the container logs
docker compose -f docker-compose.dev.yml logs postgres

Memory Issues

If you’re running out of memory:

• Increase Docker memory limit (8GB recommended)
• Run services individually instead of all at once
• Use npm run dev --filter=mill to run only specific workspaces

Next Steps

Now that you have Pillow running:

1. Explore the API: Check out the API documentation
2. Customize a View: Learn about view customization
3. Create a Connector: Build your first data connector
4. Deploy: Learn about deployment options

Getting Help

If you run into issues:

• 📖 Check the Configuration Guide
• 🐛 Report bugs
• 💬 Ask questions
• 📧 Email support

Useful Commands

# Install all dependencies
npm run install:all

# Start infrastructure (PostgreSQL, Redis, Redpanda)
docker compose -f docker-compose.dev.yml up -d

# Stop infrastructure
docker compose -f docker-compose.dev.yml down

# Start all services in dev mode
npm run dev

# View infrastructure logs
docker compose -f docker-compose.dev.yml logs -f

# Run quality checks (lint + build + test)
npm run check

# Run tests
npm run test

# Lint all components
npm run lint

# Build all components
npm run build

# Run a specific workspace
turbo run dev --filter=mill
turbo run dev --filter=pillow-app

🏠✨ Happy building with Pillow!

You’re now ready to start developing amazing real estate applications.