Getting Started

Prerequisites

• Node.js 22+ (required by engine specification)
• npm (comes with Node.js)
• PostgreSQL 16 (for local development)
  • Can use Docker Compose (recommended)
  • Or a local PostgreSQL installation
• Cloudflare account (optional, needed for Pages/R2 features)

Quick Start

# Clone and install
cd platform
npm install

# Copy environment template
cp .env.example .env

# Start PostgreSQL + Directus + app (main branch)
docker compose up -d

# Run database migrations
npm run db:migrate

# Start dev server
npm run dev

The dev server starts on http://localhost:4321.

Using Docker Compose

The docker-compose.yml provides:

• db — PostgreSQL 16 (port 5432)
• migrations — Run schema migrations (one-shot)
• directus — Directus CMS admin (port 8055) — main only
• schema-setup — Configure Directus schema (one-shot) — main only
• app — The Astro application (port 4321)

Environment Variables

Key variables for local development:

Variable	Default	Notes
DATABASE_URL	postgresql://convertella:@localhost:5432/convertella	Local DB connection
AUTH_SECRET	(required)	Generate with openssl rand -hex 32
RESEND_API_KEY	(required for OTP)	Resend API key

See Environment Variables for the full list.

Working with the spike/cf-runtime Branch

The spike/cf-runtime branch requires a different setup since it targets Cloudflare Workers:

git checkout spike/cf-runtime
npm install
cp .env.example .env
# Edit .env with Neon connection string (DATABASE_URL)
npm run db:migrate
npm run dev

Note: On spike/cf-runtime, npm run dev uses Astro’s dev server (not the Cloudflare adapter). Full Cloudflare Pages simulation requires npm run dev:wrangler.