Setup

Setup

Prerequisites

• Bun (version 1.4.4, as pinned by packageManager in package.json)
• Docker Compose

Installation

1. Install dependencies:

   bun install

2. Start PostgreSQL via Docker Compose:

   bun run db:start

   This starts a PostgreSQL 16 container using the configuration in docker-compose.yml. The database is accessible at localhost:5433 (or the port set by POSTGRES_PORT).

3. Push the database schema:

   bun run db:push

   This uses Drizzle ORM to push the schema defined in the @os/db package to the database.

4. Generate environment types (if needed):

   bun run env:generate

   This reads .env.schema files in each app and package and generates TypeScript types in src/env.ts via varlock. Run this after modifying any .env.schema file.

Development

Run both development servers:

bun run dev

This starts:

• Admin UI (Next.js) at http://localhost:3001
• Server API (Hono + oRPC) at http://localhost:3000

To run them separately:

bun run dev:admin   # Admin UI only
bun run dev:server  # Server API only

Checking the codebase

Run linting, formatting, and TypeScript checking across all workspaces:

bun run check

This command runs ultracite (for linting and formatting) and vp run -r check-types (for TypeScript checking).

Additional notes

• The Docker Compose configuration (docker-compose.yml) defines:
  • postgres: PostgreSQL 16-alpine service, exposing port 5432 internally and mapping to host port 5433 (or custom via POSTGRES_PORT)
  • server: The Hono/oRPC server service, which connects to the database via the DATABASE_URL environment variable
• Environment variables for each app are stored in .env files (e.g., apps/server/.env) and are managed by varlock. The .env.schema files define the expected variables and their types.
• For information on scaffolding new components using the better-t-stack template, see the bts.jsonc file and run bunx create-better-t-stack@latest add.
• Related documentation:
  • Deployment
  • Quickstart
  • Testing checks