Documentation enhancement

.dockerignore

@@ -0,0 +1,103 @@
+# ============================================================================
+# Docker Ignore
+#
+# Excludes files not needed in Docker builds to reduce image size
+# and improve build performance.
+# ============================================================================
+
+# Dependencies
+node_modules
+bower_components
+
+# Build outputs
+dist
+build
+.next
+.nuxt
+output
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# Documentation
+*.md
+!README.md
+docs
+LICENSE
+
+# Test files
+coverage
+.nyc_output
+*.test.ts
+*.spec.ts
+__tests__
+test
+tests
+*.test.js
+*.spec.js
+
+# Turborepo
+.turbo
+node_modules/.cache
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+migrations
+
+# Environment files (keep .env.example as reference)
+.env
+.env.*
+!.env.example
+
+# Development specific
+.vscode
+.idea
+*.local
+
+# Build config (not needed in final image)
+tsconfig.json
+tsconfig.*.json
+drizzle.config.ts
+betterbase.config.ts
+turbo.json
+
+# Package artifacts
+*.tgz
+*.tar.gz
+
+# CI/CD
+.github
+.gitlab-ci.yml
+.travis.yml
+Jenkinsfile
+azure-pipelines.yml
+
+# Misc
+.cache
+tmp
+temp
+*.pid
+*.seed
+*.pid.lock

.env.example

@@ -0,0 +1,92 @@
+# ============================================================================
+# Betterbase Environment Variables
+#
+# Copy this file to .env and fill in your values.
+# NEVER commit .env to version control!
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# Required: Database
+# ----------------------------------------------------------------------------
+# PostgreSQL connection string (for postgres, neon, supabase)
+# Format: postgresql://user:password@host:port/database
+DATABASE_URL=postgres://user:password@localhost:5432/betterbase
+
+# Or for Neon (serverless PostgreSQL)
+# DATABASE_URL=postgres://user:password@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require
+
+# Or for Turso (libSQL)
+# TURSO_URL=libsql://your-database.turso.io
+# TURSO_AUTH_TOKEN=your-auth-token
+
+# ----------------------------------------------------------------------------
+# Required: Authentication
+# ----------------------------------------------------------------------------
+# Generate a secure secret: openssl rand -base64 32
+AUTH_SECRET=your-super-secret-key-min-32-chars-long-change-in-production
+AUTH_URL=http://localhost:3000
+
+# ----------------------------------------------------------------------------
+# Optional: Storage (S3-compatible)
+# ----------------------------------------------------------------------------
+# Provider: s3, r2, backblaze, minio
+STORAGE_PROVIDER=r2
+STORAGE_BUCKET=betterbase-storage
+STORAGE_REGION=auto
+STORAGE_ENDPOINT=https://your-r2-endpoint.r2.cloudflarestorage.com
+STORAGE_ACCESS_KEY_ID=your-access-key
+STORAGE_SECRET_ACCESS_KEY=your-secret-key
+
+# For local storage (development only)
+# STORAGE_PROVIDER=local
+# STORAGE_PATH=./storage
+
+# ----------------------------------------------------------------------------
+# Optional: Email (SMTP)
+# ----------------------------------------------------------------------------
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=your-smtp-user
+SMTP_PASS=your-smtp-password
+SMTP_FROM=noreply@your-domain.com
+
+# ----------------------------------------------------------------------------
+# Optional: OAuth Providers
+# ----------------------------------------------------------------------------
+# GitHub
+# GITHUB_CLIENT_ID=your-github-client-id
+# GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# Google
+# GOOGLE_CLIENT_ID=your-google-client-id
+# GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# Discord
+# DISCORD_CLIENT_ID=your-discord-client-id
+# DISCORD_CLIENT_SECRET=your-discord-client-secret
+
+# ----------------------------------------------------------------------------
+# Optional: Phone Auth (Twilio)
+# ----------------------------------------------------------------------------
+# TWILIO_ACCOUNT_SID=your-twilio-sid
+# TWILIO_AUTH_TOKEN=your-twilio-token
+# TWILIO_PHONE_NUMBER=+1234567890
+
+# ----------------------------------------------------------------------------
+# Application Settings
+# ----------------------------------------------------------------------------
+NODE_ENV=development
+PORT=3000
+HOST=0.0.0.0
+
+# Comma-separated list of allowed CORS origins
+CORS_ORIGIN=http://localhost:3000,http://localhost:5173
+
+# Logging
+LOG_LEVEL=debug
+
+# ----------------------------------------------------------------------------
+# Vector Search (optional)
+# ----------------------------------------------------------------------------
+# VECTOR_PROVIDER=openai
+# OPENAI_API_KEY=your-openai-api-key

