Development

Emberly is a Turborepo monorepo using Bun workspaces.

Prerequisites

Tool	Version
Bun	1.3+
Node.js	24+
PostgreSQL	14+
Redis	7+

If you have Docker, this is the quickest way to get PostgreSQL and Redis:

docker run -d --name emberly-postgres -p 5432:5432 \
  -e POSTGRES_USER=emberly -e POSTGRES_PASSWORD=emberly -e POSTGRES_DB=emberly \
  postgres:17-alpine
docker run -d --name emberly-redis -p 6379:6379 redis:7-alpine

Setup

git clone https://github.com/EmberlyOSS/Emberly.git
cd Emberly
bun install
cp .env.example .env

The defaults in .env.example match the containers above. Set AUTH_SECRET to any value; in development a built-in one is used if it's empty.

bun run db:deploy   # apply migrations
bun run dev

Open http://localhost:3000. An empty database sends you to the Setup Wizard.

The background worker runs inside the app unless EMBERLY_RUN_EVENT_WORKER=false.

Layout

apps/
  dashboard/      Emberly web app, API and worker (Next.js)
    app/          Routes and API handlers
    components/
    lib/          Business logic and service clients
    scripts/      Worker and maintenance scripts
  docs/           docs.embrly.ca (Fumadocs)
  bot/            Discord bot
packages/
  db/             Prisma schema, migrations and generated client
  config/         Shared TypeScript and lint config

The root .env is shared. Dashboard scripts load it automatically.

Commands

Run these from the repository root.

Command	What it does
`bun run dev`	Starts the dashboard
`bun run dev:all`	Starts every app through Turbo
`bun run build`	Builds the dashboard
`bun run start`	Runs the built dashboard
`bun run worker`	Runs the background worker on its own
`bun run typecheck`	Type-checks every package
`bun run lint`	Lints every package
`bun run test`	Runs tests
`bun run format`	Formats with Prettier

To work on a single app, run its scripts with --cwd, e.g. bun run --cwd apps/docs dev.

Database

The schema lives in packages/db/prisma/schema.prisma.

Command	What it does
`bun run db:migrate`	Creates a migration from schema changes and applies it
`bun run db:deploy`	Applies existing migrations
`bun run db:generate`	Regenerates the Prisma client
`bun run db:studio`	Opens Prisma Studio
`bun run db:seed`	Creates the Cloud plan catalog (Cloud mode only)

Use db:deploy against staging and production databases, never db:migrate.

Docker Images

The root Dockerfile builds the dashboard and is built from the repository root:

docker build -t emberly .
docker build -t emberly-worker --target worker .

The other apps each have a Dockerfile in their own folder and are built with that folder as the context, e.g. docker build apps/docs.

Flicker

Flicker, the desktop uploader, is a separate repository: EmberlyOSS/Flicker. See the Flicker development guide.