podcastic/GETTING_STARTED.md

🚀 Getting Started with Podcastic

Complete guide to set up and run the Podcastic application locally or with Docker.

Prerequisites

For Docker (Recommended)

• Docker 20.10+
• Docker Compose 2.0+
• 4GB RAM minimum

For Local Development

• Node.js 20+ (LTS)
• npm or yarn
• MongoDB 5.0+ (local or MongoDB Atlas)
• Redis 6.0+ (local or Redis Cloud)

🐳 Option 1: Run with Docker Compose (Easiest)

Step 1: Prepare Environment

cd Podcastic
cp .env.example .env

Step 2: Start All Services

docker-compose up -d

Services will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:5000/api
• MongoDB: localhost:27017
• Redis: localhost:6379

Step 3: Access the Application

1. Open http://localhost:3000 in your browser
2. Click "Create Account" to register a new user
3. Log in with your credentials

Common Docker Commands

# View logs
docker-compose logs -f frontend
docker-compose logs -f backend

# Stop services
docker-compose down

# Remove volumes (warning: deletes data!)
docker-compose down -v

# Rebuild images
docker-compose build --no-cache

💻 Option 2: Local Development

Prerequisites Setup

MongoDB

# macOS with Homebrew
brew install mongodb-community
brew services start mongodb-community

# Or use MongoDB Atlas (cloud)
# Sign up at: https://www.mongodb.com/cloud/atlas

Redis

# macOS with Homebrew
brew install redis
brew services start redis

# Or use Redis Cloud
# https://redis.com/try-free/

Step 1: Environment Configuration

cp .env.example .env

Edit .env with your database credentials:

NODE_ENV=development
MONGODB_URI=mongodb://localhost:27017/podcastic
REDIS_URL=redis://localhost:6379

Step 2: Install Dependencies

Backend:

cd backend
npm install

Frontend:

cd frontend
npm install

Step 3: Run Development Servers

Windows (Batch Script)

# From project root
dev.bat

macOS/Linux (Shell Script)

# From project root
chmod +x dev.sh
./dev.sh

Manual (Split Terminals)

Terminal 1 - Backend:

cd backend
npm run dev
# Server runs on http://localhost:5000

Terminal 2 - Frontend:

cd frontend
npm run dev
# Server runs on http://localhost:3000

Step 4: Access the Application

Open http://localhost:3000 in your browser

🧪 Testing the API

Using cURL

Register

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123",
    "username": "testuser"
  }'

Login

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

Get User (Requires Token)

curl -X GET http://localhost:5000/api/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Using Postman

1. Import the API requests from the application
2. Set Bearer tokens in the Authorization tab
3. Test endpoints

📱 Testing Responsive Design

Chrome DevTools

1. Press F12 to open DevTools
2. Click the device toggle icon (top-left)
3. Select different devices to test

Responsive Breakpoints

• Mobile: 320px - 480px
• Tablet: 481px - 1024px
• Desktop: 1025px+

🔧 Configuration Options

Environment Variables

Backend (.env)

# Server
NODE_ENV=development|production
PORT=5000

# Database
MONGODB_URI=mongodb://user:pass@host/db
MONGODB_USER=username
MONGODB_PASSWORD=password

# Cache
REDIS_URL=redis://host:6379

# Authentication
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d
JWT_REFRESH_EXPIRES_IN=30d

# External APIs (Optional)
PODCAST_INDEX_API_KEY=your_key
PODCAST_INDEX_API_SECRET=your_secret

Frontend (.env)

VITE_API_URL=http://localhost:5000/api

📚 Development Workflow

Code Structure

Podcastic/
├── frontend/src/
│   ├── pages/          # Route pages
│   ├── components/     # Reusable components
│   ├── hooks/          # Custom hooks
│   ├── services/       # API services
│   └── styles/         # Global styles
└── backend/src/
    ├── routes/         # API routes
    ├── controllers/    # Business logic
    ├── models/         # MongoDB schemas
    ├── middleware/     # Express middleware
    └── services/       # Service layer

Making Code Changes

Backend Changes:

1. Edit files in backend/src/
2. TypeScript auto-compiles (with npm run dev)
3. Server hot-reloads automatically
4. Check terminal for errors

Frontend Changes:

1. Edit files in frontend/src/
2. Vite hot-reloads in browser automatically
3. Check browser console for errors

Build for Production

# Backend
cd backend
npm run build

# Frontend
cd frontend
npm run build

🐛 Troubleshooting

Port Already in Use

# Find what's using port 3000
lsof -i :3000
# or
netstat -ano | findstr :3000

# Kill the process (on Windows)
taskkill /PID <PID> /F

MongoDB Connection Error

• Ensure MongoDB is running: brew services list
• Check connection string in .env
• Verify credentials if using Atlas

Redis Connection Error

• Ensure Redis is running: brew services list
• Check Redis URL in .env
• Test with: redis-cli ping (should return "PONG")

API 404 Errors

• Verify backend is running on port 5000
• Check frontend proxy configuration in vite.config.ts
• Review VITE_API_URL environment variable

Slow Performance

• Check browser DevTools Network tab
• Use RTK commands for optimized output: rtk npm run dev
• Clear browser cache (Ctrl+Shift+Del)
• Check system RAM usage

📦 Building for Production

Docker Build

docker-compose build --no-cache

# Push to registry
docker tag podcastic-backend myregistry/podcastic-backend:latest
docker push myregistry/podcastic-backend:latest

Manual Build

# Backend
cd backend
npm ci --only=production
npm run build

# Frontend
cd frontend
npm ci --only=production
npm run build

🚀 Deployment

Using Docker

See .env.example for production variables:

docker-compose -f docker-compose.prod.yml up -d

Cloud Deployment

• Heroku: See Procfile (if present)
• AWS: Use ECR + ECS
• DigitalOcean: Use App Platform
• Render: Connect GitHub repo

📖 Additional Resources

• React Documentation
• Express.js Guide
• MongoDB Docs
• Tailwind CSS
• Docker Documentation

❓ FAQ

Q: Can I use SQLite instead of MongoDB? A: Not currently, but can be added. Requires schema changes.

Q: How do I add more podcasts? A: Currently via manual RSS URL addition. PodcastIndex API search coming soon.

Q: Can I deploy to Vercel/Netlify? A: Frontend yes (static), backend no (needs server runtime).

Q: How is the audio streamed? A: Direct HTTP range requests - no downloads to disk.

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Test thoroughly
4. Commit with descriptive messages
5. Push and create PR

📝 License

MIT - See LICENSE file

---

Need help? Check existing GitHub issues or create a new one.

Last updated: 2026-04-16