openship 0.1.0 → 0.1.1

package/.env.example

@@ -4,13 +4,29 @@
 NODE_ENV=development
 
 # ─── Database ────────────────────────────────
-DATABASE_URL=postgresql://openship:openship@localhost:5432/openship
+# PostgreSQL (Docker / production)
+# DATABASE_URL=postgresql://openship:openship@localhost:5432/openship
+#
+# Leave empty or unset to use PGlite (embedded PostgreSQL, no Docker needed)
+DATABASE_URL=
+
+# PGlite data directory (only used when DATABASE_URL is empty)
+# Defaults to <project-root>/.openship/data if unset
+# PGLITE_DATA_DIR=/var/lib/openship/data
 
 # ─── Redis ───────────────────────────────────
 REDIS_URL=redis://localhost:6379
 
-# ─── Auth ────────────────────────────────────
-JWT_SECRET=change-me-in-production
+# ─── Auth (Better Auth) ─────────────────────
+BETTER_AUTH_SECRET=change-me-in-production
+BETTER_AUTH_URL=http://localhost:4000
+# TRUSTED_ORIGINS=http://localhost:3000,http://localhost:3001
+
+# ─── OAuth (optional) ───────────────────────
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
 
 # ─── Mode ────────────────────────────────────
 # false = self-hosted (no billing)

package/CONTRIBUTING.md

@@ -1,40 +1,90 @@
 # Contributing to Openship
 
-Thank you for your interest in contributing! This guide will help you get started.
+Thanks for your interest in contributing! This guide covers everything you need to get started.
 
 ## Development Setup
 
-1. **Fork & clone** the repository
-2. **Install dependencies**: `pnpm install`
-3. **Set up env**: `cp .env.example .env`
-4. **Generate DB client**: `pnpm db:generate`
-5. **Start dev**: `pnpm dev`
+```bash
+git clone https://github.com/oblien/openship.git
+cd openship
+cp .env.example .env
+bun install
+bun dev
+```
+
+This starts all three services:
+
+| Service     | URL                   |
+| ----------- | --------------------- |
+| Web         | http://localhost:3000  |
+| Dashboard   | http://localhost:3001  |
+| API         | http://localhost:4000  |
+
+To work on a single app:
+
+```bash
+bun dev --filter @repo/api          # API only
+bun dev --filter @repo/dashboard    # Dashboard only
+bun dev --filter @repo/web          # Web only
+```
 
 ## Project Structure
 
-- `apps/*` — Deployable applications (web, dashboard, api, cli)
-- `packages/*` — Shared libraries consumed by apps
-- `tooling/*` — Build and lint configurations
+```
+apps/
+  web/            → Next.js marketing site (port 3000)
+  dashboard/      → Next.js deployment dashboard (port 3001)
+  api/            → Hono API engine (port 4000)
+  cli/            → CLI tool (`openship deploy`)
+
+packages/
+  adapters/       → DockerAdapter (self-host) + OblienAdapter (cloud)
+  core/           → Shared types, constants, utilities, errors
+  db/             → Drizzle ORM schema + client + repositories
+  ui/             → Shared React components (Tailwind)
+```
+
+All apps and packages extend `tsconfig.base.json` at the repo root.
 
 ## Conventions
 
-- **Commits**: Follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, etc.)
+- **Commits**: [Conventional Commits](https://www.conventionalcommits.org/) — `feat:`, `fix:`, `docs:`, `chore:`
 - **Branches**: `feat/`, `fix/`, `docs/`, `chore/`
-- **Code style**: Prettier is configured — run `pnpm format` before committing
-- **Types**: TypeScript strict mode is enabled everywhere
+- **Code style**: Prettier — run `bun format` before committing
+- **Types**: TypeScript strict mode everywhere
 
 ## API Module Pattern
 
-Each API module follows this structure:
+Each API module lives in `apps/api/src/modules/<name>/` and follows this structure:
 
 ```
-modules/<name>/
-  ├── <name>.routes.ts      # Route definitions
-  ├── <name>.controller.ts   # Request handlers
-  ├── <name>.service.ts      # Business logic
-  └── <name>.schema.ts       # Zod validation schemas
+<name>.routes.ts        # Route definitions (Hono)
+<name>.controller.ts    # Request handlers
+<name>.service.ts       # Business logic
+<name>.schema.ts        # TypeBox validation schemas
 ```
 
+Shared modules (auth, projects, deployments, domains, webhooks, health) are always mounted. The `billing` module is **cloud-only** — it's only mounted when `CLOUD_MODE=true` in the environment.
+
+## Adding a Cloud-Only Feature
+
+If you're adding something that should only exist in the cloud version:
+
+1. Gate it behind `CLOUD_MODE` in `apps/api/src/app.ts`
+2. Make any required env vars (like Stripe keys) optional in `apps/api/src/config/env.ts`
+3. Self-hosters should never see 500s from missing cloud config
+
+## Database
+
+```bash
+bun db:generate     # Generate Drizzle migration files from schema
+bun db:push         # Push schema to dev database (no migration file)
+bun db:migrate      # Run pending migrations (production)
+bun db:studio       # Open Drizzle Studio (database browser)
+```
+
+Schema lives in `packages/db/src/schema/`.
+
 ## Need Help?
 
-Open an issue or start a discussion — we're happy to help!
+Open an issue or start a discussion — happy to help!