jedmund-svelte/LOCAL_SETUP.md

Local Development Setup Guide

This guide will help you set up a local development environment for the CMS without needing external services.

Prerequisites

• Node.js 18+ installed
• Homebrew (for macOS)

Step 1: Install PostgreSQL

On macOS:

# Install PostgreSQL
brew install postgresql@15

# Start PostgreSQL service
brew services start postgresql@15

# Verify installation
psql --version

On Linux:

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# Start PostgreSQL
sudo systemctl start postgresql

Step 2: Set Up Local Environment

1. Run the setup script:

   npm run setup:local
   

   This script will:

   • Check PostgreSQL installation
   • Create a .env file from .env.local.example
   • Create the database
   • Run migrations
   • Generate Prisma client

2. If the script fails, manually create the database:

   # Create database
   createdb jedmund_cms
   
   # Or using psql
   psql -c "CREATE DATABASE jedmund_cms;"
   

3. Update your .env file:

   # Use your local PostgreSQL settings
   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/jedmund_cms?schema=public"
   
   # For local dev, leave Cloudinary empty (will use mock data)
   CLOUDINARY_CLOUD_NAME=""
   CLOUDINARY_API_KEY=""
   CLOUDINARY_API_SECRET=""
   
   # Simple admin password for local testing
   ADMIN_PASSWORD="localdev"
   

Step 3: Run Database Migrations

# Generate Prisma client
npx prisma generate

# Run migrations
npm run db:migrate

# Seed with test data
npm run db:seed

Step 4: Start Development Server

npm run dev

Step 5: Test the Setup

1. Check API health: Visit http://localhost:5173/api/health

   You should see:

   {
   	"status": "ok",
   	"services": {
   		"database": "connected",
   		"cloudinary": "not configured"
   	}
   }
   

2. View database:

   npm run db:studio
   

   This opens Prisma Studio at http://localhost:5555

Testing API Endpoints

Since we need authentication, use these curl commands:

# Test health (no auth needed)
curl http://localhost:5173/api/health

# Test media list (with auth)
curl -H "Authorization: Basic $(echo -n 'admin:localdev' | base64)" \
  http://localhost:5173/api/media

# Test project creation
curl -X POST \
  -H "Authorization: Basic $(echo -n 'admin:localdev' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Project","year":2024,"slug":"test-project"}' \
  http://localhost:5173/api/projects

Local Development Notes

1. Media Uploads: Without Cloudinary configured, uploaded images will return mock URLs. The files won't actually be stored anywhere, but the database records will be created for testing.

2. Authentication: Use Basic Auth with username admin and password localdev (or whatever you set in ADMIN_PASSWORD).

3. Database: All data is stored locally in PostgreSQL. You can reset it anytime with:

   npx prisma migrate reset
   

4. Debugging: Check the console for detailed logs. The logger will show all API requests and database queries in development mode.

Troubleshooting

PostgreSQL Connection Issues

• Make sure PostgreSQL is running: brew services list
• Check if the database exists: psql -l
• Try connecting manually: psql -d jedmund_cms

Prisma Issues

• Clear Prisma generated files: rm -rf node_modules/.prisma
• Regenerate: npx prisma generate

Port Already in Use

• Kill the process: lsof -ti:5173 | xargs kill -9
• Or use a different port: npm run dev -- --port 5174

Next Steps

Once local development is working, you can:

1. Start building the admin UI (Phase 3)
2. Test CRUD operations with the API
3. Develop without needing external services

When ready for production, see the deployment guide for setting up Railway and Cloudinary.