Development Setup
Development Setup
This guide walks through setting up Cognova for local development from a fresh clone.
Prerequisites
| Tool | Version | Purpose |
|---|---|---|
| Node.js | 20+ | Runtime |
| pnpm | 10+ | Package manager |
| Docker | 24+ | Local PostgreSQL |
| Git | 2.40+ | Version control |
Quick Start
1. Clone the repository
git clone https://github.com/Patrity/cognova.git
cd cognova
2. Install dependencies
pnpm install
node-pty is a native module and will compile during install. If it fails, ensure you have a C++ build toolchain (build-essential on Linux, Xcode CLI tools on macOS).
3. Copy the environment file
cp .env.example .env
Edit .env and set at minimum:
VAULT_PATH=~/vault # Path to your markdown files
BETTER_AUTH_SECRET=<generate-one> # openssl rand -base64 32
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=postgres://postgres:postgres@localhost:5432/cognova
4. Start the database
pnpm db:up
This runs docker compose --profile local up -d db, which starts a PostgreSQL 17 container on port 5432.
5. Push the schema
In development, use db:push to sync the schema directly (no migration files):
pnpm db:push
6. Start the dev server
pnpm dev
The app will be available at http://localhost:3000. On first load, a default admin user is created automatically (see console output for credentials).
Common Commands
| Command | Description |
|---|---|
pnpm dev | Start Nuxt dev server with HMR |
pnpm build | Production build |
pnpm preview | Preview production build locally |
pnpm lint | Run ESLint |
pnpm typecheck | Run TypeScript type checking |
pnpm db:up | Start local PostgreSQL container |
pnpm db:down | Stop local PostgreSQL container |
pnpm db:push | Push schema changes directly (dev) |
pnpm db:generate | Generate a migration file |
pnpm db:migrate | Run pending migrations |
pnpm db:studio | Open Drizzle Studio (DB browser) |
pnpm cli:dev | Run CLI in development mode |
pnpm cli:build | Build the CLI package |
pnpm auth:create-admin | Create an admin user via script |
pnpm auth:reset-pw | Reset a user's password |
Project Structure
cognova/
├── app/ # Frontend (Vue 3, Nuxt 4)
├── server/ # Backend (Nitro, H3)
│ ├── api/ # REST endpoints
│ ├── routes/ # WebSocket handlers
│ ├── services/ # Business logic
│ ├── plugins/ # Startup lifecycle
│ ├── utils/ # Helpers and singletons
│ └── db/ # Schema, migrations, seed
├── shared/types/ # Shared TypeScript types
├── cli/ # CLI workspace package
├── Claude/ # Published Claude Code config
└── docs/ # Internal planning docs
Development Workflow
Making backend changes
- Edit files in
server/-- Nitro auto-reloads on save - If you changed the schema, run
pnpm db:pushto sync - Test via the browser or with
curl
Making frontend changes
- Edit files in
app/-- Vite HMR updates the browser instantly - New components in
app/components/are auto-imported - New composables in
app/composables/are auto-imported
Import conventions
- Frontend code:
~/resolves toapp/ - Server code:
~~/server/for server-internal imports - Shared types:
~~/shared/types
Database schema changes
See the Migrations guide for the full workflow.
Stopping the Environment
# Stop the dev server
Ctrl+C
# Stop the database
pnpm db:down
Troubleshooting
node-pty build fails
Install the C++ build toolchain for your platform:
- macOS:
xcode-select --install - Ubuntu/Debian:
sudo apt install build-essential - Fedora:
sudo dnf groupinstall "Development Tools"
Database connection refused
Ensure the PostgreSQL container is running: docker ps. If not, run pnpm db:up and wait a few seconds for it to initialize.
Port 3000 already in use
Either stop the other process or start Nuxt on a different port:
PORT=3001 pnpm dev