179 lines
3.9 KiB
Markdown
179 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# Install PostgreSQL
|
|
brew install postgresql@15
|
|
|
|
# Start PostgreSQL service
|
|
brew services start postgresql@15
|
|
|
|
# Verify installation
|
|
psql --version
|
|
```
|
|
|
|
### On Linux:
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
# Create database
|
|
createdb jedmund_cms
|
|
|
|
# Or using psql
|
|
psql -c "CREATE DATABASE jedmund_cms;"
|
|
```
|
|
|
|
3. **Update your `.env` file:**
|
|
|
|
```env
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## Step 5: Test the Setup
|
|
|
|
1. **Check API health:**
|
|
Visit http://localhost:5173/api/health
|
|
|
|
You should see:
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"services": {
|
|
"database": "connected",
|
|
"cloudinary": "not configured"
|
|
}
|
|
}
|
|
```
|
|
|
|
2. **View database:**
|
|
```bash
|
|
npm run db:studio
|
|
```
|
|
This opens Prisma Studio at http://localhost:5555
|
|
|
|
## Testing API Endpoints
|
|
|
|
Since we need authentication, use these curl commands:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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.
|