Skip to content

README.md

Latest commit

 

History

History
182 lines (138 loc) · 4.3 KB

README.md

File metadata and controls

182 lines (138 loc) · 4.3 KB

Local Music Listings

A service to aggregate local music events from multiple sources, making it easy to discover live shows in Western Massachusetts.

Tech Stack

  • Frontend: Nuxt 4 (Vue 3 + SSR)
  • Backend: Nuxt server routes
  • Database: PostgreSQL + PostGIS
  • ORM: Prisma
  • Scrapers: Playwright + Cheerio
  • Deployment: Docker + DigitalOcean VPS

Local Development

Prerequisites

  • Node.js 20+
  • Docker and Docker Compose
  • npm

Quick Start (with Docker)

  1. Clone the repository and install dependencies:

    git clone <repo-url>
cd local-music
npm install

  2. Start the database services:

    docker compose up -d

  3. Set up the database:

    npm run db:push
npm run db:generate
npm run db:seed

  4. Start the development server:

    npm run dev

Visit http://localhost:3000 to see the app.

Alternative: Local PostgreSQL

If you prefer running PostgreSQL locally:

  1. Create a PostgreSQL database with PostGIS:

    CREATE DATABASE local_music;
\c local_music
CREATE EXTENSION IF NOT EXISTS postgis;

  2. Update .env with your connection string:

    DATABASE_URL="postgresql://user:password@localhost:5432/local_music?schema=public"

  3. Follow steps 3-4 from Quick Start above.

Scripts

Development

  • npm run dev - Start development server
  • npm run build - Build for production
  • npm run preview - Preview production build

Database

  • npm run db:generate - Generate Prisma client
  • npm run db:migrate - Run database migrations
  • npm run db:push - Push schema changes to database
  • npm run db:seed - Seed database with sample data
  • npm run db:studio - Open Prisma Studio

Code Quality

  • npm run lint - Run ESLint
  • npm run lint:fix - Fix ESLint errors
  • npm run format - Format code with Prettier
  • npm run typecheck - Run TypeScript type checking

Production Deployment

Initial Server Setup

  1. Create a DigitalOcean Droplet (Ubuntu 24.04, 2GB RAM minimum)

  2. SSH into the server and run the setup script:

    curl -sSL https://raw.githubusercontent.com/<your-repo>/main/scripts/setup-server.sh | bash

  3. Configure environment variables:

    nano /opt/local-music/.env

    Required variables:

    POSTGRES_PASSWORD=your-secure-password
DOMAIN=your-domain.com
GITHUB_REPOSITORY=your-username/local-music

  4. Copy production files to the server:

    scp docker-compose.prod.yml Caddyfile root@your-server:/opt/local-music/

  5. Update Caddyfile with your domain:

    nano /opt/local-music/Caddyfile
# Replace {$DOMAIN:localhost} with your domain

  6. Start the services:

    cd /opt/local-music
docker compose -f docker-compose.prod.yml up -d

GitHub Actions Deployment

Add these secrets to your GitHub repository:

Secret Description
SERVER_HOST Your server's IP address
SERVER_USER SSH user (e.g., root)
SERVER_SSH_KEY Private SSH key for deployment

Once configured, pushing to main will automatically deploy.

Backup & Restore

Backups run automatically at 2am daily. Manual commands:

# Create backup
./scripts/backup.sh

# Restore from backup
./scripts/restore.sh backups/local_music_20240101_020000.sql.gz

Project Structure

/local-music
├── app/
│   ├── components/     # Vue components
│   ├── composables/    # Vue composables
│   └── pages/          # Nuxt pages
├── server/
│   ├── api/            # API routes
│   ├── scrapers/       # Scraper implementations
│   └── utils/          # Server utilities
├── prisma/
│   ├── schema.prisma   # Database schema
│   └── seed.ts         # Seed script
├── scripts/            # Deployment and maintenance scripts
├── .github/workflows/  # CI/CD pipelines
├── docker-compose.yml  # Local development services
├── docker-compose.prod.yml  # Production services
├── Dockerfile          # App container
├── Caddyfile           # Reverse proxy config
└── PLANNING.md         # Architecture docs

Documentation

See PLANNING.md for architecture decisions, MVP phases, and roadmap.

License

MIT