# CastHarbor

CastHarbor is a podcast hosting platform for publishing, distributing, and analyzing audio shows. It provides feed generation, episode management, private podcast support, embeddable players, and listener analytics for independent creators and production teams.

## Features

- Create and manage multiple podcasts from one account
- Upload, process, and host audio files
- Generate Apple Podcasts and Spotify-compatible RSS feeds
- Schedule episode releases
- Add show notes, transcripts, chapters, and cover art
- Track downloads, listener locations, devices, and retention
- Publish public, private, or team-only podcasts
- Embed responsive audio players on external sites
- Manage collaborators with role-based access
- Configure custom domains and branded podcast pages

## Installation

Clone the repository:

```bash
git clone https://github.com/example/castharbor.git
cd castharbor
```

Install dependencies:

```bash
npm install
```

Copy the example environment file:

```bash
cp .env.example .env
```

Run database migrations:

```bash
npm run db:migrate
```

Start the development server:

```bash
npm run dev
```

The application will be available at:

```text
http://localhost:3000
```

## Usage

Create an admin user:

```bash
npm run users:create-admin
```

Sign in to the dashboard, then create your first podcast by adding:

- Show title
- Description
- Author name
- Language
- Category
- Cover artwork
- Public website URL

Upload an episode from the dashboard or with the CLI:

```bash
npm run episodes:upload -- \
  --podcast "daily-build" \
  --file ./episodes/001-introduction.mp3 \
  --title "Introduction" \
  --publish-at "2026-07-15T09:00:00Z"
```

After publishing, the podcast RSS feed will be available at:

```text
https://your-domain.com/feeds/{podcast-slug}.xml
```

## Configuration

CastHarbor is configured with environment variables.

```env
APP_URL=http://localhost:3000
NODE_ENV=development

DATABASE_URL=postgres://castharbor:password@localhost:5432/castharbor
REDIS_URL=redis://localhost:6379

STORAGE_DRIVER=s3
S3_BUCKET=castharbor-audio
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key

TRANSCODING_ENABLED=true
TRANSCODING_WORKER_CONCURRENCY=2

RSS_CACHE_TTL_SECONDS=300
ANALYTICS_RETENTION_DAYS=730

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=notifications@example.com
SMTP_PASSWORD=your-smtp-password
SMTP_FROM="CastHarbor <notifications@example.com>"

CUSTOM_DOMAINS_ENABLED=true
PRIVATE_FEEDS_ENABLED=true
```

### Required Services

CastHarbor requires:

- Node.js 20 or newer
- PostgreSQL 15 or newer
- Redis 7 or newer
- S3-compatible object storage
- FFmpeg for audio processing

### Production Notes

Before deploying to production:

- Set `NODE_ENV=production`
- Use managed PostgreSQL and Redis instances
- Store audio files in durable object storage
- Configure HTTPS for the app and custom domains
- Run background workers separately from the web process
- Rotate storage, SMTP, and session secrets regularly

## License

MIT