feeblo — Open-source Feedback Board, Roadmaps & Changelogs for your product

Get the Feeblo monorepo running locally — prerequisites, local infra containers, migrations, seed data, and the dev servers.

This page walks you through running the Feeblo monorepo from source so you can hack on the API, dashboard, SDK, or any package. The workflow mirrors the "Getting started" section of the root README.md in .reference/.

This page is based on .reference/README.md, .reference/package.json, packages/db/package.json, and docker/docker-compose.dev.yml.

Prerequisites

Node.js ^26.4.0
pnpm ^11.0.3 (the repo pins packageManager to pnpm@11.0.3)
Docker — optional, but strongly recommended. The local dev infra (Postgres, SMTP, MinIO) runs in containers, and the default .env.example values point at those container ports.

1. Install dependencies

pnpm install

The workspace is a pnpm + Turborepo monorepo; apps/* and packages/* are all workspaces, so a single pnpm install wires everything up.

2. Create your `.env`

cp .env.example .env

The defaults in .env.example are already set up to match the dev containers defined in docker/docker-compose.dev.yml, so you usually don't have to change anything to get a first run going:

Variable	Default	Provided by the dev compose
`DATABASE_URL`	`postgres://feeblo:password@127.0.0.1:54323/feeblo`	`pg` service (port `54323` → `5432`)
`SMTP_HOST` / `SMTP_PORT`	`127.0.0.1` / `1025`	`mailpit` service (Mailpit)
`MEDIA_UPLOAD_ENDPOINT`	`http://127.0.0.1:9002`	`minio` service (S3 API on `9002`)
`MEDIA_UPLOAD_ACCESS_KEY_ID` / `..._SECRET_ACCESS_KEY`	`feeblo` / `password`	MinIO root credentials

AUTH_ENCRYPTION_KEY must stay stable

The example ships AUTH_ENCRYPTION_KEY="secret". This key signs/encrypts sessions — once you have logged in, keep it identical across restarts or everyone's sessions are invalidated. For local-only scratch work the default is fine; never reuse it in production.

3. Start local infrastructure

The dev infra lives in docker docker-compose.dev.yml, exposed through the @feeblo/db package scripts (db:start, db:watch, db:stop, db:down):

pnpm db:start

That docker compose up -d brings up four containers:

feeblo-database — postgres:17-alpine, user/db feeblo, password password, exposed on host port 54323.
feeblo-smtp — axllent/mailpit (Mailpit). SMTP on 1025, web UI on http://localhost:8025.
feeblo-minio — MinIO S3 API on 9002, console on http://localhost:9001, root feeblo / password.
feeblo-mc — a one-shot minio/mc container that creates the feeblo-media-public bucket and sets anonymous download on it, so uploaded media URLs are publicly readable.

4. Run migrations and seed

pnpm db:migrate
pnpm db:seed

db:migrate runs drizzle-kit migrate against DATABASE_URL.
db:seed populates the database with sample data (boards, posts, statuses, reactions, a test user, etc.) and also nukes the database first — it calls nukeDatabase() before seeding. Don't run it against anything you care about.

The seed creates a test user you can log in with during local development — see packages/db/seed.ts for the exact email/password.

5. Run the dev servers

pnpm dev

pnpm dev runs turbo dev across the workspace in parallel — the server and the web app start together. To run them individually:

pnpm dev:server   # API on http://localhost:3000
pnpm dev:web      # Dashboard on http://localhost:3001

Both read environment from ../../.env via dotenvx run -f ../../.env (see apps/server/package.json and apps/web/package.json), so the dev tasks pick up the same .env you created in step 2 — keep it at the repo root, not inside apps/.

Database scripts cheatsheet

pnpm db:* is the main way you interact with the local database. Each is a passthrough to the @feeblo/db package script:

Script	What it does
`pnpm db:start`	`docker compose up -d` — start the dev infra
`pnpm db:watch`	`docker compose up` — same, with logs streaming
`pnpm db:stop`	`docker compose stop` — pause containers
`pnpm db:down`	`docker compose down` — stop and remove containers (volumes kept)
`pnpm db:migrate`	`drizzle-kit migrate` — run pending migrations
`pnpm db:generate`	`drizzle-kit generate` — create a migration from schema changes
`pnpm db:push`	`drizzle-kit push` — push the schema straight to the DB (no migration file)
`pnpm db:studio`	`drizzle-kit studio` — open Drizzle Studio
`pnpm db:seed`	seed sample data (nukes first)
`pnpm db:nuke`	drop and recreate the database (`packages/db/nuke.ts`)

Other useful scripts

Script	Description
`pnpm build`	Build all packages and apps
`pnpm check-types`	Typecheck the whole workspace (`turbo check-types`)
`pnpm format`	Format with Biome (`biome check --write --unsafe .`)
`pnpm check` / `pnpm fix`	Ultracite lint check / autofix

Notes and gotchas

Don't edit .reference/

If you are working inside this docs repo, the Feeblo application code lives under .reference/ as a read-only reference snapshot. Never edit files there. To change Feeblo itself, work in the real Feeblo repository — this folder is only here so the docs stay tethered to the code.

Node version — Feeblo targets Node ^26.4.0. If pnpm dev fails to start, check your node -v; a tool like fnm/nvm helps pin it.
Image vs. source — this page runs Feeblo from source. To run the published images instead, see the self-hosting overview.
OpenAPI — once the server is up, the API is documented at http://localhost:3000/docs (Scalar UI) and GET /health returns OK.

Server

Self-hosting overview

Run Feeblo from the published Docker images instead of from source.

Development setup