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.9+ - Required for the Mill API service

  • Download from golang.org
  • Verify: go version

• Node.js 20+ - Required for Pillow App and documentation

  • Download from nodejs.org
  • Verify: node --version and npm --version

• Git - For cloning the repository

  • Download from git-scm.com
  • Verify: git --version

Container Runtime (Optional but Recommended)

Choose one:

• Podman (preferred) - Container runtime that runs in containers
  • Installation: podman.io/getting-started/installation
  • Verify: podman --version
• Docker - Alternative container runtime
  • Installation: docs.docker.com/get-docker
  • Verify: docker --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 and accessing remote database

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, Harvesters, and Geocoding services
• npm packages for Pillow App and Docs
• Development tools (golangci-lint, air, etc.)

Step 3: Configure Environment Variables

Copy and edit the environment files:

# Mill API configuration
cp mill/config/.env.example mill/config/.env

# Pillow App configuration
cp pillow-app/.env.example pillow-app/.env.local

Edit mill/config/.env with your database credentials:

# 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 (local)
REDIS_URL=redis://localhost:6379

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

The pillow-app/.env.local file should already have the correct defaults, but verify:

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

Note: The database is hosted remotely at db.voltdata.io, so no local database setup is required.

Step 4: Start Infrastructure Services

Start Redis using the npm script:

npm run infra

This starts Redis in the background. To stop it later, use npm run infra:stop.

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

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/Podman

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

# Or with Docker
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

The database is hosted remotely. If you have connection issues:

# Test connectivity
ping db.voltdata.io

# Check DNS resolution
nslookup db.voltdata.io

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

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, Node.js, Git)
• Dependencies installed (npm run install:all)
• Environment variables configured
• Infrastructure running (npm run infra)
• 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:

1. Quick Start Guide - Get up and running quickly
2. Configuration Guide - Detailed configuration options
3. API Documentation - Learn about API endpoints
4. Creating a Harvester - 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