Nebula

Production-ready TypeScript boilerplate.

Nebula ships with a Postgres + Redis + Drizzle stack, observability, and developer tooling pre-wired, so you can skip the setup grind and start building features on day one. This is the empty variant - no auth, email, or SMS modules included, just the core plumbing.

---

Table of Contents

• Stack Overview
• Dependency Injection Container
• Getting Started
• Environment Setup
• Database Commands
• Testing & Validation
• Monitoring
• Port Map
• Quick Start Summary

---

Stack Overview

Layer	Technology
Language	TypeScript
Runtime	Node.js
Framework	Express
Database	PostgreSQL
ORM	Drizzle
Cache / Queue / Sessions	Redis
Validation	Zod
Logging	Pino + request logger middleware, Winston (for Loki)
Rate Limiting	express-rate-limit + Redis-backed store
Testing	Vitest + Supertest
Dev Tooling	Husky, Commitlint, Prettier, ESLint
Containers	Docker + Docker Compose
Monitoring	Prometheus + Grafana + Loki

---

Dependency Injection Container

The project uses a central container to wire application dependencies together:

createContainer()
createServices()
createRepositories()
createValidators()
createMiddlewares()
createControllers()

---

Getting Started

1. Install Dependencies

pnpm install

2. Create Environment Files

For local, non-Docker development:

cp .env.example .env

For Docker-based local/production-like setup, create a Docker environment file:

cp .env.example .env.production.local

Important: The Docker Compose setup reads ./.env.production.local for the app service (env_file: ./.env.production.local).

3. Run in Development Mode

pnpm dev

This starts the app with tsx --watch ./src/index.ts and listens on the configured PORT value from .env (default: 3000).

4. Run a Production Build Locally

Build the app:

pnpm build

Run the compiled server:

PORT=3000 node dist/index.mjs

Or, with a .env file loaded automatically from your shell environment:

node dist/index.mjs

5. Run with Docker

Start the full stack (API + Postgres + Redis + RedisInsight + Prometheus + Grafana + Loki):

docker compose up --build

Run in detached mode:

docker compose up -d

Stop everything:

docker compose down

---

Environment Setup

Copy the example environment file and configure your secrets:

cp .env.example .env

Key values include:

PORT=3000
NODE_ENV=development

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
# DATABASE_URL="postgresql://postgres:postgres@nebula-postgres:5432/postgres" #docker-compose

REDIS_USERNAME=default
REDIS_PASSWORD=default
REDIS_HOST=localhost
# REDIS_HOST=nebula-redis-server #docker-compose
REDIS_PORT=6379

Variable	Purpose
PORT	App server port
NODE_ENV	Runtime environment
DATABASE_URL	PostgreSQL connection string
REDIS_USERNAME	Redis auth username
REDIS_PASSWORD	Redis auth password
REDIS_HOST	Redis connection host
REDIS_PORT	Redis connection port

---

Database Commands

Generate Drizzle schema artifacts:

pnpm db:generate

Apply migrations:

pnpm db:migrate

Push schema directly:

pnpm db:push

Seed data:

pnpm db:seed

---

Testing & Validation

pnpm test
pnpm check:types
pnpm check:lint

---

Monitoring

Setup

1. Ensure Grafana, Prometheus, and Loki are running — Docker Compose brings them up on the ports listed below.
2. From the terraform/ folder, run:

cd terraform
terraform init
terraform plan
terraform apply -auto-approve

Note: The Terraform provider used is the Grafana provider, and the modules rely on JSON dashboard templates in the repo. Terraform creates the dashboard resources in the target Grafana instance.

Viewing Metrics and Logs

This boilerplate wires Prometheus and Grafana together, so you get metrics and logs out of the box when running the Docker stack.

Default Docker Compose UI ports:

Service	URL	Notes
Grafana	http://localhost:3005	Dashboards created by Terraform live here. Default credentials: admin:admin (included Docker image)
Prometheus	http://localhost:9090	Explore metrics, run ad-hoc queries
Loki	http://localhost:3100	Log aggregation
RedisInsight	http://localhost:5540	Inspect Redis data

---

Port Map

Service	Address
App server	http://localhost:3000
↳ Health check	http://localhost:3000/health
↳ Metrics	http://localhost:3000/metrics
PostgreSQL	localhost:5432
Redis	localhost:6379
RedisInsight	http://localhost:5540
Prometheus	http://localhost:9090
Grafana	http://localhost:3005
Loki	http://localhost:3100

---

Quick Start Summary

Shortest path to running the project locally:

pnpm install
cp .env.example .env
pnpm dev

Shortest path to the full Docker stack:

cp .env.example .env.production.local
docker compose up