Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/KingPsychopath/oooc-fete-finder/llms.txt

Use this file to discover all available pages before exploring further.

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

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
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:
CommandDescription
pnpm devStart development server with hot reload
pnpm buildBuild the production application
pnpm startStart production server (after build)
pnpm lintRun Biome linter
pnpm lint:fixAuto-fix linting issues
pnpm testRun Vitest tests
pnpm test:watchRun tests in watch mode
pnpm db:cliInteractive database status CLI

​
Troubleshooting

If port 3000 is already in use, you can specify a different port:
pnpm dev -- -p 3001
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)
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
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us