mirror of
https://github.com/R0m1k3/podcastic.git
synced 2026-10-11 17:26:20 +02:00
docs: add comprehensive getting started guide and linting configuration
This commit is contained in:
Michael committed
1 parent
068f4e7ef7
commit
d7f158a498
3 files changed
+431
No files matched your search
@@ -0,0 +1,375 @@
|
||||
# 🚀 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
|
||||
```bash
|
||||
cd Podcastic
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### Step 2: Start All Services
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# macOS with Homebrew
|
||||
brew install redis
|
||||
brew services start redis
|
||||
|
||||
# Or use Redis Cloud
|
||||
# https://redis.com/try-free/
|
||||
```
|
||||
|
||||
### Step 1: Environment Configuration
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` with your database credentials:
|
||||
```env
|
||||
NODE_ENV=development
|
||||
MONGODB_URI=mongodb://localhost:27017/podcastic
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
### Step 2: Install Dependencies
|
||||
|
||||
Backend:
|
||||
```bash
|
||||
cd backend
|
||||
npm install
|
||||
```
|
||||
|
||||
Frontend:
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
### Step 3: Run Development Servers
|
||||
|
||||
#### Windows (Batch Script)
|
||||
```bash
|
||||
# From project root
|
||||
dev.bat
|
||||
```
|
||||
|
||||
#### macOS/Linux (Shell Script)
|
||||
```bash
|
||||
# From project root
|
||||
chmod +x dev.sh
|
||||
./dev.sh
|
||||
```
|
||||
|
||||
#### Manual (Split Terminals)
|
||||
Terminal 1 - Backend:
|
||||
```bash
|
||||
cd backend
|
||||
npm run dev
|
||||
# Server runs on http://localhost:5000
|
||||
```
|
||||
|
||||
Terminal 2 - Frontend:
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "test@example.com",
|
||||
"password": "password123",
|
||||
"username": "testuser"
|
||||
}'
|
||||
```
|
||||
|
||||
#### Login
|
||||
```bash
|
||||
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)
|
||||
```bash
|
||||
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)
|
||||
```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)
|
||||
```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
|
||||
```bash
|
||||
# Backend
|
||||
cd backend
|
||||
npm run build
|
||||
|
||||
# Frontend
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Port Already in Use
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
docker-compose build --no-cache
|
||||
|
||||
# Push to registry
|
||||
docker tag podcastic-backend myregistry/podcastic-backend:latest
|
||||
docker push myregistry/podcastic-backend:latest
|
||||
```
|
||||
|
||||
### Manual Build
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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](https://react.dev)
|
||||
- [Express.js Guide](https://expressjs.com)
|
||||
- [MongoDB Docs](https://docs.mongodb.com)
|
||||
- [Tailwind CSS](https://tailwindcss.com)
|
||||
- [Docker Documentation](https://docs.docker.com)
|
||||
|
||||
## ❓ 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
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"env": {
|
||||
"node": true,
|
||||
"es2021": true
|
||||
},
|
||||
"extends": [
|
||||
"eslint:recommended",
|
||||
"plugin:@typescript-eslint/recommended"
|
||||
],
|
||||
"parser": "@typescript-eslint/parser",
|
||||
"parserOptions": {
|
||||
"ecmaVersion": "latest",
|
||||
"sourceType": "module"
|
||||
},
|
||||
"plugins": [
|
||||
"@typescript-eslint"
|
||||
],
|
||||
"rules": {
|
||||
"@typescript-eslint/no-unused-vars": "warn",
|
||||
"@typescript-eslint/no-explicit-any": "warn"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"env": {
|
||||
"browser": true,
|
||||
"es2021": true
|
||||
},
|
||||
"extends": [
|
||||
"eslint:recommended",
|
||||
"plugin:@typescript-eslint/recommended",
|
||||
"plugin:react/recommended",
|
||||
"plugin:react-hooks/recommended"
|
||||
],
|
||||
"parser": "@typescript-eslint/parser",
|
||||
"parserOptions": {
|
||||
"ecmaFeatures": {
|
||||
"jsx": true
|
||||
},
|
||||
"ecmaVersion": "latest",
|
||||
"sourceType": "module"
|
||||
},
|
||||
"plugins": [
|
||||
"@typescript-eslint",
|
||||
"react"
|
||||
],
|
||||
"rules": {
|
||||
"react/react-in-jsx-scope": "off",
|
||||
"@typescript-eslint/no-unused-vars": "warn",
|
||||
"@typescript-eslint/no-explicit-any": "warn"
|
||||
},
|
||||
"settings": {
|
||||
"react": {
|
||||
"version": "detect"
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user