Installation

This guide will walk you through installing and setting up Pillow on your local machine or server.

Prerequisites

Before installing Pillow, ensure you have the following installed:

Required Software

Go 1.24+ — Required for Mill API and Connectors
- Download from golang.org
- Verify: go version
Node.js 22+ — Required for Pillow App and Docs
- Download from nodejs.org
- Verify: node --version and npm --version
Docker with Docker Compose — Required for local infrastructure
- Installation: docs.docker.com/get-docker
- Verify: docker --version and docker compose version
Git — For cloning the repository
- Download from git-scm.com
- Verify: git --version

System Requirements

Operating System: Linux, macOS, or Windows (with WSL2)
Memory: 8GB RAM minimum (16GB recommended)
Disk Space: 5GB free space
Network: Internet connection for downloading dependencies

Installation Steps

Step 1: Clone the Repository

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

Step 2: Install All Dependencies

From the repository root, run:

npm run install:all

This single command installs everything you need:

Root-level npm dependencies (Turborepo)
Go modules for Mill, Connectors, and Geocoding services
npm packages for Pillow App and Docs
Development tools (golangci-lint, air, etc.)

Step 3: Configure Environment Variables

The default configuration works out of the box for local development. The Mill reads from mill/config/config-local.yaml and the Pillow App uses sensible defaults.

If you need to customize the Pillow App configuration:

cp pillow-app/.env.example pillow-app/.env.local

Verify the defaults:

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

Step 4: Start Infrastructure Services

Start PostgreSQL, Redis, and Redpanda using Docker Compose:

docker compose -f docker-compose.dev.yml up -d

To stop infrastructure later:

docker compose -f docker-compose.dev.yml down

Step 5: Start Development Servers

Start all services in development mode:

npm run dev

This starts:

Mill API on port 4000
Pillow App on port 3000
Documentation on port 4321

Step 6: Verify Installation

Test that all services are running:

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

# Check frontend
curl http://localhost:3000

Post-Installation Setup

1. Create API Tokens

Create tokens for API access and connector submissions:

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

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

2. Test the Installation

Run a simple property search:

# Search for properties
curl "http://localhost:4000/api/v1/properties?limit=5"

# Get property statistics
curl "http://localhost:4000/api/v1/properties/stats"

3. 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

Optional: Libpostal Geocoding Service

For enhanced address parsing, you can set up libpostal:

Using Docker

# Start libpostal service
docker run -d -p 4400:4400 --name libpostal \
  pillow/libpostal-service:latest

Configure Mill to Use Libpostal

Add to mill/config/.env:

MILL_LIBPOSTAL_HOST=localhost
MILL_LIBPOSTAL_PORT=4400

Restart the Mill API to enable libpostal integration.

Troubleshooting

Port Conflicts

If ports 3000, 4000, or 4321 are already in use, update the configuration:

Mill API: Change API_PORT in mill/config/.env
Pillow App: Change PORT in pillow-app/.env.local
Documentation: Change port in docs/astro.config.mjs

Database Connection Issues

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

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

# Restart PostgreSQL
docker compose -f docker-compose.dev.yml restart postgres

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

# Test connectivity
psql -h localhost -U pillow -d pillow -c "SELECT 1"

Go Module Issues

If Go modules fail to download:

# Set Go proxy (if behind firewall)
export GOPROXY=https://proxy.golang.org,direct

# Clear module cache
go clean -modcache

# Re-download modules
go mod download

npm Installation Issues

If npm packages fail to install:

# Clear npm cache
npm cache clean --force

# Reinstall all dependencies
npm run install:all

Memory Issues

If you run out of memory:

Increase container memory limits (8GB+ recommended)
Run services individually: turbo run dev --filter=mill

Verification Checklist

After installation, verify:

All prerequisites installed (Go 1.24+, Node.js 22+, Docker, Git)
Dependencies installed (npm run install:all)
Infrastructure running (docker compose -f docker-compose.dev.yml up -d)
Development servers started (npm run dev)
Mill API responding (curl http://localhost:4000/health)
Pillow App accessible (curl http://localhost:3000)

Next Steps

Now that Pillow is installed:

Quick Start Guide - Get up and running quickly
Configuration Guide - Detailed configuration options
API Documentation - Learn about API endpoints
Creating a Connector - Build your first data collector

Getting Help

If you encounter issues during installation:

📖 Check the Quick Start Guide for common solutions
🐛 Report bugs on GitHub
💬 Ask questions in discussions
📧 Contact support: support@garagejs.com

Production Installation

For production deployments, see the Deployment Guide which covers:

Docker container deployment
Kubernetes orchestration
Cloud platform setup (GCP, AWS, Azure)
Environment configuration
Security best practices
Monitoring and logging