Merge pull request #69 from call-0f-code/local-setup

Containerized api with production data seeding script enabled

Author: i-am-that-guy

.dockerignore

@@ -0,0 +1,81 @@
+# Dependencies
+node_modules
+bun.lockb
+
+# Build outputs
+dist
+build
+.next
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+bun-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# IDE files
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# Docker
+Dockerfile*
+docker-compose*
+.dockerignore
+
+# Documentation and README
+README.md
+*.md
+docs
+
+# Test files
+tests
+__tests__
+*.test.ts
+*.test.js
+*.spec.ts
+*.spec.js
+
+# Development tools
+.eslintrc*
+.prettierrc*
+jest.config*
+tsconfig*.json
+
+# Prisma migrations
+# prisma/migrations
+
+# Temporary files
+tmp
+temp 

.env.example

@@ -8,6 +8,9 @@ DIRECT_URL=
 # Supabase URL
 SUPABASE_URL=
 
+# Session-mode pooler URL — used by setup-local.sh for pg_dump (IPv4-accessible).
+SESSION_POOLER=
+
 # Supabase service role key
 SUPABASE_SERVICE_ROLE_KEY=
 

.gitignore

@@ -12,7 +12,6 @@ report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 # Runtime data
 pids
 *.pid
-*.seed
 *.pid.lock
 
 # Directory for instrumented libs generated by jscoverage/JSCover

Dockerfile

@@ -0,0 +1,55 @@
+FROM oven/bun:1.3 AS base
+WORKDIR /var/www/api
+
+# -----------------------------
+# deps stage - cache dependencies
+# -----------------------------
+FROM base AS deps
+
+COPY package.json bun.lock* ./
+COPY prisma ./prisma
+RUN bun install --frozen-lockfile
+RUN bunx prisma generate
+
+# -----------------------------
+# build stage - compile TypeScript to JavaScript
+# -----------------------------
+FROM deps AS build
+
+COPY . .
+RUN bun build src/server.ts --target=bun --production --outdir dist
+
+# -----------------------------
+# development stage
+# -----------------------------
+FROM deps AS development
+COPY . .
+EXPOSE 3000
+CMD ["bun", "src/server.ts"]
+
+# -----------------------------
+# production stage
+# -----------------------------
+
+    
+FROM oven/bun:1-slim AS production
+
+WORKDIR /var/www/api
+RUN groupadd -g 1001 nodejs && useradd -u 1001 -g nodejs -m bunjs
+
+COPY --from=build --chown=bunjs:nodejs /var/www/api/dist ./dist
+COPY --from=deps --chown=bunjs:nodejs /var/www/api/src/generated ./dist/generated
+
+
+RUN chown -R bunjs:nodejs /var/www/api
+USER bunjs
+
+ENV NODE_ENV=production
+ENV PORT=3000
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget -qO- http://localhost:3000/health || exit 1
+
+CMD ["bun", "./dist/server.js"]

LOCAL_DEVELOPMENT.md

@@ -0,0 +1,54 @@
+# Local Development Environment Setup
+
+This document explains how to set up and manage the local development environment for the COC-API project.
+
+## Prerequisites
+
+- **Docker & Docker Compose**: Ensure you have Docker installed and running.
+- **PostgreSQL Client (`pg_dump`)**: Optional. The current local setup prefers loading a local `seed/dump.sql` file. `pg_dump` is only required if you want to create a fresh dump from a remote database manually.
+
+## Setup Instructions
+
+### 1. Configure Environment Variables
+
+Copy the `.env.example` file to `.env` and fill in the required values:
+
+```bash
+cp .env.example .env
+```
+
+Key variables for the setup script:
+- `SESSION_POOLER`: The direct connection string to your Supabase project (Session Pooler / IPv4).
+  - **Format**: `postgresql://postgres.PROJECT_REF:PASSWORD@aws-0-us-east-1.pooler.supabase.com:5432/postgres`
+
+### 2. Run the Setup Script
+
+The `scripts/setup-local.sh` script automates the local environment bring-up. By default it will load the local `seed/dump.sql` into the local Postgres instance.
+
+```bash
+bun run local
+```
+
+#### What the script does:
+1. **Starts Postgres**: Launches the `db` container.
+2. **Installs Extensions**: Pre-installs `pgcrypto`, `uuid-ossp`, and `pg_stat_statements` into the `public` schema.
+3. **Loads Local Seed**: The script will attempt to load `seed/dump.sql` into the DB only when there are no existing user tables present in the database. If the database already contains tables (non-system tables), the seed step will be skipped to avoid accidentally overwriting existing data. This is the default and recommended local flow.
+4. **Starts the API**: Launches the `api` container and waits for it to be healthy.
+
+Flags:
+  - `--skip-dump`: reuse existing `seed/dump.sql` (no remote dump step)
+  - `--skip-seed`: skip loading the seed and just start containers
+
+### 3. Useful Commands
+
+- **Start environment**: `bash scripts/setup-local.sh`
+- **Skip dump (reuse existing `seed/dump.sql`)**: `bash scripts/setup-local.sh --skip-dump`
+- **Skip seeding (just start containers)**: `bash scripts/setup-local.sh --skip-seed`
+- **View logs**: `docker compose logs -f`
+- **Stop containers**: `docker compose down`
+- **Wipe local data (force re-seed)**: `docker compose down -v`
+
+## Troubleshooting
+
+### Tables not in `public` schema
+The script automatically patches the dump to ensure tables are placed in the `public` schema. If you manually imported a dump, ensure you've installed the required extensions first.

docker-compose.yml

@@ -0,0 +1,45 @@
+services:
+    api:
+        image: coc-api
+        build:
+            context: .
+            dockerfile: Dockerfile
+            target: development
+        ports:
+            - "127.0.0.1:3000:3000"
+        env_file:
+            - .env
+        environment:
+            NODE_ENV: development
+            PORT: 3000
+            DATABASE_URL: "postgresql://postgres:example@db:5432/coc?sslmode=disable"
+        volumes:
+            - ./:/app:cached
+            - /app/node_modules
+        depends_on:
+            - db
+        healthcheck:
+            test: ["CMD", "curl", "-sf", "http://localhost:3000/health"]
+            interval: 30s
+            timeout: 3s
+            retries: 3
+
+    db:
+        image: postgres:17
+        environment:
+            POSTGRES_USER: postgres
+            POSTGRES_PASSWORD: example
+            POSTGRES_DB: coc
+        volumes:
+            - pgdata:/var/lib/postgresql/data
+        ports:
+            - "127.0.0.1:5432:5432"
+        healthcheck:
+            test: ["CMD", "pg_isready", "-U", "postgres", "-d", "coc", "-h", "127.0.0.1", "-p", "5432"]
+            interval: 5s
+            timeout: 5s
+            retries: 5
+
+volumes:
+    pgdata:
+    seed-data:

package.json

@@ -16,7 +16,8 @@
     "precommit": "lint-staged",
     "migrate:first": "bunx prisma migrate dev --name init",
     "migrate": "bunx prisma migrate dev",
-    "generate": "bunx prisma generate"
+    "generate": "bunx prisma generate",
+    "local": "bash scripts/setup-local.sh"
   },
   "repository": {
     "type": "git",