Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Bun

Version 1.3.10 or later
curl -fsSL https://bun.sh/install | bash

Node.js

Version 24.14.0 or later (optional, if not using Bun runtime)
# Using nvm
nvm install 24.14.0

PostgreSQL

Version 17 or later (can use Docker)
# Via Docker Compose (recommended)
bun compose:up

Git

Any recent version
git --version

​
Installation

1

Clone the repository

Clone the BE Monorepo template to your local machine:
git clone https://github.com/rifandani/be-monorepo.git
cd be-monorepo
The repository uses exact versioning for all dependencies to ensure reproducible builds.
2

Install dependencies

Install all workspace dependencies using Bun:
bun install
This command installs dependencies for all apps and packages in the monorepo. The bunfig.toml configuration ensures exact versions and isolated linking.
Installation typically takes 30-60 seconds depending on your internet connection.
3

Start infrastructure services

Start PostgreSQL, Redis, and the Grafana observability stack using Docker Compose:
bun compose:up
This command starts:
  • PostgreSQL on port 5432 (database)
  • Redis on port 6379 (caching)
  • Grafana LGTM on port 3111 (observability dashboard)
  • OTLP Receiver on ports 4317/4318 (telemetry collection)
Make sure ports 5432, 6379, 3111, 4317, and 4318 are not already in use.
4

Configure environment variables

Copy the example environment file and configure your settings:
cp apps/hono/.env.example apps/hono/.env.dev
Update apps/hono/.env.dev with your configuration:
apps/hono/.env.dev
# APP
APP_TITLE="Hono API"
APP_URL=http://localhost:3333

# DATABASE
DATABASE_URL="postgres://postgres_db:postgres_db@localhost:5432/postgres_db"

# BETTER AUTH
BETTER_AUTH_SECRET="your-secret-key-here"

# OTEL
OTEL_LOG_LEVEL="INFO"
Generate a secure secret for BETTER_AUTH_SECRET using:
openssl rand -base64 32
5

Set up the database

Push the database schema to create tables:
bun hono db:push
This command uses Drizzle Kit to synchronize your database schema with the definitions in apps/hono/src/db/schema.ts.Expected output:
✔ Schema pushed successfully
✔ Created tables: users, sessions, accounts, verifications
To view your database schema in a UI, run bun hono db:studio and visit http://localhost:3003.
6

Start the development server

Launch the Hono API server with hot reload:
bun hono dev
Expected output:
$ bun run --env-file=.env.dev --hot --preload src/instrumentation.ts src/bun.ts

🚀 Server is running on http://localhost:3333
📚 OpenAPI docs: http://localhost:3333/openapi/docs
Your API is now running! The --hot flag enables automatic reload when you save files.

​
Verify the installation

Make a test request to the health check endpoint:
curl http://localhost:3333/health
Expected response:
{
  "status": "ok",
  "timestamp": "2026-03-04T10:30:00.000Z"
}
Visit the OpenAPI documentation in your browser:
http://localhost:3333/openapi/docs
You’ll see an interactive API reference powered by Scalar. You can test endpoints directly from the documentation.
Access the Grafana dashboard to view traces and metrics:
http://localhost:3111
Login credentials:
  • Username: admin
  • Password: admin
The dashboard shows request traces, performance metrics, logs, and profiling data collected via OpenTelemetry.

​
Available scripts

The monorepo provides several utility scripts defined in package.json: 
# Development
bun hono dev              # Start Hono with Bun runtime
bun hono node:dev         # Start Hono with Node.js runtime

# Database
bun hono db:push          # Push schema changes to database
bun hono db:gen           # Generate migration files
bun hono db:migrate       # Run migrations
bun hono db:studio        # Open Drizzle Studio UI

# Authentication
bun hono auth:gen         # Generate auth schema from Better Auth

# Testing & Quality
bun hono test             # Run tests
bun hono typecheck        # Type check without emitting
bun lint                  # Lint all workspaces
bun lint:fix              # Fix linting issues
bun format                # Format code with Biome

# Infrastructure
bun compose:up            # Start Docker services

# Maintenance
bun clean                 # Remove all build artifacts and node_modules
bun bump:deps             # Check for dependency updates

​
Alternative: Node.js runtime

If you prefer Node.js over Bun runtime, use these commands instead:
1

Start with Node.js

bun hono node:dev
This uses tsx to run TypeScript with Node.js and watch for changes.
2

Build for production

bun hono node:build:prod
Compiles TypeScript to JavaScript in the dist folder.
3

Run production build

bun hono node:start:prod
Starts the compiled application with production environment variables.
All database, testing, and utility commands work the same regardless of which runtime you choose.

​
Next steps

Now that your backend is running, explore the project structure and learn how to add new features:

Project structure

Learn about the monorepo organization and file structure

Database schema

Understand the database schema and how to modify it

Authentication

Configure authentication and user management

Add endpoints

Create new API routes with OpenAPI documentation
Important: Never commit .env.dev or .env.prod files to version control. The .gitignore already excludes these files.

Build docs developers (and LLMs) love

Get started for freeTalk to us