CODEBASE_MAP.md

@@ -309,6 +309,43 @@ betterbase/
 
 ---
 
+## Docker Deployment
+
+Betterbase includes production-ready Docker configuration for self-hosted deployment.
+
+### Docker Files
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Monorepo build (for developing Betterbase itself) |
+| `Dockerfile.project` | Project template for deploying user projects |
+| `docker-compose.yml` | Development environment with PostgreSQL |
+| `docker-compose.production.yml` | Production-ready configuration |
+| `.dockerignore` | Optimizes Docker builds |
+| `.env.example` | Environment variable template |
+
+### Quick Start
+
+```bash
+# Development with Docker Compose
+docker-compose up -d
+
+# Production deployment
+docker-compose -f docker-compose.production.yml up -d
+```
+
+### Docker Features
+
+- **Multi-stage builds** for minimal image size
+- **PostgreSQL** included in dev environment
+- **Health checks** for reliability
+- **Non-root user** for security
+- **Volume mounts** for hot-reload in development
+- **External database support** - Neon, Supabase, RDS, etc.
+- **S3-compatible storage** - R2, S3, B2, MinIO
+
+---
+
 ## Root-Level Files
 
 ### [`package.json`](package.json)

Dockerfile

@@ -0,0 +1,113 @@
+# ============================================================================
+# Betterbase Monorepo Dockerfile
+# 
+# This Dockerfile builds the entire Betterbase monorepo including:
+# - @betterbase/cli
+# - @betterbase/core  
+# - @betterbase/client
+# - @betterbase/shared
+#
+# Usage:
+#   docker build -t betterbase:local .
+#   docker run -p 3000:3000 betterbase:local
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# Stage 1: Base
+# ----------------------------------------------------------------------------
+FROM oven/bun:1.3.9-debian AS base
+
+LABEL maintainer="Betterbase Team"
+LABEL description="AI-Native Backend-as-a-Service Platform"
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    # For sharp image processing
+    vips-tools \
+    fftw3 \
+    libvips \
+    # For PostgreSQL client
+    libpq-dev \
+    # For build tools
+    make \
+    gcc \
+    g++ \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# ----------------------------------------------------------------------------
+# Stage 2: Dependencies
+# ----------------------------------------------------------------------------
+FROM base AS deps
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json bun.lock ./
+COPY turbo.json ./
+
+# Copy workspace package.json files
+COPY packages/cli/package.json packages/cli/
+COPY packages/core/package.json packages/core/
+COPY packages/client/package.json packages/client/
+COPY apps/test-project/package.json apps/test-project/
+
+# Install dependencies
+RUN bun install --frozen-lockfile
+
+# ----------------------------------------------------------------------------
+# Stage 3: Builder
+# ----------------------------------------------------------------------------
+FROM base AS builder
+
+WORKDIR /app
+
+# Copy lockfile and install dependencies
+COPY package.json bun.lock ./
+COPY turbo.json ./
+RUN bun install --frozen-lockfile
+
+# Copy all source code
+COPY packages/ packages/
+COPY apps/ apps/
+
+# Build all packages using turbo
+RUN bun run build
+
+# ----------------------------------------------------------------------------
+# Stage 4: Production Runner
+# ----------------------------------------------------------------------------
+FROM base AS runner
+
+WORKDIR /app
+
+# Copy package files for production
+COPY package.json bun.lock ./
+COPY turbo.json ./
+
+# Install only production dependencies
+RUN bun install --frozen-lockfile --production
+
+# Copy built packages from builder
+COPY --from=builder /app/packages/core/dist ./node_modules/@betterbase/core/dist
+COPY --from=builder /app/packages/cli/dist ./node_modules/@betterbase/cli/dist
+COPY --from=builder /app/packages/client/dist ./node_modules/@betterbase/client/dist
+COPY --from=builder /app/packages/shared/dist ./node_modules/@betterbase/shared/dist
+
+# Copy package.json files to access exports
+COPY packages/core/package.json ./node_modules/@betterbase/core/
+COPY packages/cli/package.json ./node_modules/@betterbase/cli/
+COPY packages/client/package.json ./node_modules/@betterbase/client/
+COPY packages/shared/package.json ./node_modules/@betterbase/shared/
+
+# Set environment
+ENV NODE_ENV=production
+ENV PORT=3000
+
+# Expose port
+EXPOSE 3000
+
+# Default command (should be overridden by project-specific Dockerfiles)
+CMD ["bun", "run", "src/index.ts"]