Quickstart

Use Bun 1.3.13, pinned in .bun-version and package.json, and Docker Compose for the supplied local services.

1. Install and start PostgreSQL

bun --version
bun install --frozen-lockfile
docker compose up -d postgres

Wait until PostgreSQL is healthy. The Compose service uses local development credentials and port 5432; do not expose it publicly.

2. Initialize a disposable local database

The setup script requires an explicitly exported local DATABASE_URL and the --disposable flag because it changes the schema:

export DATABASE_URL="postgresql://postgres:[email protected]:5432/vibekit"
bun run setup:local --disposable

When .env is missing, it copies .env.example as a starting point, replaces BETTER_AUTH_SECRET and APP_ENCRYPTION_KEY with freshly generated random values, sets MOCK_SERVICES=true, and writes the file with owner-only permissions. It then applies the checked-in migration chain and generates the Prisma client and Zod types. It does not install dependencies or start PostgreSQL. Keep the database URL in .env aligned with the disposable database you chose; an existing .env is preserved. Never print or commit the generated secrets.

If .env already exists, set a local BETTER_AUTH_SECRET of at least 32 characters and MOCK_SERVICES=true yourself. This explicitly selects the offline payment, mail, storage and AI paths. Missing credentials alone do not enable every mock provider, especially in production. Never commit .env.

3. Start the app

bun run dev

The web app is at http://localhost:3000, and documentation is at /docs. Run bun run mail:preview separately for the email preview at http://localhost:3005.

Mock storage supports temporary local uploads and reads during development. To test the S3 integration and its CORS behavior, follow Local MinIO Setup. Mock upload/read routes reject production-mode requests.

4. Verify changes

bun run verify
bun run build
bun run e2e

Use reviewed migrations for deployed databases, as described in Database Migrations. Continue with Configuration.

Optional: connect an AI client

If the site administrator wants read-only AI access, follow MCP setup. Your agent can configure the chosen client and verify a permitted read after the administrator signs in and approves the scopes and teams. Admin access requires explicit admin consent. You can skip this connection and complete normal setup; it does not require a separate auth system.