Docs
→
Getting Started
→
Installation

Installation

Current local and Docker installation flow for HeadlessX V2

by saifyxpro

Before you start

Use the current repository layout and commands from the HeadlessX monorepo root.

Recommended versions

  • Node.js 22
  • pnpm 9+
  • PostgreSQL or a hosted Postgres-compatible database
  • Docker and Docker Compose if you want the containerized stack

The package manifests are permissive in a few places, but the project docs and current dev workflow are maintained around Node 22.

Local development setup

1. Clone and install

2. Create .env

At minimum, set these values before booting the stack:

Generate the two security values with:

3. Prepare the database

4. Ensure Camoufox is available

apps/api also attempts this during install, but running it explicitly is the safest path on a fresh machine.

5. Start the stack

That starts:

ServiceDefault URL
Dashboardhttp://localhost:3000
APIhttp://localhost:8000

Verify the installation

API health

Expected shape:

Dashboard access

Open http://localhost:3000, then go to Settings → API Keys and generate a key for external API usage.

First authenticated scrape

Docker setup

Docker support is wired through infra/docker/docker-compose.yml.

1. Create .env

Fill in DATABASE_URL, DASHBOARD_INTERNAL_API_KEY, and CREDENTIAL_ENCRYPTION_KEY before starting the stack.

2. Boot the stack

The containerized stack exposes the same default ports:

  • Dashboard: http://localhost:3000
  • API: http://localhost:8000

Common problems

Web app starts on the wrong port

Use WEB_PORT for the dashboard and PORT for the API. They are separate.

API refuses to boot

The backend now fails fast if either of these is missing:

  • DASHBOARD_INTERNAL_API_KEY
  • CREDENTIAL_ENCRYPTION_KEY

pnpm dev starts but scraping fails

Most local failures after boot are one of these:

  • invalid DATABASE_URL
  • Prisma schema not pushed yet
  • Camoufox not downloaded
  • target site blocking or challenging the request

Frontend loads but cannot talk to the API

Check these values together:

  • NEXT_PUBLIC_API_URL
  • FRONTEND_URL
  • PORT
  • WEB_PORT

Optional setup tasks

Download local CAPTCHA models

Only do this if you need the local model-backed CAPTCHA solving flow:

Next steps