Ad-block for podcasts. Create an ad-free RSS feed.
## How To Run
You have a few options to get started:
- [](https://railway.com/deploy/podly?referralCode=NMdeg5&utm_medium=integration&utm_source=template&utm_campaign=generic)
- quick and easy setup in the cloud, follow our [Railway deployment guide](docs/how_to_run_railway.md).
- Use this if you want to share your Podly server with others.
- **Run Locally**:
- For local development and customization,
- see our [beginner's guide for running locally](docs/how_to_run_beginners.md).
- Use this for the most cost-optimal & private setup.
- **[Join The Preview Server](https://podly.up.railway.app/)**:
- pay what you want (limited sign ups available)
## How it works:
- You request an episode
- Podly downloads the requested episode
- Whisper transcribes the episode
- LLM labels ad segments
- Podly removes the ad segments
- Podly delivers the ad-free version of the podcast to you
### Cost Breakdown
*Monthly cost breakdown for 5 podcasts*
| Cost | Hosting | Transcription | LLM |
|---------|----------|---------------|--------|
| **free**| local | local | local |
| **$2** | local | local | remote |
| **$5** | local | remote | remote |
| **$10** | public (railway) | remote | remote |
| **Pay What You Want** | [preview server](https://podly.up.railway.app/) | n/a | n/a |
| **$5.99/mo** | https://zeroads.ai/ | production fork of podly | |
## Contributing
See [contributing guide](docs/contributors.md) for local setup & contribution instructions.
================================================
FILE: SECURITY.md
================================================
# Security Policy
## Supported Versions
We only support the latest on main & preview.
## Reporting a Vulnerability
Please use the Private Vulnerability Reporting feature on GitHub:
- Navigate to the Security tab of this repository.
- Select "Vulnerability reporting" from the left-hand sidebar.
- Click "Report a vulnerability" to open a private advisory.
Include as much detail as possible:
- Steps to reproduce.
- Potential impact.
- Any suggested fixes.
This allows us to collaborate with you on a fix in a private workspace before the issue is made public.
================================================
FILE: compose.dev.cpu.yml
================================================
services:
podly:
container_name: podly-pure-podcasts
image: podly-pure-podcasts
volumes:
- ./src/instance:/app/src/instance
env_file:
- ./.env.local
build:
context: .
dockerfile: Dockerfile
args:
- BASE_IMAGE=${BASE_IMAGE:-python:3.11-slim}
- CUDA_VERSION=${CUDA_VERSION:-12.4.1}
- USE_GPU=${USE_GPU:-false}
- USE_GPU_NVIDIA=${USE_GPU_NVIDIA:-false}
- USE_GPU_AMD=${USE_GPU_AMD:-false}
- LITE_BUILD=${LITE_BUILD:-false}
ports:
- "5001:5001"
environment:
- PUID=${PUID:-1000}
- PGID=${PGID:-1000}
- CUDA_VISIBLE_DEVICES=${CUDA_VISIBLE_DEVICES:--1}
- SERVER_THREADS=${SERVER_THREADS:-1}
restart: unless-stopped
healthcheck:
test:
[
"CMD",
"python3",
"-c",
"import urllib.request; urllib.request.urlopen('http://127.0.0.1:5001/')",
]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
networks:
default:
name: podly-pure-podcasts-network
================================================
FILE: compose.dev.nvidia.yml
================================================
services:
podly:
extends:
file: compose.dev.cpu.yml
service: podly
env_file:
- ./.env.local
environment:
- PUID=${PUID:-1000}
- PGID=${PGID:-1000}
- CUDA_VISIBLE_DEVICES=0
- CORS_ORIGINS=*
- SERVER_THREADS=${SERVER_THREADS:-1}
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
networks:
default:
name: podly-pure-podcasts-network
================================================
FILE: compose.dev.rocm.yml
================================================
services:
podly:
extends:
file: compose.dev.cpu.yml
service: podly
env_file:
- ./.env.local
devices:
- /dev/kfd
- /dev/dri
environment:
- PUID=${PUID:-1000}
- PGID=${PGID:-1000}
- CUDA_VISIBLE_DEVICES=${CUDA_VISIBLE_DEVICES:--1}
- CORS_ORIGINS=*
- SERVER_THREADS=${SERVER_THREADS:-1}
# Don't ask me why this is needed for ROCM. See
# https://github.com/openai/whisper/discussions/55#discussioncomment-3714528
- HSA_OVERRIDE_GFX_VERSION=10.3.0
security_opt:
- seccomp=unconfined
networks:
default:
name: podly-pure-podcasts-network
# This would be ideal. Not currently supported, apparently. Or I just wasn't able to figure out the driver arg.
# Tried: amdgpu, amd, rocm
# deploy:
# resources:
# reservations:
# devices:
# - capabilities: [gpu]
# driver: "amdgpu"
# count: 1
================================================
FILE: compose.yml
================================================
services:
podly:
container_name: podly-pure-podcasts
ports:
- "5001:5001"
image: ghcr.io/podly-pure-podcasts/podly-pure-podcasts:${BRANCH:-main-latest}
volumes:
- ./src/instance:/app/src/instance
env_file:
- ./.env.local
environment:
- PUID=${PUID:-1000}
- PGID=${PGID:-1000}
- CUDA_VISIBLE_DEVICES=${CUDA_VISIBLE_DEVICES:--1}
- SERVER_THREADS=${SERVER_THREADS:-1}
restart: unless-stopped
healthcheck:
test:
[
"CMD",
"python3",
"-c",
"import urllib.request; urllib.request.urlopen('http://127.0.0.1:5001/')",
]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
networks:
default:
name: podly-pure-podcasts-network
================================================
FILE: docker-entrypoint.sh
================================================
#!/bin/bash
set -e
# Check if PUID/PGID env variables are set
if [ -n "${PUID}" ] && [ -n "${PGID}" ] && [ "$(id -u)" = "0" ]; then
echo "Using custom UID:GID = ${PUID}:${PGID}"
# Update user/group IDs if needed
usermod -o -u "$PUID" appuser
groupmod -o -g "$PGID" appuser
# Ensure required directories exist
mkdir -p /app/src/instance /app/src/instance/data /app/src/instance/data/in /app/src/instance/data/srv /app/src/instance/config /app/src/instance/db /app/src/instance/logs
# Set permissions for all application directories
APP_DIRS="/home/appuser /app/processing /app/src/instance /app/src/instance/data /app/src/instance/config /app/src/instance/db /app/src/instance/logs /app/scripts"
chown -R appuser:appuser $APP_DIRS 2>/dev/null || true
# Ensure log file exists and has correct permissions in new location
touch /app/src/instance/logs/app.log
chmod 664 /app/src/instance/logs/app.log
chown appuser:appuser /app/src/instance/logs/app.log
# Run as appuser
export HOME=/home/appuser
exec gosu appuser "$@"
else
# Run as current user (but don't assume it's appuser)
exec "$@"
fi
================================================
FILE: docs/contributors.md
================================================
# Contributor Guide
### Quick Start (Docker - recommended for local setup)
1. Make the script executable and run:
```bash
chmod +x run_podly_docker.sh
./run_podly_docker.sh --build
./run_podly_docker.sh # foreground with logs
./run_podly_docker.sh -d # or detached
```
This automatically detects NVIDIA GPUs and uses them if available.
After the server starts:
- Open `http://localhost:5001` in your browser
- Configure settings at `http://localhost:5001/config`
- Add podcast feeds and start processing
## Usage
Once the server is running:
1. Open `http://localhost:5001`
2. Configure settings in the Config page at `http://localhost:5001/config`
3. Add podcast RSS feeds through the web interface
4. Open your podcast app and subscribe to the Podly endpoint (e.g., `http://localhost:5001/feed/1`)
5. Select an episode and download
## Transcription Options
Podly supports multiple options for audio transcription:
1. **Local Whisper (Default)**
- Slower but self-contained
2. **OpenAI Hosted Whisper**
- Fast and accurate; billed per-feed via Stripe
3. **Groq Hosted Whisper**
- Fast and cost-effective
Select your preferred method in the Config page (`/config`).
## Remote Setup
Podly automatically detects reverse proxies and generates appropriate URLs via request headers.
### Reverse Proxy Examples
**Nginx:**
```nginx
server {
listen 443 ssl;
server_name your-domain.com;
location / {
proxy_pass http://localhost:5001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
}
}
```
**Traefik (docker-compose.yml):**
```yaml
labels:
- "traefik.enable=true"
- "traefik.http.routers.podly.rule=Host(`your-domain.com`)"
- "traefik.http.routers.podly.tls.certresolver=letsencrypt"
- "traefik.http.services.podly.loadbalancer.server.port=5001"
```
> **Note**: Most modern reverse proxies automatically set the required headers. No manual configuration is needed in most cases.
### Built-in Authentication
Podly ships with built-in authentication so you can secure feeds without relying on a reverse proxy.
- Set `REQUIRE_AUTH=true` to enable protection. By default it is `false`, preserving existing behaviour.
- When auth is enabled, Podly fails fast on startup unless `PODLY_ADMIN_PASSWORD` is supplied and meets the strength policy (≥12 characters with upper, lower, digit, symbol). Override the initial username with `PODLY_ADMIN_USERNAME` (default `podly_admin`).
- Provide a long, random `PODLY_SECRET_KEY` so Flask sessions remain valid across restarts. If you omit it, the app generates a new key on each boot and all users are signed out.
- On first boot with an empty database, Podly seeds an admin user using the supplied credentials. **If you are enabling auth on an existing install, start from a fresh data volume.**
- After signing in, open the Config page to rotate your password and manage additional users. When you change the admin password, update the corresponding environment variable in your deployment platform so restarts continue to succeed.
- Use the "Copy protected feed" button to generate feed-specific access tokens that are embedded in subscription URLs so podcast clients can authenticate without your primary password. Rate limiting is still applied to repeated authentication failures.
## Ubuntu Service
Add a service file to /etc/systemd/system/podly.service
```
[Unit]
Description=Podly Podcast Service
After=network.target
[Service]
User=yourusername
Group=yourusername
WorkingDirectory=/path/to/your/app
ExecStart=/usr/bin/pipenv run python src/main.py
Restart=always
[Install]
WantedBy=multi-user.target
```
enable the service
```
sudo systemctl daemon-reload
sudo systemctl enable podly.service
```
## Database Update
The database auto-migrates on launch.
To add a migration after data model change:
```bash
pipenv run flask --app ./src/main.py db migrate -m "[change description]"
```
On next launch, the database updates automatically.
## Releases and Commit Messages
This repo uses `semantic-release` to automate versioning and GitHub releases. It relies on
Conventional Commits to determine the next version.
For pull requests, include **at least one** commit that follows the Conventional Commit format:
- `feat: add new episode filter`
- `fix(api): handle empty feed`
- `chore: update dependencies`
If no Conventional Commit is present, the release pipeline will have nothing to publish.
## Docker Support
Podly can be run in Docker with support for both NVIDIA GPU and non-NVIDIA environments.
### Docker Options
```bash
./run_podly_docker.sh --dev # rebuild containers for local changes
./run_podly_docker.sh --production # use published images
./run_podly_docker.sh --lite # smaller image without local Whisper
./run_podly_docker.sh --cpu # force CPU mode
./run_podly_docker.sh --gpu # force GPU mode
./run_podly_docker.sh --build # build only
./run_podly_docker.sh --test-build # test build
./run_podly_docker.sh -d # detached
```
### Development vs Production Modes
**Development Mode** (default):
- Uses local Docker builds
- Requires rebuilding after code changes: `./run_podly_docker.sh --dev`
- Mounts essential directories (config, input/output, database) and live code for development
- Good for: development, testing, customization
**Production Mode**:
- Uses pre-built images from GitHub Container Registry
- No building required - images are pulled automatically
- Same volume mounts as development
- Good for: deployment, quick setup, consistent environments
```bash
# Start with existing local container
./run_podly_docker.sh
# Rebuild and start after making code changes
./run_podly_docker.sh --dev
# Use published images (no local building required)
./run_podly_docker.sh --production
```
### Docker Environment Configuration
**Environment Variables**:
- `PUID`/`PGID`: User/group IDs for file permissions (automatically set by run script)
- `CUDA_VISIBLE_DEVICES`: GPU device selection for CUDA acceleration
- `CORS_ORIGINS`: Backend CORS configuration (defaults to accept requests from any origin)
## FAQ
Q: What does "whitelisted" mean in the UI?
A: It means an episode is eligible for download and ad removal. By default, new episodes are automatically whitelisted (`automatically_whitelist_new_episodes`), and only a limited number of old episodes are auto-whitelisted (`number_of_episodes_to_whitelist_from_archive_of_new_feed`). Adjust these settings in the Config page (/config).
Q: How can I enable whisper GPU acceleration?
A: There are two ways to enable GPU acceleration:
1. **Using Docker**:
- Use the provided Docker setup with `run_podly_docker.sh` which automatically detects and uses NVIDIA GPUs if available
- You can force GPU mode with `./run_podly_docker.sh --gpu` or force CPU mode with `./run_podly_docker.sh --cpu`
2. **In a local environment**:
- Install the CUDA version of PyTorch to your virtual environment:
```bash
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```
## Contributing
We welcome contributions to Podly! Here's how you can help:
### Development Setup
1. Fork the repository
2. Clone your fork:
```bash
git clone https://github.com/yourusername/podly.git
```
3. Create a new branch for your feature:
```bash
git checkout -b feature/your-feature-name
```
4. Create a pull request with a target branch of Preview
#### Application Ports
Both local and Docker deployments provide a consistent experience:
- **Application**: Runs on port 5001 (configurable via web UI at `/config`)
- Serves both the web interface and API endpoints
- Frontend is built as static assets and served by the backend
- **Development**: `run_podly_docker.sh` serves everything on port 5001
- Local script builds frontend to static assets (like Docker)
- Restart `./run_podly_docker.sh` after frontend changes to rebuild assets
#### Development Modes
Both scripts provide equivalent core functionality with some unique features:
**Common Options (work in both scripts)**:
- `-b/--background` or `-d/--detach`: Run in background mode
- `-h/--help`: Show help information
**Local Development**
**Docker Development** (`./run_podly_docker.sh`):
- **Development mode**: `./run_podly_docker.sh --dev` - rebuilds containers with code changes
- **Production mode**: `./run_podly_docker.sh --production` - uses pre-built images
- **Docker-specific options**: `--build`, `--test-build`, `--gpu`, `--cpu`, `--cuda=VERSION`, `--rocm=VERSION`, `--branch=BRANCH`
**Functional Equivalence**:
Both scripts provide the same core user experience:
- Application runs on port 5001 (configurable)
- Frontend served as static assets by Flask backend
- Same web interface and API endpoints
- Compatible background/detached modes
### Running Tests
Before submitting a pull request, you can run the same tests that run in CI:
To prep your pipenv environment to run this script, you will need to first run:
```bash
pipenv install --dev
```
Then, to run the checks,
```bash
scripts/ci.sh
```
This will run all the necessary checks including:
- Type checking with mypy
- Code formatting checks
- Unit tests
- Linting
### Pull Request Process
1. Ensure all tests pass locally
2. Update the documentation if needed
3. Create a Pull Request with a clear description of the changes
4. Link any related issues
### Code Style
- We use black for code formatting
- Type hints are required for all new code
- Follow existing patterns in the codebase
================================================
FILE: docs/how_to_run_beginners.md
================================================
# How To Run: Ultimate Beginner's Guide
This guide will walk you through setting up Podly from scratch using Docker. Podly creates ad-free RSS feeds for podcasts by automatically detecting and removing advertisement segments.
## Highly Recommend!
Want an expert to guide you through the setup? Download an AI powered IDE like cursor https://www.cursor.com/ or windsurf https://windsurf.com/
Most IDEs have a free tier you can use to get started. Alternatively, you can use your own [LLM API key in Cursor](https://docs.cursor.com/settings/api-keys) (you'll need a key for Podly anyways).
Open the AI chat in the IDE. Enable 'Agent' mode if available, which will allow the IDE to help you run commands, view the output, and debug or take corrective steps if necessary.
Paste one of the prompts below into the chat box.
If you don't have the repo downloaded:
```
Help me install docker and run Podly https://github.com/podly-pure-podcasts/podly_pure_podcasts
After the project is cloned, help me:
- install docker & docker compose
- run `./run_podly_docker.sh --build` then `./run_podly_docker.sh -d`
- configure the app via the web UI at http://localhost:5001/config
Be sure to check if a dependency is already installed before downloading.
We recommend Docker because installing ffmpeg & local whisper can be difficult.
The Docker image has both ffmpeg & local whisper preconfigured.
Podly works with many different LLMs, it does not require an OpenAI key.
Check your work by retrieving the index page from localhost:5001 at the end.
```
If you do have the repo pulled, open this file and prompt:
```
Review this project, follow this guide and start Podly on my computer.
Briefly, help me:
- install docker & docker compose
- run `./run_podly_docker.sh --build` and then `./run_podly_docker.sh -d`
- configure the app via the web UI at http://localhost:5001/config
Be sure to check if a dependency is already installed before downloading.
We recommend docker because installing ffmpeg & local whisper can be difficult.
The docker image has both ffmpeg & local whisper preconfigured.
Podly works with many different LLMs; it does not need to work with OpenAI.
Check your work by retrieving the index page from localhost:5001 at the end.
```
## Prerequisites
### Install Docker and Docker Compose
#### On Windows:
1. Download and install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
2. During installation, make sure "Use WSL 2 instead of Hyper-V" is checked
3. Restart your computer when prompted
4. Open Docker Desktop and wait for it to start completely
#### On macOS:
1. Download and install [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/)
2. Drag Docker to your Applications folder
3. Launch Docker Desktop from Applications
4. Follow the setup assistant
#### On Linux (Ubuntu/Debian):
```bash
# Update package index
sudo apt update
# Install Docker
sudo apt install docker.io docker-compose-v2
# Add your user to the docker group
sudo usermod -aG docker $USER
# Log out and log back in for group changes to take effect
```
#### Verify Installation:
Open a terminal/command prompt and run:
```bash
docker --version
docker compose version
```
You should see version information for both commands.
### 2. Get an OpenAI API Key
1. Go to [OpenAI's API platform](https://platform.openai.com/)
2. Sign up for an account or log in if you already have one
3. Navigate to the [API Keys section](https://platform.openai.com/api-keys)
4. Click "Create new secret key"
5. Give it a name (e.g., "Podly")
6. **Important**: Copy the key immediately and save it somewhere safe - you won't be able to see it again!
7. Your API key will look something like: `sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
> **Note**: OpenAI API usage requires payment. Make sure to set up billing and usage limits in your OpenAI account to avoid unexpected charges.
## Setup Podly
### Download the Project
```bash
git clone https://github.com/normand1/podly_pure_podcasts.git
cd podly_pure_podcasts
```
## Running Podly
### Run the Application via Docker
```bash
chmod +x run_podly_docker.sh
./run_podly_docker.sh --build
./run_podly_docker.sh # foreground
./run_podly_docker.sh -d # detached
```
### Optional: Enable Authentication
The Docker image reads environment variables from `.env` files or your shell. To require login:
1. Export the variables before running Podly, or add them to `config/.env`:
```bash
export REQUIRE_AUTH=true
export PODLY_ADMIN_USERNAME='podly_admin'
export PODLY_ADMIN_PASSWORD='SuperSecurePass!2024'
export PODLY_SECRET_KEY='replace-with-a-strong-64-char-secret'
```
2. Start Podly as usual. On first boot with auth enabled and an empty database, the admin account is created automatically. If you are turning auth on for an existing volume, clear the `sqlite3.db` file so the bootstrap can succeed.
3. Sign in at `http://localhost:5001`, then visit the Config page to change your password, add users, and copy RSS URLs with the "Copy protected feed" button. Podly generates feed-specific access tokens and embeds them in the link so podcast players can subscribe without exposing your main password. Remember to update your environment variables whenever you rotate the admin password.
### First Run
1. Docker will download and build the necessary image (this may take 5-15 minutes)
2. Look for "Running on http://0.0.0.0:5001"
3. Open your browser to `http://localhost:5001`
4. Configure settings at `http://localhost:5001/config`
- Alternatively, set secrets via Docker env file `.env.local` in the project root and restart the container. See .env.local.example
## Advanced Options
```bash
# Force CPU-only processing (if you have GPU issues)
./run_podly_docker.sh --cpu
# Force GPU processing
./run_podly_docker.sh --gpu
# Just build the container without running
./run_podly_docker.sh --build
# Test build from scratch (useful for troubleshooting)
./run_podly_docker.sh --test-build
```
## Using Podly
### Adding Your First Podcast
1. In the web interface, look for an "Add Podcast" or similar button
2. Paste the RSS feed URL of your podcast
3. Podly will start processing new episodes automatically
4. Processed episodes will have advertisements removed
### Getting Your Ad-Free RSS Feed
1. After adding a podcast, Podly will generate a new RSS feed URL
2. Use this new URL in your podcast app instead of the original
3. Your podcast app will now download ad-free versions!
## Troubleshooting
### "Docker command not found"
- Make sure Docker Desktop is running
- On Windows, restart your terminal after installing Docker
- On Linux, make sure you logged out and back in after adding yourself to the docker group
### Cannot connect to the Docker daemon. Is the docker daemon running?
- If using docker desktop, open up the app, otherwise start the daemon
### "Permission denied" errors
- On macOS/Linux, make sure the script is executable: `chmod +x run_podly_docker.sh`
- On Windows, try running Command Prompt as Administrator
### OpenAI API errors
- Double-check your API key in the Config page at `/config`
- Make sure you have billing set up in your OpenAI account
- Check your usage limits haven't been exceeded
### Port 5001 already in use
- Another application is using port 5001
- **Docker users**: Either stop that application or modify the port in `compose.dev.cpu.yml` and `compose.yml`
- **Native users**: Change the port in the Config page under App settings
- To kill processes on that port run `lsof -i :5001 | grep LISTEN | awk '{print $2}' | xargs kill -9`
### Out of memory errors
- Close other applications to free up RAM
- Consider using `--cpu` flag if you have limited memory
## Stopping Podly
To stop the application:
If you have launched it in the foreground by omitting the `-d` parameter:
1. In the terminal where Podly is running, press `Ctrl+C`
2. Wait for the container to stop gracefully
If you have launched it in the background using the `-d` parameter:
1. In the terminal where Podly is running, execute `docker compose down`
2. Wait for the container to stop gracefully
In both cases this output should appear to indicate that it has stopped:
```sh
[+] Running 2/2
✔ Container podly-pure-podcasts Removed
✔ Network podly-pure-podcasts-network Removed
```
## Upgrading Podly
To upgrade the application while you are in the terminal where it is running:
1. [Stop it](#stopping-podly)
2. Execute `git pull`
3. [Run it again](#running-podly)
## Getting Help
If you encounter issues ask in our discord, we're friendly!
https://discord.gg/FRB98GtF6N
## What's Next?
Once you have Podly running:
- Explore the web interface to add more podcasts
- Configure settings in the Config page
- Consider setting up automatic background processing
- Enjoy your ad-free podcasts!
================================================
FILE: docs/how_to_run_railway.md
================================================
# How to Run on Railway
This guide will walk you through deploying Podly on Railway using the one-click template.
## 0. Important! Set Budgets
Both Railway and Groq allow you to set budgets on your processing. Set a $10 (minimum possible, expect smaller bill) budget on Railway. Set a $5 budget for Groq.
## 1. Get Free Groq API Key
Podly uses Groq to transcribe podcasts quickly and for free.
1. Go to [https://console.groq.com/keys](https://console.groq.com/keys).
2. Sign up for a free account.
3. Create a new API key.
4. Copy the key and paste it into the `GROQ_API_KEY` field during the Railway deployment.
## 2. Deploy Railway Template
Click the button below to deploy Podly to Railway. This is a sponsored link that supports the project!
[](https://railway.com/deploy/podly?referralCode=NMdeg5&utm_medium=integration&utm_source=template&utm_campaign=generic)
If you want to be a beta-tester, you can deploy the preview branch instead:
[](https://railway.com/deploy/podly-preview?referralCode=NMdeg5&utm_medium=integration&utm_source=template&utm_campaign=generic)
## 3. Configure Networking
After the deployment is complete, you need to expose the service to the internet.
1. Click on the new deployment in your Railway dashboard.
2. Go to the **Settings** tab.
3. Under **Networking**, find the **Public Networking** section and click **Generate Domain**.
4. You can now access Podly at the generated URL.
5. (Optional) To change the domain name, click **Edit** and enter a new name.
## 4. Set Budgets & Expected Pricing
Set a $10 budget on Railway and a $5 budget on Groq (or use the free tier for Groq which will slow processing).
Podly is designed to run efficiently on Railway's hobby plan.
If you process a large volume of podcasts, you can check the **Config** page in your Podly deployment for estimated monthly costs based on your usage.
## 5. Secure Your Deployment
Podly now uses secure session cookies for the web dashboard while keeping HTTP Basic authentication for RSS feeds and audio downloads. Before inviting listeners, secure the app:
1. In the Railway dashboard, open your Podly service and head to **Variables**.
2. Add `REQUIRE_AUTH` with value `true`.
3. Add a strong `PODLY_ADMIN_PASSWORD` (minimum 12 characters including uppercase, lowercase, digit, and symbol). Optionally set `PODLY_ADMIN_USERNAME`.
4. Provide a long, random `PODLY_SECRET_KEY` so session cookies survive restarts. (If you omit it, Podly will generate a new key each deploy and sign everyone out.)
5. Redeploy the service. On first boot Podly seeds the admin user and requires those credentials on every request.
> **Important:** Enabling auth on an existing deployment requires a fresh data volume. Create a new Railway deployment or wipe the existing storage so the initial admin can be seeded.
After signing in, use the Config page to change your password, add additional users, and copy RSS links via the "Copy protected feed" button. Podly issues feed-specific access tokens and embeds them in each URL so listeners can subscribe without knowing your main password. When you rotate passwords, update the corresponding Railway variables so restarts succeed.
## 6. Using Podly
1. Open your new Podly URL in a browser.
2. Navigate to the **Feeds** page.
3. Add the RSS feed URL of a podcast you want to process.
4. Go to your favorite podcast client and subscribe to the new feed URL provided by Podly (e.g., `https://your-podly-app.up.railway.app/feed/1`).
5. Download and enjoy ad-free episodes!
================================================
FILE: docs/todo.txt
================================================
- config audit & testing (advanced and basic)
- move host/port/threads to docker config
reaudit security + testing
ci.sh
test railway
login for public facing
podcast rss search
'basic' config page - just put in groq api key + test + save on populate
also show if api key is set or blank
test hide 'local' whisper in lite build
================================================
FILE: frontend/.gitignore
================================================
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*
node_modules
dist
dist-ssr
*.local
# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
================================================
FILE: frontend/README.md
================================================
# Podly Frontend
This is the React + TypeScript + Vite frontend for Podly. The frontend is built and served as part of the main Podly application.
## Development
The frontend is integrated into the main Podly application and served as static assets by the Flask backend on port 5001.
### Development Workflows
1. **Docker (recommended)**: The Docker build compiles the frontend during image creation and serves static assets from Flask.
2. **Direct Frontend Development**: You can run the frontend development server separately for advanced frontend work:
```bash
cd frontend
npm install
npm run dev
```
This starts the Vite development server on port 5173 with hot reloading and proxies API calls to the backend on port 5001.
### Build Process
- **Direct Development** (`npm run dev`): Vite dev server serves files with hot reloading on port 5173 and proxies API calls to backend on port 5001
- **Docker**: Multi-stage build compiles frontend assets during image creation and copies them to the Flask static directory
## Technology Stack
- **React 18+** with TypeScript
- **Vite** for build tooling and development server
- **Tailwind CSS** for styling
- **React Router** for client-side routing
- **Tanstack Query** for data fetching
## Configuration
The frontend configuration is handled through:
- **Environment Variables**: Set via Vite's environment variable system
- **Vite Config**: `vite.config.ts` for build and development settings
- Development server runs on port 5173
- Proxies API calls to backend on port 5001 (configurable via `BACKEND_TARGET`)
- **Tailwind Config**: `tailwind.config.js` for styling configuration
================================================
FILE: frontend/eslint.config.js
================================================
import js from '@eslint/js'
import globals from 'globals'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import tseslint from 'typescript-eslint'
export default tseslint.config(
{ ignores: ['dist'] },
{
extends: [js.configs.recommended, ...tseslint.configs.recommended],
files: ['**/*.{ts,tsx}'],
languageOptions: {
ecmaVersion: 2020,
globals: globals.browser,
},
plugins: {
'react-hooks': reactHooks,
'react-refresh': reactRefresh,
},
rules: {
...reactHooks.configs.recommended.rules,
'react-refresh/only-export-components': [
'warn',
{ allowConstantExport: true },
],
},
},
)
================================================
FILE: frontend/index.html
================================================
Loading authentication…
{result.author}
)} {result.genres.length > 0 && ({result.genres.join(' · ')}
)}{result.feedUrl}
Episode • {formatTime(duration)}
{currentError ? 'An error occurred. You can report it with logs.' : 'Use this to collect logs for a bug report.'}
{recentEntries
.map((e) => {
const base = `[${formatTs(e.ts)}] ${e.level.toUpperCase()}: ${e.message}`;
if (e.data === undefined) return base;
try {
return base + `\n ${JSON.stringify(e.data)}`;
} catch {
return base;
}
})
.join('\n')}
by {currentFeed.author}
)}by {currentFeed.author}
)}{currentFeed.description.replace(/<[^>]*>/g, '')}
Overrides the global setting. Global default: {autoWhitelistDefaultLabel}.
This feed exceeds your plan's allowance. New episodes will not be processed automatically until you upgrade your plan or leave other feeds.
Enabled episodes are processed by Podly to automatically detect and remove advertisements, giving you a clean, ad-free listening experience.
Disabled episodes are not processed and won't be available for download through Podly. This is useful for episodes you don't want to listen to.
Why whitelist episodes? Processing takes time and computational resources. Enable only the episodes you want to hear to keep your feed focused. This is useful when adding a new feed with a large back catalog.
Failed to load episodes
No episodes found
{currentFeed.title}
{episode.description.replace(/<[^>]*>/g, '').substring(0, 300)}...
{pendingEpisode.title}
{isEstimating && ({estimateError}
)} {!isEstimating && processingEstimate && (Estimated minutes: {processingEstimate.estimated_minutes.toFixed(2)}
{!processingEstimate.can_process && (Processing not available for this episode.
)}No podcast feeds added yet.
Click "Add Feed" to get started.
No podcasts match "{searchTerm}"
by {feed.author}
)}Failed to load processing statistics
| ID | Model | Segment Range | Status | Timestamp | Retries | Actions |
|---|---|---|---|---|---|---|
| {call.id} | {call.model_name} | {call.segment_range} | {call.status} | {formatTimestamp(call.timestamp)} | {call.retry_attempts} | |
|
{call.prompt && (
Prompt:
{call.prompt}
Error Message:
{call.error_message}
Response:
{call.response}
|
| Seq # | Time Range | Label | Text |
|---|---|---|---|
| {segment.sequence_num} | {segment.start_time}s - {segment.end_time}s | {segment.primary_label === 'ad' ? (segment.mixed ? 'Ad (mixed)' : 'Ad') : 'Content'} |
{segment.text}
|
| ID | Segment ID | Time Range | Label | Confidence | Model Call | Text |
|---|---|---|---|---|---|---|
| {identification.id} | {identification.transcript_segment_id} | {identification.segment_start_time}s - {identification.segment_end_time}s | {identification.label === 'ad' ? (identification.mixed ? 'ad (mixed)' : 'ad') : identification.label} | {identification.confidence ? identification.confidence.toFixed(2) : 'N/A'} | {identification.model_call_id} |
{identification.segment_text}
|
Are you sure you want to reprocess this episode? This will delete the existing processed data and start fresh processing.
{/* Action Buttons */}When is Base URL used?
The Base URL is only used for models without a provider prefix. LiteLLM automatically routes provider-prefixed models to their respective APIs.
✅ Base URL is IGNORED for:
groq/openai/gpt-oss-120b → Groq API
anthropic/claude-3.5-sonnet → Anthropic
API
gemini/gemini-3-flash-preview → Google API
gemini/gemini-2.0-flash → Google API
⚙️ Base URL is USED for:
gpt-4o
For the default Groq setup, you don't need to set this.
These fields are controlled by environment variables. Update the referenced variables in your
.env
(or deployment secrets) to make the change persistent. Your manual change will be saved, but will be overwritten if you modify your environment variables in the future.
Managed by {meta.env_var}
{meta?.value_preview && (
({meta.value_preview})
)}
{!meta?.value_preview && meta?.value && (
({meta.value})
)}
Managed by deployment environment
)}{meta.env_var}
);
}
================================================
FILE: frontend/src/components/config/shared/Field.tsx
================================================
import type { ReactNode } from 'react';
import type { EnvOverrideEntry } from '../../../types';
import EnvVarHint from './EnvVarHint';
interface FieldProps {
label: string;
children: ReactNode;
envMeta?: EnvOverrideEntry;
labelWidth?: string;
hint?: string;
}
export default function Field({
label,
children,
envMeta,
labelWidth = 'w-60',
hint,
}: FieldProps) {
return (
);
}
================================================
FILE: frontend/src/components/config/shared/SaveButton.tsx
================================================
interface SaveButtonProps {
onSave: () => void;
isPending: boolean;
className?: string;
}
export default function SaveButton({ onSave, isPending, className = '' }: SaveButtonProps) {
return (
gsk_) and paste it below.
Based on the recommended models: whisper-large-v3-turbo and{' '}
llama-3.3-70b-versatile
* Actual costs may vary based on podcast length, complexity, and token usage. Consider setting a $5-10/month billing limit for safety.
https://your-domain/api/auth/discord/callbackNote: Environment variables (DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, etc.) take precedence over values configured here.
Leave blank for unlimited; set to 0 to block new user creation. Applies only when authentication is enabled.
Pay what you want for the Starter Bundle (10 feeds).
Get 10 feeds for a monthly price of your choice (min ${minAmountDollars.toFixed(2)}).
Error loading feeds. Please try again.
Select a podcast from the list to view details and episodes.
Paste an RSS URL or search the catalog to find shows to follow.
{run ? hasActiveWork ? `Processing · Last update ${formatDateTime(run.updated_at)}` : `Idle · Last activity ${formatDateTime(run.updated_at)}` : 'Jobs Manager has not started yet.'}
{cleanupDisabled ? 'Cleanup is disabled while retention days are unset or zero.' : `Episodes older than ${retentionDays} day${retentionDays === 1 ? '' : 's'} will be removed.`}
{mode === 'active' ? 'Queued and running jobs, ordered by priority.' : 'All jobs ordered by priority (running/pending first).'}
Podly
We're testing a self-hosted podcast ad removal system. Podly transcribes episodes, detects sponsor reads with an LLM, and generates clean RSS feeds that work in any podcast app.
{/* Live user count */}Podly grabs the feed, finds sponsorship blocks, and gives you a private RSS link so your own players stream the ad-free version.
Listen anywhere
Getting started
{landingPageEnabled && (
← Back to home
)}
 }}){kind=logo}
We've moved to a new and improved interface!
You will be automatically redirected to our new UI in 5 seconds.
{% set redirect_url = "http://" + request.host.split(':')[0] + ":5001" %} Go to New UI NowIf you are not redirected automatically, click the button above.