Skip to content

setup.md

Latest commit

 

History

History
168 lines (110 loc) · 4.26 KB

setup.md

File metadata and controls

168 lines (110 loc) · 4.26 KB

HarborPilot Setup Guide

This guide is for developers installing HarborPilot from a public repository.

HarborPilot is not a zero-config hosted app. It installs and builds without private secrets, but the working CRM requires your own database and provider accounts.

What Works Immediately

After cloning the repo, you can:

  • Install dependencies.
  • Run typecheck, lint, audit, and production build.
  • Review the code, migrations, user guide, and environment template.

To run the app in a browser, configure at least Clerk and the database first.

What Requires Configuration

The authenticated CRM workspace requires:

  • Clerk for authentication.
  • Postgres for workspace data.
  • Drizzle migrations applied to that database.

Provider-backed features require additional accounts:

  • Stripe for checkout, billing portal, and webhooks.
  • Composio for per-user Gmail and Google Calendar connections.
  • Cloudflare R2 for private document uploads and signed downloads.
  • Twilio for phone number inventory and communications records.
  • Hostinger only if you want to wire infrastructure automation around that provider.

Prerequisites

  • Node.js 20 or newer.
  • npm.
  • A Postgres database. The app is configured for Neon/Postgres-compatible URLs.
  • A Clerk application.

Optional provider accounts:

  • Stripe.
  • Composio with Gmail and Google Calendar auth configs.
  • Cloudflare R2 bucket and S3-compatible credentials.
  • Twilio.

Local Setup

  1. Clone the repo and install dependencies.
npm ci
  1. Create your local environment file.
cp .env.example .env.local
  1. Fill in the required values in .env.local.

Minimum useful setup:

NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=...
CLERK_SECRET_KEY=...
CLERK_WEBHOOK_SECRET=...
DATABASE_URL=...
  1. Apply database migrations.
node --env-file=.env.local ./node_modules/.bin/tsx scripts/migrate.ts
  1. Verify the database tables.
node --env-file=.env.local ./node_modules/.bin/tsx scripts/verify-db.ts
  1. Start the app.
npm run dev
  1. Open http://localhost:3000, sign in through Clerk, and create the first real contact.

If Clerk is not configured, the app can still build, but sign-in and protected routes will not run correctly.

Provider Setup Notes

Clerk

Create a Clerk app, copy the publishable and secret keys, and configure the webhook endpoint:

http://localhost:3000/api/webhooks/clerk

For production, use your production domain instead of localhost.

Stripe

Set the secret key, publishable key, webhook secret, and optional default Price ID. The billing pages and API routes call Stripe directly; they are not mock links.

Composio

Set COMPOSIO_API_KEY, then configure Gmail and Google Calendar auth configs in Composio. Each HarborPilot user still needs to connect their own Google account from the Integrations page.

R2

Create a Cloudflare R2 bucket and S3-compatible credentials. Documents and file downloads depend on these values.

Twilio

Set the Twilio account SID, auth token, messaging service SID, and default phone number if you want Twilio number sync.

Verification

Run these after setup:

npm run typecheck
npm run lint
npm run build
npm audit

Run these after .env.local is configured:

npm run connections
npm run smoke -- http://localhost:3000
npm run smoke:workflow

npm run smoke:workflow writes temporary records to the configured database and cleans them up.

Production Deployment

HarborPilot is a standard Next.js app. Deploy it to any platform that supports Node.js and Next.js.

Required production steps:

  1. Set all production environment variables in the hosting provider.
  2. Apply migrations against the production database.
  3. Configure Clerk, Stripe, and any provider webhooks to point at the production URL.
  4. Run a production smoke check after deployment.

First User Workflow

After the app is running:

  1. Sign in as the first admin/member user.
  2. Open Contacts.
  3. Create or import contacts.
  4. Create a task or appointment from Calendar.
  5. Upload a document after R2 is configured.
  6. Grant portal access to a client only after that client has signed in with Clerk.

For product usage after installation, read the HarborPilot User Guide.