Local Setup

Prerequisites

Tool	Version	Notes
Node.js	20+	Node 22+ recommended for full Nuxt Content support
pnpm	9+	Used for all JS package management
Docker	Any stable	Used for the admin app database and services
PHP	8.4+	Required to run the admin app outside Docker
Composer	2.x	PHP dependency manager

Installation

Clone the repository and install all JS dependencies from the monorepo root:

git clone https://github.com/ninjasitm/kubuli-monorepo.git
cd kubuli-monorepo
pnpm install

Running the dev servers

pnpm dev

This starts the web, API, admin app, and docs dev processes in a single Turborepo pipeline. It does not provision the admin app's Docker-backed services.

Running individual apps

Web (Nuxt 4)

pnpm dev --filter=web

Runs at http://localhost:3000.

API (HonoX)

Before starting the API, generate the Prisma client:

pnpm --filter=@kubuli/database db:generate
pnpm dev --filter=api

Shared schema migrations are owned by the Laravel admin app. If the schema changed, run the Laravel migration in apps/admin, then sync Prisma with prisma db pull and rerun db:generate. Do not run prisma migrate from packages/database.

Runs at http://localhost:3001.

Admin (Laravel 13 / FrankenPHP)

For the full local admin stack:

pnpm run docker:admin:local:up

This starts the admin app, database, Redis, Horizon, and the other supporting services defined by the local Docker stack.

If you only need the Laravel app process and the supporting services are already running:

cd apps/admin
composer install
composer dev

From the monorepo root, pnpm dev --filter=admin is equivalent to composer dev for the admin app only.

See Admin Workflows for migrations, user bootstrap, and the Docker-vs-app-only workflow details.

Docs (VitePress)

pnpm dev --filter=@kubuli/docs

Runs at http://localhost:4173.

Environment variables

Copy the example files for each app you intend to run:

cp apps/web/.env.example apps/web/.env.local
cp apps/api/.env.example apps/api/.env.local
cp apps/admin/.env.example apps/admin/.env

Key variables

App	Variable	Purpose
web	NUXT_PUBLIC_API_URL	Base URL for API calls from the web client
api	DATABASE_URL	PostgreSQL connection string
admin	APP_URL	Local HTTPS base URL (typically https://localhost)
admin	N8N_API_KEY	n8n API key for ingestion workflow management

Local development defaults

# apps/web/.env.local
NUXT_PUBLIC_API_URL=http://localhost:3001

# apps/api/.env.local
DATABASE_URL=postgresql://postgres:password@localhost:5432/kubuli

Turborepo task reference

# Build all apps and packages
pnpm build

# Build a specific app
pnpm build --filter=web

# Run tests
pnpm test --filter=api

# Lint everything
pnpm lint

# Type-check everything
pnpm type-check