Quick start

Get OOOC Fête Finder running locally in minutes

Get OOOC Fête Finder up and running on your local machine in just a few minutes. This guide walks you through the essential setup steps to start developing with the app.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18.x or higher

pnpm

Version 8.x or higher

PostgreSQL

Version 14.x or higher

Installation

Follow these steps to get your development environment set up:

1. Clone the repository

   Clone the OOOC Fête Finder repository to your local machine:

   git clone https://github.com/KingPsychopath/oooc-fete-finder.git
   cd oooc-fete-finder
   
2. Install dependencies

   Install all required dependencies using pnpm:

   pnpm install
   

   This will install Next.js, React, Postgres client, and all other dependencies defined in package.json.

3. Configure environment variables

   Create a .env file in the root directory by copying the example file:

   cp .env.example .env
   

   Edit .env and set the required variables:

   # Required - Generate with: openssl rand -base64 32
   AUTH_SECRET="your-random-32-plus-character-secret"
   
   # Required - Your PostgreSQL connection string
   DATABASE_URL="postgresql://user:password@localhost:5432/oooc_fete"
   
   # Required - Data mode (use "remote" for production-like setup)
   DATA_MODE="remote"
   
   # Optional but recommended for full admin access
   ADMIN_KEY="your-admin-password"
   

   Generate a secure AUTH_SECRET using: openssl rand -base64 32

4. Bootstrap the database

   Initialize the Postgres event store with sample data:

   pnpm bootstrap:postgres-store
   

   This script will:

   • Create the required database tables
   • Seed initial event data from CSV
   • Set up the event store schema
5. Start the development server

   Run the Next.js development server:

   pnpm dev
   

   The app will be available at http://localhost:3000

6. Verify the installation

   Open your browser and navigate to:

   • Homepage: http://localhost:3000 - View public event listings
   • Admin: http://localhost:3000/admin - Access admin console (requires ADMIN_KEY)

   If you set an ADMIN_KEY in your environment, you’ll be able to log in to the admin panel and manage events.

Verify your setup

Health check

Run the health check script to verify all systems are working:

pnpm health:check

You should see output confirming:

• ✓ Database connection is active
• ✓ Event store is populated
• ✓ Admin endpoints are accessible

Manual verification

Check these endpoints manually:

# Public homepage (should return event data)
curl http://localhost:3000

# Admin health check (requires ADMIN_KEY)
curl -H "Authorization: Bearer $ADMIN_KEY" http://localhost:3000/api/admin/health

Database check

Use the interactive database CLI to inspect your data:

pnpm db:cli

This will show you:

• Row count and column count
• Store metadata and settings
• Data source status

Optional: Bootstrap featured events

If you want to set up featured event scheduling:

pnpm bootstrap:featured-schedule

This migrates any legacy Featured values from CSV rows into the dedicated featured event scheduler queue.

Development commands

Here are the most common commands you’ll use during development:

Command	Description
pnpm dev	Start development server with hot reload
pnpm build	Build the production application
pnpm start	Start production server (after build)
pnpm lint	Run Biome linter
pnpm lint:fix	Auto-fix linting issues
pnpm test	Run Vitest tests
pnpm test:watch	Run tests in watch mode
pnpm db:cli	Interactive database status CLI

Troubleshooting

Port 3000 is already in use

If port 3000 is already in use, you can specify a different port:

pnpm dev -- -p 3001

Database connection failed

Verify your DATABASE_URL is correct and PostgreSQL is running:

# Check if PostgreSQL is running
psql -h localhost -U your_user -d oooc_fete -c "SELECT 1;"

Common issues:

• PostgreSQL service not running
• Incorrect credentials in DATABASE_URL
• Database does not exist (create it first: createdb oooc_fete)

AUTH_SECRET error

If you see errors about AUTH_SECRET:

1. Ensure it’s set in your .env file
2. Make sure it’s at least 32 characters long
3. Generate a new one: openssl rand -base64 32
4. Restart the dev server after updating .env

DATA_MODE not set

If you see “DATA_MODE is required in production”:

# Add to your .env file
DATA_MODE="remote"

Valid values:

• remote - Use Postgres as primary source (recommended)
• local - Use local CSV files only
• test - Use in-memory test data

Admin access denied

If you can’t access /admin:

1. Ensure ADMIN_KEY is set in .env
2. Clear your browser cookies and try again
3. Check that you’re entering the correct admin password
4. Restart the dev server after setting ADMIN_KEY

Next steps

Now that you have OOOC Fête Finder running locally, explore these guides:

Environment setup

Learn about all available environment variables

Architecture overview

Understand the system architecture

Admin workflow

Learn how to manage events and content

API reference

Explore the public and admin APIs