Quick Start (Local Development)

Get your directory platform running locally in under 5 minutes.

Note: We strongly recommend starting by running the platform locally in development mode - it's quick and easy. This allows you to test, configure, and customize everything properly before deploying to production. For production setup (Vercel + Supabase), see Deployment.

Requirements

Bun — Recommended for faster installs and builds (install here)
Docker — For PostgreSQL development database (install here)
Google/GitHub accounts — For OAuth setup (create here)
Stripe account — For payment processing (can start without) (create here)

We use Bun for this project due to faster dependency installation and build times. This tutorial will use Bun commands throughout.

Installation

Clone and install

git clone https://github.com/your-repo/findly-tools
cd findly-tools
bun install

Bun will install dependencies ~10x faster than npm.

Start PostgreSQL with Docker

The project includes a pre-configured PostgreSQL setup for development only:

bun run db:start

This launches postgres:15-alpine container with:

Container: postgres-findlytools
Port: 5432
Database: postgres
User: postgres
Password: mypassword

Additional database commands:

bun run db:stop    # Stop container
bun run db:logs    # View logs
bun run db:reset   # Reset with fresh data

Alternative: Use external PostgreSQL and skip to step 3. (For production, see the deployment guide.)

Configure environment variables

Copy the example file:
```
cp .env.example .env
```
Fill in the required variables for local development. For complete setup instructions, see Environment Variables.
You can start with test credentials for OAuth and Stripe. The platform works for basic testing even if some optional variables are left empty.

What you'll have running

With basic OAuth setup:

User authentication — Google/GitHub sign-in
Directory browsing — View tools and categories
Tool pages — Individual tool detail pages
Admin dashboard — Access at /admin (after setting admin role)

With Stripe configuration:

Tool submission — Submit tools with subscription checkout
Advertisement system — Self-service tool promotion
Subscription management — Plan upgrades/downgrades
Revenue tracking — Admin analytics dashboard

Platform works for testing without Stripe. Add Stripe configuration to enable all revenue features.

Development workflow

# Start database
bun run db:start

# Development server (with Turbopack)
bun run dev

# Database operations
bun run db:studio    # Visual database browser
bun run db:generate  # Create new migrations
bun run db:push      # Apply schema changes

# Production build
bun run build
bun run start

Troubleshooting

Database connection issues:

Check Docker is running: docker ps
Reset database: bun run db:reset

Authentication not working:

Verify OAuth redirect URIs match exactly
Check BETTER_AUTH_SECRET is set

Stripe webhooks failing:

Use Stripe CLI for local testing
Verify webhook secret in .env

Bun installation issues:

Follow official installation guide
Alternative: Use npm or yarn if needed

Next steps

Complete environment setup — Full guide with step-by-step instructions for all services

Customize your platform — Branding, categories, pricing, and more

Deploy to production — Get your directory live on Vercel with Supabase

Ready to configure everything? → Environment Variables

On this page