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:

• Podman (preferred) or Docker, with a compose tool (podman compose/docker compose)
• Go 1.24.9+ (for Mill API development)
• Node.js 18+ (for Pillow App 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 Redis and Redpanda (database is remote at db.voltdata.io)
   docker compose up -d redis redpanda
   # Or with Podman:
   podman compose up -d redis redpanda

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 ps || podman compose 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

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

# Note: Database is remote at db.voltdata.io
# No local database setup required

# 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 API health
curl http://localhost:4000/health

# Check frontend is running
curl http://localhost:3000

# Check infrastructure services
docker compose ps || podman compose ps

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 harvesters 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": ["harvester"]
  }'

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.

Sample Data

Quick Testing

Sample data can be loaded by running harvesters or using the API to submit properties.

# Run a harvester to collect real data
cd harvesters/sources/homes-co-nz
export MILL_API_URL="http://localhost:4000"
export MILL_API_KEY="your-token-here"
go run main.go

# Or submit properties via the API (see Mill API documentation)
curl -X POST http://localhost:4000/harvesters/properties/single \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-Harvester-Source: test-source" \
  -d '{...property data...}'

See the Harvesters documentation for more information on data collection.

Setting Up Your First Harvester

Create a simple harvester to collect data:

1. Create harvester directory

# Navigate to harvesters directory
cd harvesters

# Create a new harvester from template
cp -r templates/basic-harvester sources/my-first-harvester

2. Configure the harvester

# Configure the harvester
cd sources/my-first-harvester
nano config.yml

Configure your harvester:

config.yml

name: "my-first-harvester"
source: "example-real-estate-site.com"
schedule: "0 9 * * *" # Daily at 9 AM
rate_limit:
  requests_per_second: 5
regions:
  - "US-CA"
validation:
  required_fields: ["address", "price"]

3. Run your harvester

# Test the harvester
go run main.go --config=config.yml --dry-run

# Run the harvester
go run main.go --config=config.yml

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)
• Harvesters: 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

# Harvester tests
cd harvesters && 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/.env)

mill/config/.env

# Database (remote at db.voltdata.io)
DATABASE_HOST=db.voltdata.io
DATABASE_PORT=9030
DATABASE_USER=your_user
DATABASE_PASSWORD=your_password
DATABASE_NAME=mill

# Redis
REDIS_URL=redis://localhost:6379

# API Configuration
API_PORT=4000
JWT_SECRET=your-jwt-secret-change-this
LOG_LEVEL=info

Pillow App (.env.local)

pillow-app/.env.local

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

Harvester (.env)

harvesters/sources/<harvester>/.env

MILL_API_URL=http://localhost:4000
MILL_API_KEY=your-harvester-token-here

Feature Flags

Enable/disable features using configuration:

config/features.yml

features:
  enable_real_time_updates: true
  enable_market_analytics: true
  enable_saved_searches: true
  enable_price_alerts: true

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

The database is hosted remotely at db.voltdata.io. If you experience connection issues:

# Check network connectivity
ping db.voltdata.io

# Verify database credentials in mill/config/.env
# Check firewall/network settings

Memory Issues

If you’re running out of memory:

• Increase Podman/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 Harvester: Build your first data harvester
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 all services in dev mode
npm run dev

# Start infrastructure only
docker compose up -d redis redpanda || podman compose up -d redis redpanda

# Stop infrastructure
docker compose down || podman compose down

# View logs
docker compose logs -f redis || podman compose logs -f redis

# Run quality checks
npm run check

# Run tests
npm run test

# Lint all components
npm run lint

# Build all components
npm run build

# Run 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.